@vgai/engine 0.2.0

package/src/render/render-features.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+
+/**
+ * The render-feature registry — single source of truth for every togglable render
+ * setting. The scene schema (`SceneEnvironment.rendering`, `SceneEntity.render`),
+ * the cascade resolver (`resolveRenderSettings`), the editor UI, and the stats
+ * overlay are all derived from this list, so "everything togglable" stays
+ * consistent by construction (same posture as the component/material/instancer
+ * registries). Adding a feature here gives it a schema field + cascade entry for
+ * free. See docs/research/RENDER-SETTINGS-UX.md.
+ */
+
+export type RenderFeatureValue = boolean | number | string;
+
+export interface RenderFeature {
+  /** Stable key used in schema, cascade, and UI. */
+  key: string;
+  /** Editor display label. */
+  label: string;
+  /** Schema `.describe()` text (powers JSON Schema / inspector docs). */
+  description: string;
+  /** Control shape. */
+  kind: 'toggle' | 'number' | 'enum';
+  /** Engine default — the "fast by default" baseline. */
+  default: RenderFeatureValue;
+  /**
+   * `live` re-applies on change; `reload` needs a renderer re-init (e.g. backend,
+   * antialias). The editor badges `reload` features and re-inits the viewport.
+   */
+  apply: 'live' | 'reload';
+  /** Whether this feature may be overridden per-entity (the entity cascade layer). */
+  perEntity: boolean;
+  /** Allowed values for `enum` kind. */
+  options?: readonly string[];
+  /** [min, max] for `number` kind. */
+  range?: readonly [number, number];
+}
+
+export const RENDER_FEATURES: readonly RenderFeature[] = [
+  {
+    key: 'autoBatch',
+    label: 'Auto-batching',
+    description:
+      'Automatically batch entities sharing geometry+material into one draw call (InstancedMesh/BatchedMesh) while keeping each Object3D as the handle. The headline perf win; opt out per-entity for custom-shader/skinned meshes.',
+    kind: 'toggle',
+    default: true,
+    apply: 'live',
+    perEntity: true,
+  },
+  {
+    key: 'frustumCulling',
+    label: 'Frustum culling',
+    description: 'Per-instance frustum culling for batched content.',
+    kind: 'toggle',
+    default: true,
+    apply: 'live',
+    perEntity: true,
+  },
+  {
+    key: 'lod',
+    label: 'Level of detail',
+    description: 'Distance-based geometry swap (LOD) for eligible entities.',
+    kind: 'toggle',
+    default: true,
+    apply: 'live',
+    perEntity: true,
+  },
+  {
+    key: 'shadows',
+    label: 'Shadows',
+    description: 'Enable the shadow map. Per-entity cast/receive still applies.',
+    kind: 'toggle',
+    default: true,
+    apply: 'live',
+    perEntity: true,
+  },
+  {
+    key: 'postProcessing',
+    label: 'Post-processing',
+    description:
+      'Master switch for the post-processing stack (individual effects nest beneath it).',
+    kind: 'toggle',
+    default: true,
+    apply: 'live',
+    perEntity: false,
+  },
+  {
+    key: 'resolutionScale',
+    label: 'Resolution scale',
+    description: 'Device-pixel-ratio multiplier (1.0 = native). The cheapest perf dial.',
+    kind: 'number',
+    default: 1,
+    apply: 'live',
+    perEntity: false,
+    range: [0.25, 2],
+  },
+  {
+    key: 'antialias',
+    label: 'Antialiasing',
+    description: 'MSAA via renderer construction. Applies on reload (renderer re-init).',
+    kind: 'toggle',
+    default: true,
+    apply: 'reload',
+    perEntity: false,
+  },
+  {
+    key: 'backend',
+    label: 'Renderer backend',
+    description: 'GPU backend: auto picks WebGPU when available, else WebGL2. Applies on reload.',
+    kind: 'enum',
+    default: 'auto',
+    apply: 'reload',
+    perEntity: false,
+    options: ['auto', 'webgl', 'webgpu'],
+  },
+];
+
+/** Map for O(1) lookup by key. */
+export const RENDER_FEATURE_BY_KEY: ReadonlyMap<string, RenderFeature> = new Map(
+  RENDER_FEATURES.map((f) => [f.key, f]),
+);
+
+/**
+ * Build a Zod object for the render settings, derived from the registry so the
+ * schema can never drift from the feature list. All fields optional — absence
+ * means "inherit" in the cascade. `perEntityOnly` builds the per-entity override
+ * schema (only features whose `perEntity` is true).
+ */
+export function buildRenderingZod(opts: { perEntityOnly?: boolean } = {}): z.ZodTypeAny {
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const f of RENDER_FEATURES) {
+    if (opts.perEntityOnly && !f.perEntity) continue;
+    let base: z.ZodTypeAny;
+    if (f.kind === 'toggle') base = z.boolean();
+    else if (f.kind === 'number') base = z.number();
+    else base = z.enum(f.options as [string, ...string[]]);
+    shape[f.key] = base.optional().describe(f.description);
+  }
+  return z
+    .object(shape)
+    .describe(
+      opts.perEntityOnly
+        ? 'Per-entity render overrides (omit a field to inherit from the scene/engine default)'
+        : 'Scene render settings (omit a field to inherit the engine default)',
+    );
+}

