@vgai/engine 0.5.4 → 0.5.6

package/dist/setup/setup-renderer.js

@@ -0,0 +1,381 @@
+/// <reference path="../types-n8ao.d.ts" />
+import { N8AOPostPass } from 'n8ao';
+import { BloomEffect, BrightnessContrastEffect, ChromaticAberrationEffect, ColorDepthEffect, DepthOfFieldEffect, DotScreenEffect, EffectComposer, EffectPass, GlitchEffect, GodRaysEffect, GridEffect, HueSaturationEffect, LensDistortionEffect, NoiseEffect, NormalPass, OutlineEffect, PixelationEffect, RenderPass, ScanlineEffect, SepiaEffect, ShockWaveEffect, SMAAEffect, SMAAPreset, SSAOEffect, TiltShiftEffect, VignetteEffect, } from 'postprocessing';
+import * as THREE from 'three';
+import { MotionBlurEffect, SSGIEffect, SSREffect, VelocityDepthNormalPass, } from '../../vendor/realism-effects/dist/index.js';
+import { DEFAULTS } from '../defaults';
+import { detectKtx2Support } from '../loader';
+import { resolveRenderSettings } from '../render/render-settings';
+/**
+ * Apply the live renderer-level render settings (shadows, resolution scale) from
+ * the resolved cascade. `antialias`/`backend` are reload-only (renderer re-init)
+ * and are handled at construction, not here. Pass the scene `rendering` scope
+ * (e.g. `env.rendering`); absent values fall back to the registry defaults so
+ * behavior is unchanged when a scene omits `rendering`.
+ *
+ * `basePixelRatio` is the call-site's native pixel-ratio policy (the runtime caps
+ * at 2; the editor uses the raw devicePixelRatio); `resolutionScale` multiplies it.
+ */
+export function applyRendererSettings(renderer, rendering, basePixelRatio = Math.min(window.devicePixelRatio, 2)) {
+    const settings = resolveRenderSettings(rendering);
+    renderer.shadowMap.enabled = Boolean(settings['shadows']);
+    const scale = Number(settings['resolutionScale']) || 1;
+    renderer.setPixelRatio(basePixelRatio * scale);
+}
+/**
+ * Create ONLY the WebGL renderer. The HOST owns the renderer (see
+ * `ThreeHostContext.renderer`); the game/adapter owns the scene/camera/composer it
+ * renders into. Split out of `setupRenderer` for the adapter inversion.
+ *
+ * `rendering` is the scene-level render scope (`env.rendering`); it seeds the
+ * reload-only `antialias` option at construction and the live shadow/resolution
+ * settings (via {@link applyRendererSettings}). Absent → registry defaults.
+ *
+ * `opts` is additive (T6.1 slice 1, D5 §1/§4): omitted
+ * entirely, construction is byte-identical to before (no `alpha`/
+ * `preserveDrawingBuffer` keys at all) — the legacy single-canvas host never
+ * passes it. The roots path passes `alpha:true` for every stacked canvas
+ * above the bottom one (so its clear-alpha-0 shows the layer below through
+ * it) and `preserveDrawingBuffer:true` for every stacked canvas (the
+ * recorded capture-tier cost, paid once here rather than re-derived later).
+ */
+export function createHostRenderer(canvas, width = window.innerWidth, height = window.innerHeight, rendering, opts) {
+    // A newly-shown editor tab can report 0x0 for one layout frame. WebGL render
+    // targets cannot have zero-sized attachments, so boot at the smallest valid
+    // backing size and let the normal resize path apply the real dimensions.
+    const safeWidth = Math.max(1, width);
+    const safeHeight = Math.max(1, height);
+    const settings = resolveRenderSettings(rendering);
+    const renderer = new THREE.WebGLRenderer({
+        canvas,
+        antialias: Boolean(settings['antialias']),
+        powerPreference: 'high-performance',
+        ...(opts?.alpha ? { alpha: true } : {}),
+        ...(opts?.preserveDrawingBuffer ? { preserveDrawingBuffer: true } : {}),
+    });
+    renderer.setSize(safeWidth, safeHeight);
+    applyRendererSettings(renderer, rendering);
+    renderer.shadowMap.type = THREE.PCFSoftShadowMap;
+    renderer.toneMapping = toneMappingModes[DEFAULTS.toneMapping.mode] ?? THREE.ACESFilmicToneMapping;
+    renderer.toneMappingExposure = DEFAULTS.toneMapping.exposure;
+    // The shared KTX2Loader cannot transcode a KHR_texture_basisu texture until
+    // some renderer has told it which compressed formats this GPU accepts.
+    // Idempotent — see `detectKtx2Support`.
+    detectKtx2Support(renderer);
+    return renderer;
+}
+/**
+ * Create the scene, camera, and postprocessing composer that a first-party game
+ * renders into, given a host-provided renderer. The GPU-only `composer` is
+ * created here; a headless host (no GPU) skips this entirely.
+ */
+export function createSceneView(renderer, width = window.innerWidth, height = window.innerHeight) {
+    const safeWidth = Math.max(1, width);
+    const safeHeight = Math.max(1, height);
+    const scene = new THREE.Scene();
+    scene.background = new THREE.Color(0x1a1a2e);
+    const camera = new THREE.PerspectiveCamera(DEFAULTS.camera.fov, safeWidth / safeHeight, DEFAULTS.camera.near, DEFAULTS.camera.far);
+    camera.position.set(0, 5, 10);
+    camera.lookAt(0, 0, 0);
+    const composer = new EffectComposer(renderer);
+    composer.addPass(new RenderPass(scene, camera));
+    composer.addPass(new EffectPass(camera, new BloomEffect({ luminanceThreshold: DEFAULTS.postProcessing.bloom.luminanceThreshold })));
+    return { scene, camera, composer };
+}
+/**
+ * Creates the Three.js renderer, scene, camera, and postprocessing pipeline.
+ *
+ * This is direct Three.js setup — no abstraction. Edit freely. (Now a thin
+ * combination of {@link createHostRenderer} + {@link createSceneView}.)
+ */
+export function setupRenderer(canvas, width = window.innerWidth, height = window.innerHeight) {
+    const renderer = createHostRenderer(canvas, width, height);
+    const { scene, camera, composer } = createSceneView(renderer, width, height);
+    return { renderer, scene, camera, composer };
+}
+const toneMappingModes = {
+    none: THREE.NoToneMapping,
+    linear: THREE.LinearToneMapping,
+    reinhard: THREE.ReinhardToneMapping,
+    cineon: THREE.CineonToneMapping,
+    aces: THREE.ACESFilmicToneMapping,
+    agx: THREE.AgXToneMapping,
+};
+const smaaPresets = {
+    low: SMAAPreset.LOW,
+    medium: SMAAPreset.MEDIUM,
+    high: SMAAPreset.HIGH,
+    ultra: SMAAPreset.ULTRA,
+};
+/**
+ * Rebuild composer passes from scene environment settings.
+ * Scenes without toneMapping default to ACES (the runtime default).
+ * Code can further modify the composer after this call.
+ *
+ * Pass objectMap to enable entity-referencing effects (godRays, outline).
+ * Pass entities to resolve tag-based references (outline).
+ */
+export function applyScenePostProcessing(composer, renderer, scene, camera, env, objectMap, entityTags) {
+    // Dispose the existing passes before discarding them — removeAllPasses() just
+    // drops the references, so their GPU render targets would otherwise leak on
+    // every env edit / scene switch.
+    for (const pass of composer.passes) {
+        pass.dispose?.();
+    }
+    composer.removeAllPasses();
+    composer.addPass(new RenderPass(scene, camera));
+    // ── Tone mapping ──────────────────────────────────────────────────────
+    const tm = env?.toneMapping;
+    renderer.toneMapping =
+        toneMappingModes[tm?.mode ?? DEFAULTS.toneMapping.mode] ?? THREE.ACESFilmicToneMapping;
+    renderer.toneMappingExposure = tm?.exposure ?? DEFAULTS.toneMapping.exposure;
+    // ── Master switch ─────────────────────────────────────────────────────
+    // When post-processing is disabled at the scene/engine level, render the
+    // plain scene (the RenderPass added above) and skip every effect pass. The
+    // per-effect `enabled` flags below still apply when the master switch is on.
+    if (!resolveRenderSettings(env?.rendering)['postProcessing'])
+        return;
+    const pp = env?.postProcessing;
+    const d = DEFAULTS.postProcessing;
+    // ── Prerequisite passes ───────────────────────────────────────────────
+    // NormalPass — needed by SSAO
+    let normalPass;
+    if (pp?.ssao?.enabled) {
+        normalPass = new NormalPass(scene, camera);
+        composer.addPass(normalPass);
+    }
+    // VelocityDepthNormalPass — needed by SSR, SSGI, MotionBlur
+    let velocityPass;
+    if (pp?.ssr?.enabled || pp?.ssgi?.enabled || pp?.motionBlur?.enabled) {
+        velocityPass = new VelocityDepthNormalPass(scene, camera);
+        composer.addPass(velocityPass);
+    }
+    // N8AOPostPass — separate Pass, not an Effect
+    if (pp?.n8ao?.enabled) {
+        const n8aoPass = new N8AOPostPass(scene, camera);
+        const cfg = n8aoPass.configuration;
+        cfg.aoSamples = pp.n8ao.aoSamples ?? d.n8ao.aoSamples;
+        cfg.aoRadius = pp.n8ao.aoRadius ?? d.n8ao.aoRadius;
+        cfg.intensity = pp.n8ao.intensity ?? d.n8ao.intensity;
+        cfg.denoiseSamples = pp.n8ao.denoiseSamples ?? d.n8ao.denoiseSamples;
+        cfg.denoiseRadius = pp.n8ao.denoiseRadius ?? d.n8ao.denoiseRadius;
+        cfg.distanceFalloff = pp.n8ao.distanceFalloff ?? d.n8ao.distanceFalloff;
+        if (pp.n8ao.screenSpaceRadius !== undefined)
+            cfg.screenSpaceRadius = pp.n8ao.screenSpaceRadius;
+        if (pp.n8ao.halfRes !== undefined)
+            cfg.halfRes = pp.n8ao.halfRes;
+        if (pp.n8ao.color)
+            cfg.color = new THREE.Color(pp.n8ao.color);
+        composer.addPass(n8aoPass);
+    }
+    // ── Collect Effect instances ──────────────────────────────────────────
+    const effects = [];
+    // Anti-aliasing
+    if (pp?.smaa?.enabled) {
+        const preset = smaaPresets[pp.smaa.preset ?? d.smaa.preset] ?? SMAAPreset.HIGH;
+        effects.push(new SMAAEffect({ preset }));
+    }
+    // Ambient occlusion
+    if (pp?.ssao?.enabled && normalPass) {
+        effects.push(new SSAOEffect(camera, normalPass.texture, {
+            radius: pp.ssao.radius ?? d.ssao.radius,
+            intensity: pp.ssao.intensity ?? d.ssao.intensity,
+            bias: pp.ssao.bias ?? d.ssao.bias,
+            samples: pp.ssao.samples ?? d.ssao.samples,
+            rings: pp.ssao.rings ?? d.ssao.rings,
+            fade: pp.ssao.fade ?? d.ssao.fade,
+            ...(pp.ssao.color ? { color: new THREE.Color(pp.ssao.color) } : {}),
+        }));
+    }
+    // SSR (realism-effects)
+    if (pp?.ssr?.enabled && velocityPass) {
+        effects.push(new SSREffect(scene, camera, velocityPass, {
+            intensity: pp.ssr.intensity ?? d.ssr.intensity,
+            exponent: pp.ssr.exponent ?? d.ssr.exponent,
+            distance: pp.ssr.distance ?? d.ssr.distance,
+            thickness: pp.ssr.thickness ?? d.ssr.thickness,
+            maxRoughness: pp.ssr.maxRoughness ?? d.ssr.maxRoughness,
+        }));
+    }
+    // SSGI (realism-effects)
+    if (pp?.ssgi?.enabled && velocityPass) {
+        effects.push(new SSGIEffect(scene, camera, velocityPass, {
+            intensity: pp.ssgi.intensity ?? d.ssgi.intensity,
+            distance: pp.ssgi.distance ?? d.ssgi.distance,
+            thickness: pp.ssgi.thickness ?? d.ssgi.thickness,
+            maxRoughness: pp.ssgi.maxRoughness ?? d.ssgi.maxRoughness,
+        }));
+    }
+    // Motion blur (realism-effects)
+    if (pp?.motionBlur?.enabled && velocityPass) {
+        effects.push(new MotionBlurEffect(velocityPass, {
+            intensity: pp.motionBlur.intensity ?? d.motionBlur.intensity,
+            jitter: pp.motionBlur.jitter ?? d.motionBlur.jitter,
+            samples: pp.motionBlur.samples ?? d.motionBlur.samples,
+        }));
+    }
+    // Bloom
+    if (pp?.bloom?.enabled) {
+        effects.push(new BloomEffect({
+            intensity: pp.bloom.intensity ?? d.bloom.intensity,
+            luminanceThreshold: pp.bloom.luminanceThreshold ?? d.bloom.luminanceThreshold,
+            luminanceSmoothing: pp.bloom.luminanceSmoothing ?? d.bloom.luminanceSmoothing,
+        }));
+    }
+    // Depth of field
+    if (pp?.depthOfField?.enabled) {
+        effects.push(new DepthOfFieldEffect(camera, {
+            worldFocusDistance: pp.depthOfField.worldFocusDistance ?? d.depthOfField.worldFocusDistance,
+            worldFocusRange: pp.depthOfField.worldFocusRange ?? d.depthOfField.worldFocusRange,
+            bokehScale: pp.depthOfField.bokehScale ?? d.depthOfField.bokehScale,
+            focalLength: pp.depthOfField.focalLength ?? d.depthOfField.focalLength,
+        }));
+    }
+    // Tilt shift
+    if (pp?.tiltShift?.enabled) {
+        effects.push(new TiltShiftEffect({
+            offset: pp.tiltShift.offset ?? d.tiltShift.offset,
+            rotation: pp.tiltShift.rotation ?? d.tiltShift.rotation,
+            focusArea: pp.tiltShift.focusArea ?? d.tiltShift.focusArea,
+            feather: pp.tiltShift.feather ?? d.tiltShift.feather,
+        }));
+    }
+    // God rays (needs entity reference)
+    if (pp?.godRays?.enabled && pp.godRays.sourceEntity && objectMap) {
+        const lightObj = objectMap.get(pp.godRays.sourceEntity);
+        if (lightObj instanceof THREE.Mesh || lightObj instanceof THREE.Points) {
+            effects.push(new GodRaysEffect(camera, lightObj, {
+                density: pp.godRays.density ?? d.godRays.density,
+                decay: pp.godRays.decay ?? d.godRays.decay,
+                weight: pp.godRays.weight ?? d.godRays.weight,
+                exposure: pp.godRays.exposure ?? d.godRays.exposure,
+                samples: pp.godRays.samples ?? d.godRays.samples,
+            }));
+        }
+    }
+    // Outline (needs entity tag references)
+    if (pp?.outline?.enabled && objectMap) {
+        const outlineEffect = new OutlineEffect(scene, camera, {
+            edgeStrength: pp.outline.edgeStrength ?? d.outline.edgeStrength,
+            pulseSpeed: pp.outline.pulseSpeed ?? d.outline.pulseSpeed,
+            visibleEdgeColor: pp.outline.visibleEdgeColor
+                ? new THREE.Color(pp.outline.visibleEdgeColor).getHex()
+                : new THREE.Color(d.outline.visibleEdgeColor).getHex(),
+            hiddenEdgeColor: pp.outline.hiddenEdgeColor
+                ? new THREE.Color(pp.outline.hiddenEdgeColor).getHex()
+                : new THREE.Color(d.outline.hiddenEdgeColor).getHex(),
+            xRay: pp.outline.xRay ?? false,
+        });
+        // Add entities matching tags to selection
+        const tags = pp.outline.tags ?? [];
+        if (tags.length > 0 && entityTags) {
+            for (const [entityId, eTags] of entityTags) {
+                if (tags.some((t) => eTags.includes(t))) {
+                    const obj = objectMap.get(entityId);
+                    if (obj)
+                        outlineEffect.selection.add(obj);
+                }
+            }
+        }
+        effects.push(outlineEffect);
+    }
+    // Chromatic aberration
+    if (pp?.chromaticAberration?.enabled) {
+        effects.push(new ChromaticAberrationEffect({
+            offset: new THREE.Vector2(pp.chromaticAberration.offsetX ?? d.chromaticAberration.offsetX, pp.chromaticAberration.offsetY ?? d.chromaticAberration.offsetY),
+            radialModulation: pp.chromaticAberration.radialModulation ?? false,
+            modulationOffset: pp.chromaticAberration.modulationOffset ?? d.chromaticAberration.modulationOffset,
+        }));
+    }
+    // Lens distortion
+    if (pp?.lensDistortion?.enabled) {
+        effects.push(new LensDistortionEffect({
+            distortion: new THREE.Vector2(pp.lensDistortion.distortionX ?? d.lensDistortion.distortionX, pp.lensDistortion.distortionY ?? d.lensDistortion.distortionY),
+            principalPoint: new THREE.Vector2(0, 0),
+            focalLength: new THREE.Vector2(pp.lensDistortion.focalLengthX ?? d.lensDistortion.focalLengthX, pp.lensDistortion.focalLengthY ?? d.lensDistortion.focalLengthY),
+            skew: pp.lensDistortion.skew ?? d.lensDistortion.skew,
+        }));
+    }
+    // Shock wave
+    if (pp?.shockWave?.enabled) {
+        effects.push(new ShockWaveEffect(camera, new THREE.Vector3(pp.shockWave.positionX ?? 0, pp.shockWave.positionY ?? 0, pp.shockWave.positionZ ?? 0), {
+            speed: pp.shockWave.speed ?? d.shockWave.speed,
+            maxRadius: pp.shockWave.maxRadius ?? d.shockWave.maxRadius,
+            waveSize: pp.shockWave.waveSize ?? d.shockWave.waveSize,
+            amplitude: pp.shockWave.amplitude ?? d.shockWave.amplitude,
+        }));
+    }
+    // Color adjustments
+    if (pp?.brightnessContrast?.enabled) {
+        effects.push(new BrightnessContrastEffect({
+            brightness: pp.brightnessContrast.brightness ?? d.brightnessContrast.brightness,
+            contrast: pp.brightnessContrast.contrast ?? d.brightnessContrast.contrast,
+        }));
+    }
+    if (pp?.hueSaturation?.enabled) {
+        effects.push(new HueSaturationEffect({
+            hue: pp.hueSaturation.hue ?? d.hueSaturation.hue,
+            saturation: pp.hueSaturation.saturation ?? d.hueSaturation.saturation,
+        }));
+    }
+    if (pp?.sepia?.enabled) {
+        effects.push(new SepiaEffect({ intensity: pp.sepia.intensity ?? d.sepia.intensity }));
+    }
+    if (pp?.colorDepth?.enabled) {
+        effects.push(new ColorDepthEffect({ bits: pp.colorDepth.bits ?? d.colorDepth.bits }));
+    }
+    // Film / retro
+    if (pp?.noise?.enabled) {
+        effects.push(new NoiseEffect({ premultiply: pp.noise.premultiply ?? d.noise.premultiply }));
+    }
+    if (pp?.scanline?.enabled) {
+        effects.push(new ScanlineEffect({ density: pp.scanline.density ?? d.scanline.density }));
+    }
+    if (pp?.dotScreen?.enabled) {
+        effects.push(new DotScreenEffect({
+            angle: pp.dotScreen.angle ?? d.dotScreen.angle,
+            scale: pp.dotScreen.scale ?? d.dotScreen.scale,
+        }));
+    }
+    if (pp?.grid?.enabled) {
+        effects.push(new GridEffect({
+            scale: pp.grid.scale ?? d.grid.scale,
+            lineWidth: pp.grid.lineWidth ?? d.grid.lineWidth,
+        }));
+    }
+    if (pp?.pixelation?.enabled) {
+        effects.push(new PixelationEffect(pp.pixelation.granularity ?? d.pixelation.granularity));
+    }
+    if (pp?.glitch?.enabled) {
+        effects.push(new GlitchEffect({
+            delay: new THREE.Vector2(pp.glitch.delayX ?? d.glitch.delayX, pp.glitch.delayY ?? d.glitch.delayY),
+            duration: new THREE.Vector2(pp.glitch.durationX ?? d.glitch.durationX, pp.glitch.durationY ?? d.glitch.durationY),
+            strength: new THREE.Vector2(pp.glitch.strengthX ?? d.glitch.strengthX, pp.glitch.strengthY ?? d.glitch.strengthY),
+            columns: pp.glitch.columns ?? d.glitch.columns,
+            ratio: pp.glitch.ratio ?? d.glitch.ratio,
+        }));
+    }
+    // Vignette (last color effect)
+    if (pp?.vignette?.enabled) {
+        effects.push(new VignetteEffect({
+            darkness: pp.vignette.darkness ?? d.vignette.darkness,
+            offset: pp.vignette.offset ?? d.vignette.offset,
+        }));
+    }
+    // ── Merge all effects into a single EffectPass ────────────────────────
+    if (effects.length > 0) {
+        composer.addPass(new EffectPass(camera, ...effects));
+    }
+}
+/**
+ * Apply every authored scene-level renderer setting through one path.
+ *
+ * Tone mapping is part of the scene environment, not conditional on the
+ * presence of post-processing effects. Keeping renderer settings and the
+ * composer rebuild together prevents editor/runtime drift for scenes that
+ * only author exposure or a tone-mapping mode.
+ */
+export function applySceneRenderPipeline(composer, renderer, scene, camera, env, options) {
+    applyRendererSettings(renderer, env?.rendering, options?.basePixelRatio);
+    applyScenePostProcessing(composer, renderer, scene, camera, env, options?.objectMap, options?.entityTags);
+}

