@combos-fun/plugin-renderer-3d 0.0.41 → 0.0.44

package/dist/plugin-renderer-3d.cjs.js

@@ -1,9 +1,16 @@
 'use strict';
 
+var tslib = require('tslib');
 var engine = require('@combos-fun/engine');
 var three = require('three');
+var inspectorDecorator = require('@combos-fun/inspector-decorator');
 
 const COMBOS_GAME_OBJECT_ID = 'combosGameObjectId';
+const COMBOS_INSTANCE_GAME_OBJECT_IDS = 'combosInstanceGameObjectIds';
+const COMBOS_TRANSFORM3D = 'combosTransform3D';
+function isTransform3DRoot(object) {
+    return !!object?.userData?.[COMBOS_TRANSFORM3D];
+}
 /** Stamp a Three.js object (and its children) so Event3D raycasts can resolve the GameObject. */
 function tagObject3D(object, gameObjectId) {
     object.traverse((child) => {
@@ -21,15 +28,130 @@ function gameObjectIdFromObject3D(object) {
     }
     return undefined;
 }
+/** Resolve a raycast hit, including InstancedMesh `instanceId` rows. */
+function gameObjectIdFromIntersection(intersection) {
+    if (!intersection?.object)
+        return undefined;
+    if (typeof intersection.instanceId === 'number') {
+        let current = intersection.object;
+        while (current) {
+            const ids = current.userData?.[COMBOS_INSTANCE_GAME_OBJECT_IDS];
+            if (Array.isArray(ids) && typeof ids[intersection.instanceId] === 'number') {
+                return ids[intersection.instanceId];
+            }
+            current = current.parent;
+        }
+    }
+    return gameObjectIdFromObject3D(intersection.object);
+}
+
+/** True when this GameObject is a scene root (no 3D parent). */
+function is3DSceneParent(gameObject) {
+    if (!gameObject)
+        return true;
+    const parent = gameObject.parent;
+    return !parent || parent === gameObject.scene;
+}
+function has3DChildGameObjects(gameObject) {
+    return (gameObject?.transform?.children?.length ?? 0) > 0;
+}
+
+function readPose(pose) {
+    return {
+        positionX: pose.positionX ?? 0,
+        positionY: pose.positionY ?? 0,
+        positionZ: pose.positionZ ?? 0,
+        rotationX: pose.rotationX ?? 0,
+        rotationY: pose.rotationY ?? 0,
+        rotationZ: pose.rotationZ ?? 0,
+        scaleX: pose.scaleX ?? 1,
+        scaleY: pose.scaleY ?? 1,
+        scaleZ: pose.scaleZ ?? 1,
+    };
+}
+function poseKeyOf(pose) {
+    const r = readPose(pose);
+    return [
+        r.positionX, r.positionY, r.positionZ,
+        r.rotationX, r.rotationY, r.rotationZ,
+        r.scaleX, r.scaleY, r.scaleZ,
+    ].join(',');
+}
+function copyPose(from, to) {
+    const r = readPose(from);
+    to.positionX = r.positionX;
+    to.positionY = r.positionY;
+    to.positionZ = r.positionZ;
+    to.rotationX = r.rotationX;
+    to.rotationY = r.rotationY;
+    to.rotationZ = r.rotationZ;
+    to.scaleX = r.scaleX;
+    to.scaleY = r.scaleY;
+    to.scaleZ = r.scaleZ;
+}
+function isIdentityPose(pose) {
+    const r = readPose(pose);
+    return r.positionX === 0 && r.positionY === 0 && r.positionZ === 0
+        && r.rotationX === 0 && r.rotationY === 0 && r.rotationZ === 0
+        && r.scaleX === 1 && r.scaleY === 1 && r.scaleZ === 1;
+}
+function seedTransform3D(visual, transform) {
+    if (isIdentityPose(transform) && !isIdentityPose(visual)) {
+        copyPose(visual, transform);
+    }
+}
+/**
+ * Keep a visual component's pose fields and a sibling Transform3D in sync.
+ * Returns true when the visual Object3D should still apply pose itself
+ * (no Transform3D root yet).
+ */
+class VisualPoseBridge {
+    constructor() {
+        this.lastVisual = '';
+        this.lastRoot = '';
+    }
+    sync(visual, root) {
+        if (!root)
+            return true;
+        if (this.lastVisual === '' && this.lastRoot === '') {
+            seedTransform3D(visual, root);
+            this.lastVisual = poseKeyOf(visual);
+            this.lastRoot = poseKeyOf(root);
+            return false;
+        }
+        const visualKey = poseKeyOf(visual);
+        const rootKey = poseKeyOf(root);
+        if (visualKey !== this.lastVisual && rootKey === this.lastRoot) {
+            copyPose(visual, root);
+        }
+        this.lastVisual = poseKeyOf(visual);
+        this.lastRoot = poseKeyOf(root);
+        return false;
+    }
+}
 
+const TONE_MAPPING = {
+    none: three.NoToneMapping,
+    aces: three.ACESFilmicToneMapping,
+    linear: three.LinearToneMapping,
+    reinhard: three.ReinhardToneMapping,
+    cineon: three.CineonToneMapping,
+};
+const _world = new three.Vector3();
+const _euler = new three.Euler();
 class ThreeContext {
     constructor(params) {
         this.mixers = new Map();
         this.models = new Map();
+        /** Root Object3D for each GameObject that has a 3D node. */
+        this.nodes = new Map();
+        this.defaultLights = [];
         const { canvas, container, width, height, antialias = true, backgroundColor = 0x000000, backgroundAlpha = 1, } = params;
         this.scene = new three.Scene();
+        this.shadows = !!params.shadows;
         this.camera = new three.PerspectiveCamera(75, width / height, 0.1, 1000);
         this.camera.position.z = 5;
+        this.fallbackCamera = this.camera;
         const rendererOpts = { antialias };
         if (canvas) {
             rendererOpts.canvas = canvas;
@@ -41,15 +163,36 @@ class ThreeContext {
         this.renderer.setSize(width, height);
         this.renderer.setPixelRatio(window.devicePixelRatio);
         this.renderer.setClearColor(backgroundColor, backgroundAlpha);
-        // If no canvas was provided but a container was, append the generated canvas
+        this.renderer.toneMapping = TONE_MAPPING[params.toneMapping ?? 'aces'] ?? three.ACESFilmicToneMapping;
+        this.renderer.toneMappingExposure = params.toneMappingExposure ?? 1;
+        if (this.shadows) {
+            this.renderer.shadowMap.enabled = true;
+            this.renderer.shadowMap.type = three.PCFSoftShadowMap;
+        }
         if (!canvas && container) {
             container.appendChild(this.renderer.domElement);
         }
-        const ambientLight = new three.AmbientLight(0xffffff, 0.6);
+        const ambientLight = new three.AmbientLight(0xffffff, params.ambientIntensity ?? 0.6);
         this.scene.add(ambientLight);
-        const directionalLight = new three.DirectionalLight(0xffffff, 0.8);
+        this.defaultLights.push(ambientLight);
+        const directionalLight = new three.DirectionalLight(0xffffff, params.directionalIntensity ?? 0.8);
         directionalLight.position.set(5, 10, 7.5);
+        if (this.shadows) {
+            directionalLight.castShadow = true;
+            directionalLight.shadow.mapSize.set(1024, 1024);
+        }
         this.scene.add(directionalLight);
+        this.defaultLights.push(directionalLight);
+        if (params.hemisphereLight !== false) {
+            const hemi = typeof params.hemisphereLight === 'object' ? params.hemisphereLight : {};
+            const hemisphereLight = new three.HemisphereLight(hemi.skyColor ?? 0xffffff, hemi.groundColor ?? 0x444444, hemi.intensity ?? 0.35);
+            this.scene.add(hemisphereLight);
+            this.defaultLights.push(hemisphereLight);
+        }
+        if (params.fog) {
+            const fog = typeof params.fog === 'object' ? params.fog : {};
+            this.scene.fog = new three.Fog(fog.color ?? backgroundColor, fog.near ?? 8, fog.far ?? 40);
+        }
         this.clock = new three.Clock();
     }
     update() {
@@ -59,10 +202,25 @@ class ThreeContext {
         }
         this.renderer.render(this.scene, this.camera);
     }
-    attachParsedModel(id, model, animations) {
+    hasTransform3DRoot(id) {
+        return isTransform3DRoot(this.nodes.get(id));
+    }
+    applyModelShadows(object) {
+        if (!this.shadows)
+            return;
+        object.traverse((child) => {
+            const mesh = child;
+            if (mesh.isMesh) {
+                mesh.castShadow = true;
+                mesh.receiveShadow = true;
+            }
+        });
+    }
+    attachParsedModel(id, model, animations, gameObject) {
         tagObject3D(model, id);
-        this.scene.add(model);
+        this.applyModelShadows(model);
         this.models.set(id, model);
+        this.attachVisual(id, model, gameObject);
         if (animations && animations.length > 0) {
             const mixer = new three.AnimationMixer(model);
             this.mixers.set(id, mixer);
@@ -70,6 +228,185 @@ class ThreeContext {
         }
         return model;
     }
+    object3DFor(id) {
+        return this.nodes.get(id);
+    }
+    /** Place a GameObject's root Object3D under the nearest ancestor visual (or the scene). */
+    attachObject3D(id, object, gameObject) {
+        const prev = this.nodes.get(id);
+        if (prev && prev !== object) {
+            this.rehomeRegisteredChildren(prev);
+            prev.parent?.remove(prev);
+        }
+        this.nodes.set(id, object);
+        const parentNode = this.findParentNode(gameObject);
+        if (object.parent !== parentNode) {
+            parentNode.add(object);
+        }
+        if (gameObject) {
+            this.adoptChildGameObjects(gameObject, object);
+        }
+    }
+    /**
+     * Attach a visual / camera / light under the Transform3D root when one exists.
+     * Otherwise the object itself becomes the GameObject root (legacy path).
+     */
+    attachVisual(id, object, gameObject) {
+        tagObject3D(object, id);
+        const root = this.nodes.get(id);
+        if (isTransform3DRoot(root) && root !== object) {
+            if (object.parent !== root) {
+                root.add(object);
+            }
+            return;
+        }
+        this.attachObject3D(id, object, gameObject);
+    }
+    detachVisual(id, object) {
+        const root = this.nodes.get(id);
+        if (isTransform3DRoot(root) && root !== object) {
+            object.parent?.remove(object);
+            return object;
+        }
+        if (root === object) {
+            return this.detachObject3D(id);
+        }
+        object.parent?.remove(object);
+        return object;
+    }
+    /** Remove a registered node without disposing it; child GameObject nodes stay in the scene. */
+    detachObject3D(id) {
+        const object = this.nodes.get(id);
+        if (!object)
+            return undefined;
+        this.rehomeRegisteredChildren(object);
+        object.parent?.remove(object);
+        this.nodes.delete(id);
+        return object;
+    }
+    reparentGameObject(gameObject) {
+        const object = this.nodes.get(gameObject.id);
+        if (!object)
+            return;
+        const parentNode = this.findParentNode(gameObject);
+        if (object.parent === parentNode)
+            return;
+        parentNode.add(object);
+    }
+    findParentNode(gameObject) {
+        if (!gameObject || is3DSceneParent(gameObject)) {
+            return this.scene;
+        }
+        let current = gameObject.parent;
+        while (current && current !== gameObject.scene) {
+            const node = this.nodes.get(current.id);
+            if (node)
+                return node;
+            current = current.parent;
+        }
+        return this.scene;
+    }
+    adoptChildGameObjects(gameObject, object) {
+        const children = gameObject.transform?.children;
+        if (!children)
+            return;
+        for (const childTransform of children) {
+            const childGo = childTransform.gameObject;
+            if (!childGo)
+                continue;
+            const childNode = this.nodes.get(childGo.id);
+            if (childNode && childNode.parent !== object) {
+                object.add(childNode);
+            }
+        }
+    }
+    ensureTransformRoot(gameObject, transform) {
+        const existing = this.nodes.get(gameObject.id);
+        if (isTransform3DRoot(existing)) {
+            this.applyTransformPose(existing, transform);
+            return existing;
+        }
+        const group = new three.Group();
+        group.name = gameObject.name;
+        group.userData[COMBOS_TRANSFORM3D] = true;
+        tagObject3D(group, gameObject.id);
+        if (existing && existing !== group) {
+            if (isIdentityPoseObject(transform)) {
+                transform.positionX = existing.position.x;
+                transform.positionY = existing.position.y;
+                transform.positionZ = existing.position.z;
+                transform.rotationX = existing.rotation.x;
+                transform.rotationY = existing.rotation.y;
+                transform.rotationZ = existing.rotation.z;
+                transform.scaleX = existing.scale.x;
+                transform.scaleY = existing.scale.y;
+                transform.scaleZ = existing.scale.z;
+            }
+            const parent = existing.parent || this.scene;
+            parent.add(group);
+            group.add(existing);
+            existing.position.set(0, 0, 0);
+            existing.rotation.set(0, 0, 0);
+            existing.scale.set(1, 1, 1);
+            this.nodes.set(gameObject.id, group);
+            this.adoptChildGameObjects(gameObject, group);
+        }
+        else {
+            this.attachObject3D(gameObject.id, group, gameObject);
+        }
+        this.applyTransformPose(group, transform);
+        return group;
+    }
+    applyTransform3D(gameObject, transform) {
+        const root = this.ensureTransformRoot(gameObject, transform);
+        this.applyTransformPose(root, transform);
+        root.updateWorldMatrix(true, false);
+        root.getWorldPosition(_world);
+        transform.worldPositionX = _world.x;
+        transform.worldPositionY = _world.y;
+        transform.worldPositionZ = _world.z;
+        _euler.setFromRotationMatrix(root.matrixWorld);
+        transform.worldRotationX = _euler.x;
+        transform.worldRotationY = _euler.y;
+        transform.worldRotationZ = _euler.z;
+        return root;
+    }
+    applyTransformPose(root, transform) {
+        const pose = readPose(transform);
+        root.position.set(pose.positionX, pose.positionY, pose.positionZ);
+        root.rotation.set(pose.rotationX, pose.rotationY, pose.rotationZ);
+        root.scale.set(pose.scaleX, pose.scaleY, pose.scaleZ);
+    }
+    removeDefaultLights() {
+        if (!this.defaultLights.length)
+            return;
+        for (const light of this.defaultLights) {
+            light.parent?.remove(light);
+            light.dispose?.();
+        }
+        this.defaultLights = [];
+    }
+    setActiveCamera(camera) {
+        const prev = this.camera;
+        this.camera = camera;
+        if (prev) {
+            camera.aspect = prev.aspect;
+        }
+        camera.updateProjectionMatrix();
+    }
+    restoreFallbackCamera() {
+        if (this.camera !== this.fallbackCamera) {
+            this.setActiveCamera(this.fallbackCamera);
+        }
+    }
+    rehomeRegisteredChildren(object) {
+        for (const child of [...object.children]) {
+            const childId = child.userData?.[COMBOS_GAME_OBJECT_ID];
+            if (typeof childId === 'number' && this.nodes.get(childId) === child) {
+                this.scene.add(child);
+            }
+        }
+    }
     playAnimation(id, animationIndex, speed) {
         const mixer = this.mixers.get(id);
         const model = this.models.get(id);
@@ -91,7 +428,7 @@ class ThreeContext {
     removeModel(id) {
         const model = this.models.get(id);
         if (model) {
-            this.scene.remove(model);
+            this.detachVisual(id, model);
             model.traverse((child) => {
                 const mesh = child;
                 if (mesh.geometry) {
@@ -115,20 +452,33 @@ class ThreeContext {
     resize(width, height) {
         this.camera.aspect = width / height;
         this.camera.updateProjectionMatrix();
+        if (this.fallbackCamera !== this.camera) {
+            this.fallbackCamera.aspect = width / height;
+            this.fallbackCamera.updateProjectionMatrix();
+        }
         this.renderer.setSize(width, height);
     }
     destroy() {
         for (const id of this.models.keys()) {
             this.removeModel(id);
         }
+        this.removeDefaultLights();
         this.renderer.dispose();
         this.renderer.domElement.remove();
+        this.nodes.clear();
         this.scene = null;
         this.camera = null;
+        this.fallbackCamera = null;
         this.renderer = null;
         this.clock = null;
     }
 }
+function isIdentityPoseObject(transform) {
+    const pose = readPose(transform);
+    return pose.positionX === 0 && pose.positionY === 0 && pose.positionZ === 0
+        && pose.rotationX === 0 && pose.rotationY === 0 && pose.rotationZ === 0
+        && pose.scaleX === 1 && pose.scaleY === 1 && pose.scaleZ === 1;
+}
 
 class Renderer3DManager {
     constructor({ game, rendererSystem }) {
@@ -195,7 +545,60 @@ class Renderer3DManager {
     }
 }
 
-class Renderer3DSystem extends engine.System {
+class Transform3D extends engine.Component {
+    constructor() {
+        super(...arguments);
+        this.positionX = 0;
+        this.positionY = 0;
+        this.positionZ = 0;
+        this.rotationX = 0;
+        this.rotationY = 0;
+        this.rotationZ = 0;
+        this.scaleX = 1;
+        this.scaleY = 1;
+        this.scaleZ = 1;
+        this.worldPositionX = 0;
+        this.worldPositionY = 0;
+        this.worldPositionZ = 0;
+        this.worldRotationX = 0;
+        this.worldRotationY = 0;
+        this.worldRotationZ = 0;
+    }
+    static { this.componentName = 'Transform3D'; }
+    init(obj) {
+        if (obj)
+            Object.assign(this, obj);
+    }
+}
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Transform3D', label: 'positionX', editor: 'number-stepper' })
+], Transform3D.prototype, "positionX", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Transform3D', label: 'positionY', editor: 'number-stepper' })
+], Transform3D.prototype, "positionY", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Transform3D', label: 'positionZ', editor: 'number-stepper' })
+], Transform3D.prototype, "positionZ", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.01, group: 'Transform3D', label: 'rotationX', editor: 'number-stepper' })
+], Transform3D.prototype, "rotationX", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.01, group: 'Transform3D', label: 'rotationY', editor: 'number-stepper' })
+], Transform3D.prototype, "rotationY", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.01, group: 'Transform3D', label: 'rotationZ', editor: 'number-stepper' })
+], Transform3D.prototype, "rotationZ", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Transform3D', label: 'scaleX', editor: 'number-stepper' })
+], Transform3D.prototype, "scaleX", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Transform3D', label: 'scaleY', editor: 'number-stepper' })
+], Transform3D.prototype, "scaleY", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Transform3D', label: 'scaleZ', editor: 'number-stepper' })
+], Transform3D.prototype, "scaleZ", void 0);
+
+let Renderer3DSystem$1 = class Renderer3DSystem extends engine.System {
     constructor() {
         super(...arguments);
         this.name = 'Renderer3DSystem';
@@ -213,6 +616,13 @@ class Renderer3DSystem extends engine.System {
             antialias: opts.antialias,
             backgroundColor: opts.backgroundColor,
             backgroundAlpha: opts.backgroundAlpha,
+            fog: opts.fog,
+            hemisphereLight: opts.hemisphereLight,
+            shadows: opts.shadows,
+            toneMapping: opts.toneMapping,
+            toneMappingExposure: opts.toneMappingExposure,
+            ambientIntensity: opts.ambientIntensity,
+            directionalIntensity: opts.directionalIntensity,
         });
         this.game.canvas = this.threeContext.renderer.domElement;
         this.rendererManager = new Renderer3DManager({
@@ -221,10 +631,38 @@ class Renderer3DSystem extends engine.System {
         });
     }
     update(e) {
+        const changes = this.componentObserver.clear();
+        for (const changed of changes) {
+            this.handleHierarchyChange(changed);
+        }
         for (const gameObject of this.game.gameObjects) {
+            const transform = gameObject.getComponent(Transform3D);
+            if (transform) {
+                this.threeContext.applyTransform3D(gameObject, transform);
+            }
             this.rendererManager.update(gameObject);
         }
     }
+    handleHierarchyChange(changed) {
+        if (changed.componentName !== 'Transform')
+            return;
+        if (changed.type !== engine.OBSERVER_TYPE.CHANGE && changed.type !== engine.OBSERVER_TYPE.ADD)
+            return;
+        this.ensureTransform3D(changed.gameObject);
+        if (changed.gameObject.parent)
+            this.ensureTransform3D(changed.gameObject.parent);
+        this.threeContext?.reparentGameObject(changed.gameObject);
+    }
+    ensureTransform3D(gameObject) {
+        if (!gameObject || gameObject === gameObject.scene)
+            return;
+        let transform = gameObject.getComponent(Transform3D);
+        if (!transform) {
+            transform = new Transform3D();
+            gameObject.addComponent(transform);
+        }
+        this.threeContext?.ensureTransformRoot(gameObject, transform);
+    }
     lateUpdate() {
         this.threeContext?.update();
     }
@@ -235,12 +673,18 @@ class Renderer3DSystem extends engine.System {
         this.threeContext?.destroy();
         this.threeContext = null;
     }
-}
+};
+Renderer3DSystem$1 = tslib.__decorate([
+    engine.decorators.componentObserver({
+        Transform: ['_parent'],
+    })
+], Renderer3DSystem$1);
+var Renderer3DSystem = Renderer3DSystem$1;
 
 /** Auto-generated by scripts/build-package.mjs — do not edit. */
 Object.assign(Renderer3DSystem, {
     packageName: "@combos-fun/plugin-renderer-3d",
-    packageVersion: "0.0.41",
+    packageVersion: "0.0.44",
 });
 
 class Renderer3D extends engine.System {
@@ -267,6 +711,492 @@ class Renderer3D extends engine.System {
     }
 }
 