package/src/render/render-settings.ts

@@ -0,0 +1,72 @@
+import { RENDER_FEATURES, type RenderFeatureValue } from './render-features';
+
+/**
+ * Cascade resolution for render settings: engine default → scene → entity, with
+ * tri-state inherit (an absent value inherits from the next level up). See
+ * docs/research/RENDER-SETTINGS-UX.md.
+ */
+
+/** A partial override map (scene-level or entity-level). Absent key = inherit. */
+export type RenderScope = Partial<Record<string, RenderFeatureValue>>;
+
+/** Fully-resolved settings: every registry key present. */
+export type ResolvedRenderSettings = Record<string, RenderFeatureValue>;
+
+/**
+ * Resolve effective settings. `entity` overrides only apply to features whose
+ * `perEntity` flag is set; non-per-entity features resolve across engine→scene
+ * only. `??` walks up the chain on `undefined` (inherit) but lets an explicit
+ * `false`/`0` override (they are not nullish).
+ */
+export function resolveRenderSettings(
+  scene?: RenderScope,
+  entity?: RenderScope,
+): ResolvedRenderSettings {
+  const out: ResolvedRenderSettings = {};
+  for (const f of RENDER_FEATURES) {
+    const entityVal = f.perEntity ? entity?.[f.key] : undefined;
+    out[f.key] = entityVal ?? scene?.[f.key] ?? f.default;
+  }
+  return out;
+}
+
+/**
+ * A small observable holding the live scene-level resolved settings. Live
+ * features re-apply when a value changes (subscribers are notified with the
+ * changed key). This is the seam a future player-facing graphics menu would
+ * drive — for now it backs the editor toggles + the runtime systems.
+ */
+export class RenderSettings {
+  private values: ResolvedRenderSettings;
+  private listeners = new Set<(key: string, value: RenderFeatureValue) => void>();
+
+  constructor(scene?: RenderScope) {
+    this.values = resolveRenderSettings(scene);
+  }
+
+  get(key: string): RenderFeatureValue {
+    return this.values[key]!;
+  }
+
+  /** Set a scene-level value; notifies subscribers if it changed. */
+  set(key: string, value: RenderFeatureValue): void {
+    if (this.values[key] === value) return;
+    this.values[key] = value;
+    for (const fn of this.listeners) fn(key, value);
+  }
+
+  /** Resolve the effective value for an entity (entity override → scene → default). */
+  forEntity(key: string, entity?: RenderScope): RenderFeatureValue {
+    const f = entity?.[key];
+    return f ?? this.values[key]!;
+  }
+
+  subscribe(fn: (key: string, value: RenderFeatureValue) => void): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  snapshot(): ResolvedRenderSettings {
+    return { ...this.values };
+  }
+}