package/dist/world3d-react/engine-bridge.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `@engine/world3d-react` — the React context that carries this R3F world's
+ * engine runtime into its fiber tree: the world's `R3FGameContext`, read
+ * with {@link useGameContext}.
+ *
+ * Upstreamed from `examples/r3f-first-party/src/engine-bridge.ts` (R4).
+ * The bridge value
+ * is built by `createR3FAdapter`'s `mount()` (./r3f-adapter.tsx): a real
+ * `createSystemRunner` whose phases the adapter's `update(dt)` runs under the
+ * HOST loop — so registered systems tick in engine phase order, pause included
+ * (no update while the world is frozen).
+ *
+ * Behavior in an R3F world is components and hooks: `useGameContext` is how a
+ * component reaches engine services.
+ */
+import type { R3FGameContext } from './world-context';
+export interface EngineBridgeValue {
+    /** This root's context — `input`, `debug`, `random`, `game`, `roots`, … .
+     *  Present so ordinary components can reach engine services with a HOOK
+     *  (see {@link useGameContext}). */
+    readonly ctx?: R3FGameContext | undefined;
+}
+export declare const EngineBridge: import("react").Context<EngineBridgeValue | null>;
+/**
+ * This R3F root's context, for use inside any component in the tree — an
+ * {@link R3FGameContext}, which is exactly the subsystems an R3F world builds.
+ * The ones it does not build are absent from the type, so reaching for one is
+ * a compile error at the call site; that type's doc comment says what to reach
+ * for instead.
+ *
+ * An ordinary component does what a model would write:
+ *
+ * ```tsx
+ * function Player({ speed = 4.5 }) {
+ *   const { input } = useGameContext();
+ *   const ref = useRef<THREE.Group>(null);
+ *   useFrame((_, dt) => { if (input.isPressed('move_forward')) … });
+ *   return <group ref={ref}><PlayerCharacter /></group>;
+ * }
+ * ```
+ *
+ * Throws when called outside an R3F root mounted by `createR3FAdapter` —
+ * absent context is a wiring bug, and a silent `null` would surface as a
+ * mystery `undefined` deep in a frame callback.
+ */
+export declare function useGameContext(): R3FGameContext;
+//# sourceMappingURL=engine-bridge.d.ts.map