+const POSE_PROPS = new Set([
+    'positionX', 'positionY', 'positionZ',
+    'rotationX', 'rotationY', 'rotationZ',
+    'scaleX', 'scaleY', 'scaleZ',
+]);
+let Transform3DSystem = class Transform3DSystem extends Renderer3D {
+    constructor() {
+        super(...arguments);
+        this.name = 'Transform3DSystem';
+    }
+    static { this.systemName = 'Transform3DSystem'; }
+    init() {
+        const renderer3DSystem = this.game.getSystem('Renderer3DSystem');
+        renderer3DSystem.rendererManager.register(this);
+    }
+    componentChanged(changed) {
+        if (changed.componentName === 'Transform') {
+            this.ensureOn(changed.gameObject);
+            if (changed.gameObject.parent)
+                this.ensureOn(changed.gameObject.parent);
+            this.threeContext.reparentGameObject(changed.gameObject);
+            return;
+        }
+        if (changed.componentName !== 'Transform3D')
+            return;
+        if (changed.type === engine.OBSERVER_TYPE.ADD) {
+            this.threeContext.ensureTransformRoot(changed.gameObject, changed.component);
+        }
+        else if (changed.type === engine.OBSERVER_TYPE.REMOVE) {
+            this.threeContext.detachObject3D(changed.gameObject.id);
+        }
+        else if (POSE_PROPS.has(changed.prop?.prop?.[0])) {
+            this.threeContext.applyTransform3D(changed.gameObject, changed.component);
+        }
+    }
+    rendererUpdate(gameObject) {
+        const transform = gameObject.getComponent(Transform3D);
+        if (!transform)
+            return;
+        this.threeContext.applyTransform3D(gameObject, transform);
+    }
+    ensureOn(gameObject) {
+        if (!gameObject || gameObject === gameObject.scene)
+            return;
+        let transform = gameObject.getComponent(Transform3D);
+        if (!transform) {
+            transform = new Transform3D();
+            gameObject.addComponent(transform);
+        }
+        this.threeContext.ensureTransformRoot(gameObject, transform);
+    }
+};
+Transform3DSystem = tslib.__decorate([
+    engine.decorators.componentObserver({
+        Transform3D: [
+            'positionX', 'positionY', 'positionZ',
+            'rotationX', 'rotationY', 'rotationZ',
+            'scaleX', 'scaleY', 'scaleZ',
+        ],
+        Transform: ['_parent'],
+    })
+], Transform3DSystem);
+var Transform3DSystem_default = Transform3DSystem;
+
+class Render3D extends engine.Component {
+    constructor() {
+        super(...arguments);
+        this.visible = true;
+        this.opacity = 1;
+        this.renderOrder = 0;
+        this.sortableChildren = false;
+    }
+    static { this.componentName = 'Render3D'; }
+    init(obj) {
+        if (obj)
+            Object.assign(this, obj);
+    }
+}
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'boolean', group: 'Render3D', label: 'visible', editor: 'toggle' })
+], Render3D.prototype, "visible", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.01, min: 0, max: 1, group: 'Render3D', label: 'opacity', editor: 'number-slider' })
+], Render3D.prototype, "opacity", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 1, group: 'Render3D', label: 'renderOrder', editor: 'number-stepper' })
+], Render3D.prototype, "renderOrder", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'boolean', group: 'Render3D', label: 'sortableChildren', editor: 'toggle' })
+], Render3D.prototype, "sortableChildren", void 0);
+
+let Render3DSystem = class Render3DSystem extends Renderer3D {
+    constructor() {
+        super(...arguments);
+        this.name = 'Render3DSystem';
+    }
+    static { this.systemName = 'Render3DSystem'; }
+    init() {
+        const renderer3DSystem = this.game.getSystem('Renderer3DSystem');
+        renderer3DSystem.rendererManager.register(this);
+    }
+    componentChanged(changed) {
+        if (changed.componentName !== 'Render3D')
+            return;
+        if (changed.type === engine.OBSERVER_TYPE.REMOVE) {
+            const root = this.threeContext.object3DFor(changed.gameObject.id);
+            if (root)
+                this.apply(root, { visible: true, opacity: 1, renderOrder: 0, sortableChildren: false });
+            return;
+        }
+        this.applyTo(changed.gameObject, changed.component);
+    }
+    rendererUpdate(gameObject) {
+        const component = gameObject.getComponent(Render3D);
+        if (!component)
+            return;
+        this.applyTo(gameObject, component);
+    }
+    applyTo(gameObject, component) {
+        const root = this.threeContext.object3DFor(gameObject.id);
+        if (!root)
+            return;
+        this.apply(root, component);
+        if (component.sortableChildren) {
+            this.sortChildren(gameObject, root);
+        }
+    }
+    apply(root, component) {
+        root.visible = component.visible;
+        root.traverse((child) => {
+            child.renderOrder = component.renderOrder;
+            const mesh = child;
+            if (!mesh.isMesh || !mesh.material)
+                return;
+            const materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+            for (const material of materials) {
+                const mat = material;
+                if (typeof mat.opacity === 'number') {
+                    mat.opacity = component.opacity;
+                    mat.transparent = component.opacity < 1;
+                }
+            }
+        });
+    }
+    sortChildren(gameObject, root) {
+        const ranked = gameObject.transform?.children
+            ?.map((childTransform) => {
+            const childGo = childTransform.gameObject;
+            if (!childGo)
+                return null;
+            const node = this.threeContext.object3DFor(childGo.id);
+            if (!node || node.parent !== root)
+                return null;
+            const render = childGo.getComponent(Render3D);
+            return { node, order: render?.renderOrder ?? 0 };
+        })
+            .filter((item) => !!item)
+            .sort((a, b) => a.order - b.order);
+        if (!ranked?.length)
+            return;
+        for (const item of ranked) {
+            root.add(item.node);
+        }
+    }
+};
+Render3DSystem = tslib.__decorate([
+    engine.decorators.componentObserver({
+        Render3D: ['visible', 'opacity', 'renderOrder', 'sortableChildren'],
+    })
+], Render3DSystem);
+var Render3DSystem_default = Render3DSystem;
+
+class Camera3D extends engine.Component {
+    constructor() {
+        super(...arguments);
+        this.fov = 75;
+        this.near = 0.1;
+        this.far = 1000;
+        this.active = true;
+        this.lookAt = false;
+        this.lookAtX = 0;
+        this.lookAtY = 0;
+        this.lookAtZ = 0;
+    }
+    static { this.componentName = 'Camera3D'; }
+    init(obj) {
+        if (obj)
+            Object.assign(this, obj);
+    }
+}
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 1, group: 'Camera3D', label: 'fov', editor: 'number-stepper' })
+], Camera3D.prototype, "fov", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.01, group: 'Camera3D', label: 'near', editor: 'number-stepper' })
+], Camera3D.prototype, "near", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 1, group: 'Camera3D', label: 'far', editor: 'number-stepper' })
+], Camera3D.prototype, "far", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'boolean', group: 'Camera3D', label: 'active', editor: 'toggle' })
+], Camera3D.prototype, "active", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'boolean', group: 'Camera3D', label: 'lookAt', editor: 'toggle' })
+], Camera3D.prototype, "lookAt", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Camera3D', label: 'lookAtX', editor: 'number-stepper' })
+], Camera3D.prototype, "lookAtX", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Camera3D', label: 'lookAtY', editor: 'number-stepper' })
+], Camera3D.prototype, "lookAtY", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Camera3D', label: 'lookAtZ', editor: 'number-stepper' })
+], Camera3D.prototype, "lookAtZ", void 0);
+
+let Camera3DSystem = class Camera3DSystem extends Renderer3D {
+    constructor() {
+        super(...arguments);
+        this.name = 'Camera3DSystem';
+        this.cameras = new Map();
+    }
+    static { this.systemName = 'Camera3DSystem'; }
+    init() {
+        const renderer3DSystem = this.game.getSystem('Renderer3DSystem');
+        renderer3DSystem.rendererManager.register(this);
+    }
+    componentChanged(changed) {
+        if (changed.componentName !== 'Camera3D')
+            return;
+        const component = changed.component;
+        if (changed.type === engine.OBSERVER_TYPE.ADD) {
+            this.mount(changed.gameObject, component);
+        }
+        else if (changed.type === engine.OBSERVER_TYPE.REMOVE) {
+            this.unmount(changed.gameObject.id);
+        }
+        else {
+            this.sync(changed.gameObject, component);
+        }
+    }
+    rendererUpdate(gameObject) {
+        const component = gameObject.getComponent(Camera3D);
+        const camera = this.cameras.get(gameObject.id);
+        if (!component || !camera)
+            return;
+        if (component.lookAt) {
+            camera.lookAt(component.lookAtX, component.lookAtY, component.lookAtZ);
+        }
+    }
+    mount(gameObject, component) {
+        this.ensureTransform(gameObject);
+        const camera = new three.PerspectiveCamera(component.fov, this.threeContext.camera.aspect, component.near, component.far);
+        this.threeContext.attachVisual(gameObject.id, camera, gameObject);
+        this.cameras.set(gameObject.id, camera);
+        this.sync(gameObject, component);
+    }
+    sync(gameObject, component) {
+        const camera = this.cameras.get(gameObject.id);
+        if (!camera)
+            return;
+        camera.fov = component.fov;
+        camera.near = component.near;
+        camera.far = component.far;
+        camera.updateProjectionMatrix();
+        if (component.active) {
+            this.threeContext.setActiveCamera(camera);
+        }
+        else if (this.threeContext.camera === camera) {
+            this.activateAnother(gameObject.id);
+        }
+    }
+    unmount(id) {
+        const camera = this.cameras.get(id);
+        if (!camera)
+            return;
+        this.threeContext.detachVisual(id, camera);
+        this.cameras.delete(id);
+        if (this.threeContext.camera === camera) {
+            this.activateAnother(id);
+        }
+    }
+    activateAnother(exceptId) {
+        for (const [id, camera] of this.cameras) {
+            if (id === exceptId)
+                continue;
+            const go = this.game.gameObjects.find((item) => item.id === id);
+            const component = go?.getComponent(Camera3D);
+            if (component?.active) {
+                this.threeContext.setActiveCamera(camera);
+                return;
+            }
+        }
+        this.threeContext.restoreFallbackCamera();
+    }
+    ensureTransform(gameObject) {
+        let transform = gameObject.getComponent(Transform3D);
+        if (!transform) {
+            transform = new Transform3D();
+            transform.positionZ = 5;
+            gameObject.addComponent(transform);
+            return;
+        }
+        if (isIdentityPose(transform)) {
+            transform.positionZ = 5;
+        }
+    }
+    onDestroy() {
+        for (const [id] of this.cameras) {
+            this.unmount(id);
+        }
+        this.cameras.clear();
+    }
+};
+Camera3DSystem = tslib.__decorate([
+    engine.decorators.componentObserver({
+        Camera3D: ['fov', 'near', 'far', 'active', 'lookAt', 'lookAtX', 'lookAtY', 'lookAtZ'],
+    })
+], Camera3DSystem);
+var Camera3DSystem_default = Camera3DSystem;
+
+class Light3D extends engine.Component {
+    constructor() {
+        super(...arguments);
+        this.type = 'directional';
+        this.color = 0xffffff;
+        this.intensity = 1;
+        this.castShadow = false;
+        this.skyColor = 0xffffff;
+        this.groundColor = 0x444444;
+        this.distance = 0;
+        this.decay = 2;
+        this.angle = Math.PI / 3;
+        this.penumbra = 0;
+    }
+    static { this.componentName = 'Light3D'; }
+    init(obj) {
+        if (obj)
+            Object.assign(this, obj);
+    }
+}
+tslib.__decorate([
+    inspectorDecorator.Field({
+        type: 'string',
+        group: 'Light3D',
+        label: 'type',
+        editor: 'enum',
+        enumOptions: ['ambient', 'directional', 'hemisphere', 'point', 'spot'],
+    })
+], Light3D.prototype, "type", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', group: 'Light3D', label: 'color', editor: 'number-stepper' })
+], Light3D.prototype, "color", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.05, group: 'Light3D', label: 'intensity', editor: 'number-stepper' })
+], Light3D.prototype, "intensity", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'boolean', group: 'Light3D', label: 'castShadow', editor: 'toggle' })
+], Light3D.prototype, "castShadow", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', group: 'Light3D', label: 'skyColor', editor: 'number-stepper' })
+], Light3D.prototype, "skyColor", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', group: 'Light3D', label: 'groundColor', editor: 'number-stepper' })
+], Light3D.prototype, "groundColor", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Light3D', label: 'distance', editor: 'number-stepper' })
+], Light3D.prototype, "distance", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.1, group: 'Light3D', label: 'decay', editor: 'number-stepper' })
+], Light3D.prototype, "decay", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.01, group: 'Light3D', label: 'angle', editor: 'number-stepper' })
+], Light3D.prototype, "angle", void 0);
+tslib.__decorate([
+    inspectorDecorator.Field({ type: 'number', step: 0.01, min: 0, max: 1, group: 'Light3D', label: 'penumbra', editor: 'number-slider' })
+], Light3D.prototype, "penumbra", void 0);
+
+let Light3DSystem = class Light3DSystem extends Renderer3D {
+    constructor() {
+        super(...arguments);
+        this.name = 'Light3DSystem';
+        this.lights = new Map();
+    }
+    static { this.systemName = 'Light3DSystem'; }
+    init() {
+        const renderer3DSystem = this.game.getSystem('Renderer3DSystem');
+        renderer3DSystem.rendererManager.register(this);
+    }
+    componentChanged(changed) {
+        if (changed.componentName !== 'Light3D')
+            return;
+        const component = changed.component;
+        if (changed.type === engine.OBSERVER_TYPE.ADD) {
+            this.mount(changed.gameObject, component);
+        }
+        else if (changed.type === engine.OBSERVER_TYPE.REMOVE) {
+            this.unmount(changed.gameObject.id);
+        }
+        else if (changed.prop?.prop?.[0] === 'type') {
+            this.unmount(changed.gameObject.id);
+            this.mount(changed.gameObject, component);
+        }
+        else {
+            this.sync(changed.gameObject.id, component);
+        }
+    }
+    rendererUpdate(_gameObject) { }
+    mount(gameObject, component) {
+        this.ensureTransform(gameObject);
+        if (this.lights.size === 0) {
+            this.threeContext.removeDefaultLights();
+        }
+        const light = this.createLight(component);
+        this.threeContext.attachVisual(gameObject.id, light, gameObject);
+        this.lights.set(gameObject.id, light);
+        this.sync(gameObject.id, component);
+    }
+    createLight(component) {
+        switch (component.type) {
+            case 'ambient':
+                return new three.AmbientLight(component.color, component.intensity);
+            case 'hemisphere':
+                return new three.HemisphereLight(component.skyColor, component.groundColor, component.intensity);
+            case 'point':
+                return new three.PointLight(component.color, component.intensity, component.distance, component.decay);
+            case 'spot':
+                return new three.SpotLight(component.color, component.intensity, component.distance, component.angle, component.penumbra, component.decay);
+            case 'directional':
+            default:
+                return new three.DirectionalLight(component.color, component.intensity);
+        }
+    }
+    sync(id, component) {
+        const light = this.lights.get(id);
+        if (!light)
+            return;
+        if ('color' in light && light.color) {
+            light.color.set(component.color);
+        }
+        light.intensity = component.intensity;
+        if (light instanceof three.HemisphereLight) {
+            light.color.set(component.skyColor);
+            light.groundColor.set(component.groundColor);
+        }
+        if (light instanceof three.PointLight || light instanceof three.SpotLight) {
+            light.distance = component.distance;
+            light.decay = component.decay;
+        }
+        if (light instanceof three.SpotLight) {
+            light.angle = component.angle;
+            light.penumbra = component.penumbra;
+        }
+        if ('castShadow' in light) {
+            light.castShadow = !!(component.castShadow && this.threeContext.shadows);
+        }
+    }
+    unmount(id) {
+        const light = this.lights.get(id);
+        if (!light)
+            return;
+        this.threeContext.detachVisual(id, light);
+        light.dispose?.();
+        this.lights.delete(id);
+    }
+    ensureTransform(gameObject) {
+        if (gameObject.getComponent(Transform3D))
+            return;
+        gameObject.addComponent(new Transform3D());
+    }
+    onDestroy() {
+        for (const [id] of this.lights) {
+            this.unmount(id);
+        }
+        this.lights.clear();
+    }
+};
+Light3DSystem = tslib.__decorate([
+    engine.decorators.componentObserver({
+        Light3D: [
+            'type', 'color', 'intensity', 'castShadow',
+            'skyColor', 'groundColor', 'distance', 'decay', 'angle', 'penumbra',
+        ],
+    })
+], Light3DSystem);
+var Light3DSystem_default = Light3DSystem;
+
 async function requireNamedResource(name) {
     const trimmed = String(name ?? '').trim();
     if (!trimmed) {
@@ -295,12 +1225,32 @@ async function textureFromNamedImage(name) {
 }
 
 exports.COMBOS_GAME_OBJECT_ID = COMBOS_GAME_OBJECT_ID;
+exports.COMBOS_INSTANCE_GAME_OBJECT_IDS = COMBOS_INSTANCE_GAME_OBJECT_IDS;
+exports.COMBOS_TRANSFORM3D = COMBOS_TRANSFORM3D;
+exports.Camera3D = Camera3D;
+exports.Camera3DSystem = Camera3DSystem_default;
+exports.Light3D = Light3D;
+exports.Light3DSystem = Light3DSystem_default;
+exports.Render3D = Render3D;
+exports.Render3DSystem = Render3DSystem_default;
 exports.Renderer3D = Renderer3D;
 exports.Renderer3DManager = Renderer3DManager;
 exports.Renderer3DSystem = Renderer3DSystem;
 exports.ThreeContext = ThreeContext;
+exports.Transform3D = Transform3D;
+exports.Transform3DSystem = Transform3DSystem_default;
+exports.VisualPoseBridge = VisualPoseBridge;
+exports.copyPose = copyPose;
+exports.gameObjectIdFromIntersection = gameObjectIdFromIntersection;
 exports.gameObjectIdFromObject3D = gameObjectIdFromObject3D;
+exports.has3DChildGameObjects = has3DChildGameObjects;
+exports.is3DSceneParent = is3DSceneParent;
+exports.isIdentityPose = isIdentityPose;
+exports.isTransform3DRoot = isTransform3DRoot;
+exports.poseKeyOf = poseKeyOf;
+exports.readPose = readPose;
 exports.requireNamedResource = requireNamedResource;
+exports.seedTransform3D = seedTransform3D;
 exports.tagObject3D = tagObject3D;
 exports.textureFromNamedImage = textureFromNamedImage;
 exports.textureFromResourceImage = textureFromResourceImage;