package/dist/world3d-react/engine-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine-bridge.d.ts","sourceRoot":"","sources":["../../src/world3d-react/engine-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEtD,MAAM,WAAW,iBAAiB;IAChC;;wCAEoC;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,cAAc,GAAG,SAAS,CAAC;CAC3C;AAED,eAAO,MAAM,YAAY,mDAAgD,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,IAAI,cAAc,CAU/C"}

package/dist/world3d-react/engine-bridge.js

@@ -0,0 +1,48 @@
+/**
+ * `@engine/world3d-react` — the React context that carries this R3F world's
+ * engine runtime into its fiber tree: the world's `R3FGameContext`, read
+ * with {@link useGameContext}.
+ *
+ * Upstreamed from `examples/r3f-first-party/src/engine-bridge.ts` (R4).
+ * The bridge value
+ * is built by `createR3FAdapter`'s `mount()` (./r3f-adapter.tsx): a real
+ * `createSystemRunner` whose phases the adapter's `update(dt)` runs under the
+ * HOST loop — so registered systems tick in engine phase order, pause included
+ * (no update while the world is frozen).
+ *
+ * Behavior in an R3F world is components and hooks: `useGameContext` is how a
+ * component reaches engine services.
+ */
+import { createContext, useContext } from 'react';
+export const EngineBridge = createContext(null);
+/**
+ * This R3F root's context, for use inside any component in the tree — an
+ * {@link R3FGameContext}, which is exactly the subsystems an R3F world builds.
+ * The ones it does not build are absent from the type, so reaching for one is
+ * a compile error at the call site; that type's doc comment says what to reach
+ * for instead.
+ *
+ * An ordinary component does what a model would write:
+ *
+ * ```tsx
+ * function Player({ speed = 4.5 }) {
+ *   const { input } = useGameContext();
+ *   const ref = useRef<THREE.Group>(null);
+ *   useFrame((_, dt) => { if (input.isPressed('move_forward')) … });
+ *   return <group ref={ref}><PlayerCharacter /></group>;
+ * }
+ * ```
+ *
+ * Throws when called outside an R3F root mounted by `createR3FAdapter` —
+ * absent context is a wiring bug, and a silent `null` would surface as a
+ * mystery `undefined` deep in a frame callback.
+ */
+export function useGameContext() {
+    const bridge = useContext(EngineBridge);
+    if (!bridge?.ctx) {
+        throw new Error('useGameContext(): no engine root context. This hook only works inside an R3F ' +
+            'root mounted by createR3FAdapter (@engine/world3d-react) — check that the ' +
+            'component is rendered inside your world entry, not in a standalone <Canvas>.');
+    }
+    return bridge.ctx;
+}

package/dist/world3d-react/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * world3d-react — the react-three-fiber bridge for vgai's three surface
+ * (`@engine/world3d-react`).
+ *
+ * An OPT-IN module, upstreamed
+ * from the live-proven `examples/r3f-first-party` project copies (R4;
+ * decision D24 — R3F TSX is the blessed three.js authoring path). Mirrors how
+ * `pixi/` is the PixiJS surface's opt-in home: a peer surface module the engine
+ * CORE never imports (enforced by
+ * `packages/engine/test/react-core-import-ban.test.ts` — this directory is an
+ * allowed react-importing entry alongside `react/`, and core files may not
+ * import it).
+ *
+ * Peer contract: an importing PROJECT already depends on `react`,
+ * `@react-three/fiber`, and `three` (fiber's three must be deduped to the
+ * host's single instance — `resolve.dedupe: ['three', 'react', 'react-dom']`
+ * in the project's Vite config; see `createR3FAdapter`'s header). The engine
+ * package deliberately declares no hard dependency on fiber: only projects
+ * that already mount through fiber ever import this module.
+ *
+ * Surface:
+ *  - `createR3FAdapter({ id, content })` — mount an R3F tree as a first-party
+ *    `kind: "three"` world under the host's gated loop.
+ *  - `useGameContext()` — this root's `R3FGameContext` (`input`, `debug`,
+ *    `random`, `game`, `roots`, …) from inside any component in the tree. This
+ *    is how an R3F world reaches engine services: behavior is components +
+ *    hooks (D26b), not a class under a string key. The subsystems an R3F world
+ *    does not build are absent from that type — see its doc comment for what
+ *    to use instead.
+ *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported
+ *    for advanced adopters building their own bridge.
+ *
+ * Deliberately NOT re-exported here: `<RapierPhysicsBridge>`
+ * (`@engine/world3d-react/rapier-physics-bridge`), which registers an R3F
+ * world's `@react-three/rapier` physics as the game's
+ * `SystemAdapters.physics` — so the dev menu's colliders instrument and the
+ * editor's transform coordination can see it. It imports
+ * `@react-three/rapier`, and only a world that already depends on that library
+ * should pull it into its graph; a deep import keeps this barrel's peer
+ * contract to `react`/`@react-three/fiber`/`three` alone.
+ */
+export { EngineBridge, type EngineBridgeValue, useGameContext } from './engine-bridge';
+export { type CreateR3FAdapterOptions, createR3FAdapter } from './r3f-adapter';
+export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
+export { applyWorldRendererConfig, type WorldOutputColorSpace, type WorldRendererConfig, type WorldToneMapping, } from './renderer-config';
+export { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, type R3FGameContext, type R3FRootContextOptions, type R3FRootRuntime, } from './world-context';
+//# sourceMappingURL=index.d.ts.map

package/dist/world3d-react/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/world3d-react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,iBAAiB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvF,OAAO,EAAE,KAAK,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC/E,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EACL,wBAAwB,EACxB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,GACpB,MAAM,iBAAiB,CAAC"}

package/dist/world3d-react/index.js

@@ -0,0 +1,46 @@
+/**
+ * world3d-react — the react-three-fiber bridge for vgai's three surface
+ * (`@engine/world3d-react`).
+ *
+ * An OPT-IN module, upstreamed
+ * from the live-proven `examples/r3f-first-party` project copies (R4;
+ * decision D24 — R3F TSX is the blessed three.js authoring path). Mirrors how
+ * `pixi/` is the PixiJS surface's opt-in home: a peer surface module the engine
+ * CORE never imports (enforced by
+ * `packages/engine/test/react-core-import-ban.test.ts` — this directory is an
+ * allowed react-importing entry alongside `react/`, and core files may not
+ * import it).
+ *
+ * Peer contract: an importing PROJECT already depends on `react`,
+ * `@react-three/fiber`, and `three` (fiber's three must be deduped to the
+ * host's single instance — `resolve.dedupe: ['three', 'react', 'react-dom']`
+ * in the project's Vite config; see `createR3FAdapter`'s header). The engine
+ * package deliberately declares no hard dependency on fiber: only projects
+ * that already mount through fiber ever import this module.
+ *
+ * Surface:
+ *  - `createR3FAdapter({ id, content })` — mount an R3F tree as a first-party
+ *    `kind: "three"` world under the host's gated loop.
+ *  - `useGameContext()` — this root's `R3FGameContext` (`input`, `debug`,
+ *    `random`, `game`, `roots`, …) from inside any component in the tree. This
+ *    is how an R3F world reaches engine services: behavior is components +
+ *    hooks (D26b), not a class under a string key. The subsystems an R3F world
+ *    does not build are absent from that type — see its doc comment for what
+ *    to use instead.
+ *  - `EngineBridge` / `EngineBridgeValue` — the context contract, exported
+ *    for advanced adopters building their own bridge.
+ *
+ * Deliberately NOT re-exported here: `<RapierPhysicsBridge>`
+ * (`@engine/world3d-react/rapier-physics-bridge`), which registers an R3F
+ * world's `@react-three/rapier` physics as the game's
+ * `SystemAdapters.physics` — so the dev menu's colliders instrument and the
+ * editor's transform coordination can see it. It imports
+ * `@react-three/rapier`, and only a world that already depends on that library
+ * should pull it into its graph; a deep import keeps this barrel's peer
+ * contract to `react`/`@react-three/fiber`/`three` alone.
+ */
+export { EngineBridge, useGameContext } from './engine-bridge';
+export { createR3FAdapter } from './r3f-adapter';
+export { r3fRootFactory, resolveR3FEntryAdapter } from './r3f-root-factory';
+export { applyWorldRendererConfig, } from './renderer-config';
+export { createR3FRootContext, DEFAULT_INPUT_MAP_PATH, } from './world-context';

package/dist/world3d-react/r3f-adapter.d.ts

@@ -0,0 +1,51 @@
+/**
+ * `createR3FAdapter` — wraps a react-three-fiber tree as a first-party
+ * `RootAdapter` so an R3F scene mounts as an ordinary `kind: "three"`
+ * world: the engine hands `mount()` a `ThreeHostContext` (ITS OWN renderer +
+ * canvas + gated loop, per `../adapter/host-context.ts`); this returns a
+ * `MountedThreeRoot` (`../adapter/root-adapter.ts`) whose `scene`/`camera`
+ * are fiber's REAL `THREE.Scene`/`THREE.Camera` instances.
+ *
+ * Upstreamed from `examples/r3f-first-party/src/r3f-adapter.tsx` (R4 — the
+ * `@engine/world3d-react` opt-in module, mirroring how `pixi/` is the
+ * PixiJS surface's opt-in home). The mount semantics
+ * are byte-for-byte the example's live-proven Phase-1 bridge. External adopters
+ * (alien-stories-style) keep the exact same calling contract.
+ *
+ * three.js identity: this module never imports `three` itself for scene objects
+ * — fiber's internal `import * as THREE from 'three'` must resolve to the SAME
+ * instance the engine's `ThreeHostContext.three` points at, which the importing
+ * project guarantees via its Vite `resolve.dedupe: ['three', 'react',
+ * 'react-dom']` (see `examples/r3f-first-party/vite.config.ts`).
+ */
+import { type ReactNode } from 'react';
+import type { RootAdapter } from '../adapter';
+import { type WorldRendererConfig } from './renderer-config';
+/** What {@link createR3FAdapter} needs to build one `RootAdapter`. */
+export interface CreateR3FAdapterOptions {
+    /** Stable id (telemetry/registry/conformance) — `RootAdapter.id`. */
+    readonly id: string;
+    /** The R3F scene tree to mount — drei helpers, `useFrame` hooks, etc. all
+     *  work unchanged (design §1.C: "drei works unchanged (it is fiber-context
+     *  userland)"). */
+    readonly content: ReactNode;
+    /** Input map loaded through the game-owned `Game.loadInputMap` (load-once
+     *  across roots). Defaults to the classic adapter's conventional path,
+     *  `/inputmaps/default.inputmap.json`; `null` opts out (a world with no
+     *  actions). A missing/invalid map degrades loudly without failing the
+     *  mount — see `world-context.ts`. */
+    readonly inputMapPath?: string | null | undefined;
+    /** The colour pipeline this world was AUTHORED for, applied to the host's renderer for the life
+     *  of the mount and restored on dispose. Omit it (every world here does) to keep the host's own
+     *  defaults; declare it when the world's colours were picked against a different engine's
+     *  pipeline — see `./renderer-config.ts`. */
+    readonly renderer?: WorldRendererConfig | undefined;
+}
+/**
+ * Build a `RootAdapter` that mounts `options.content` through
+ * react-three-fiber, gated entirely by the host's own loop and rendering
+ * through the host's own `WebGLRenderer` — never a second renderer, never a
+ * second `requestAnimationFrame` loop (design §1.C).
+ */
+export declare function createR3FAdapter(options: CreateR3FAdapterOptions): RootAdapter;
+//# sourceMappingURL=r3f-adapter.d.ts.map

package/dist/world3d-react/r3f-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r3f-adapter.d.ts","sourceRoot":"","sources":["../../src/world3d-react/r3f-adapter.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAoB,WAAW,EAAoB,MAAM,YAAY,CAAC;AAGlF,OAAO,EAA4B,KAAK,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGvF,sEAAsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,qEAAqE;IACrE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB;;uBAEmB;IACnB,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC;IAC5B;;;;0CAIsC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAClD;;;iDAG6C;IAC7C,QAAQ,CAAC,QAAQ,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACrD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,WAAW,CA2W9E"}