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

package/dist/plugin-renderer-3d.d.ts

@@ -1,6 +1,54 @@
-import { System, Game, PureObserverInfo, ComponentChanged, GameObject, UpdateParams, ResourceStruct } from '@combos-fun/engine';
-import { Scene, PerspectiveCamera, WebGLRenderer, Clock, AnimationMixer, Group, AnimationClip, Object3D, Texture } from 'three';
+import { GameObject, System, Game, PureObserverInfo, ComponentChanged, UpdateParams, Component, ResourceStruct } from '@combos-fun/engine';
+import { Scene, PerspectiveCamera, WebGLRenderer, Clock, AnimationMixer, Group, Object3D, AnimationClip, Texture } from 'three';
 
+interface PoseLike {
+    positionX?: number;
+    positionY?: number;
+    positionZ?: number;
+    rotationX?: number;
+    rotationY?: number;
+    rotationZ?: number;
+    scaleX?: number;
+    scaleY?: number;
+    scaleZ?: number;
+}
+declare function readPose(pose: PoseLike): {
+    positionX: number;
+    positionY: number;
+    positionZ: number;
+    rotationX: number;
+    rotationY: number;
+    rotationZ: number;
+    scaleX: number;
+    scaleY: number;
+    scaleZ: number;
+};
+declare function poseKeyOf(pose: PoseLike): string;
+declare function copyPose(from: PoseLike, to: PoseLike): void;
+declare function isIdentityPose(pose: PoseLike): boolean;
+declare function seedTransform3D(visual: PoseLike, transform: PoseLike): void;
+/**
+ * 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).
+ */
+declare class VisualPoseBridge {
+    lastVisual: string;
+    lastRoot: string;
+    sync(visual: PoseLike, root?: PoseLike | null): boolean;
+}
+
+type ToneMappingKind = 'none' | 'aces' | 'linear' | 'reinhard' | 'cineon';
+interface FogParams {
+    color?: number;
+    near?: number;
+    far?: number;
+}
+interface HemisphereLightParams {
+    skyColor?: number;
+    groundColor?: number;
+    intensity?: number;
+}
 interface ThreeContextParams {
     canvas?: HTMLCanvasElement;
     container?: HTMLElement;
@@ -9,17 +57,60 @@ interface ThreeContextParams {
     antialias?: boolean;
     backgroundColor?: number;
     backgroundAlpha?: number;
+    fog?: boolean | FogParams;
+    hemisphereLight?: boolean | HemisphereLightParams;
+    shadows?: boolean;
+    toneMapping?: ToneMappingKind;
+    toneMappingExposure?: number;
+    ambientIntensity?: number;
+    directionalIntensity?: number;
+}
+interface Transform3DLike extends PoseLike {
+    worldPositionX?: number;
+    worldPositionY?: number;
+    worldPositionZ?: number;
+    worldRotationX?: number;
+    worldRotationY?: number;
+    worldRotationZ?: number;
 }
 declare class ThreeContext {
     scene: Scene;
     camera: PerspectiveCamera;
+    fallbackCamera: PerspectiveCamera;
     renderer: WebGLRenderer;
     clock: Clock;
     mixers: Map<number, AnimationMixer>;
     models: Map<number, Group>;
+    /** Root Object3D for each GameObject that has a 3D node. */
+    nodes: Map<number, Object3D>;
+    shadows: boolean;
+    defaultLights: Object3D[];
     constructor(params: ThreeContextParams);
     update(): void;
-    attachParsedModel(id: number, model: Group, animations?: AnimationClip[]): Group;
+    hasTransform3DRoot(id: number): boolean;
+    applyModelShadows(object: Object3D): void;
+    attachParsedModel(id: number, model: Group, animations?: AnimationClip[], gameObject?: GameObject): Group;
+    object3DFor(id: number): Object3D | undefined;
+    /** Place a GameObject's root Object3D under the nearest ancestor visual (or the scene). */
+    attachObject3D(id: number, object: Object3D, gameObject?: GameObject): void;
+    /**
+     * Attach a visual / camera / light under the Transform3D root when one exists.
+     * Otherwise the object itself becomes the GameObject root (legacy path).
+     */
+    attachVisual(id: number, object: Object3D, gameObject?: GameObject): void;
+    detachVisual(id: number, object: Object3D): Object3D | undefined;
+    /** Remove a registered node without disposing it; child GameObject nodes stay in the scene. */
+    detachObject3D(id: number): Object3D | undefined;
+    reparentGameObject(gameObject: GameObject): void;
+    findParentNode(gameObject?: GameObject): Object3D;
+    adoptChildGameObjects(gameObject: GameObject, object: Object3D): void;
+    ensureTransformRoot(gameObject: GameObject, transform: Transform3DLike): Object3D;
+    applyTransform3D(gameObject: GameObject, transform: Transform3DLike): Object3D;
+    private applyTransformPose;
+    removeDefaultLights(): void;
+    setActiveCamera(camera: PerspectiveCamera): void;
+    restoreFallbackCamera(): void;
+    private rehomeRegisteredChildren;
     playAnimation(id: number, animationIndex: number, speed: number): void;
     stopAnimation(id: number): void;
     removeModel(id: number): void;
@@ -72,19 +163,180 @@ declare class Renderer3DSystem extends System<Renderer3DSystemParams> {
     rendererManager: Renderer3DManager;
     init(params?: Renderer3DSystemParams): void;
     update(e?: UpdateParams): void;
+    private handleHierarchyChange;
+    private ensureTransform3D;
     lateUpdate(): void;
     resize(width: number, height: number): void;
     onDestroy(): void;
 }
 
+interface Transform3DParams {
+    positionX?: number;
+    positionY?: number;
+    positionZ?: number;
+    rotationX?: number;
+    rotationY?: number;
+    rotationZ?: number;
+    scaleX?: number;
+    scaleY?: number;
+    scaleZ?: number;
+}
+declare class Transform3D extends Component<Transform3DParams> {
+    static componentName: string;
+    positionX: number;
+    positionY: number;
+    positionZ: number;
+    rotationX: number;
+    rotationY: number;
+    rotationZ: number;
+    scaleX: number;
+    scaleY: number;
+    scaleZ: number;
+    worldPositionX: number;
+    worldPositionY: number;
+    worldPositionZ: number;
+    worldRotationX: number;
+    worldRotationY: number;
+    worldRotationZ: number;
+    init(obj?: Transform3DParams): void;
+}
+
+interface Render3DParams {
+    visible?: boolean;
+    opacity?: number;
+    renderOrder?: number;
+    sortableChildren?: boolean;
+}
+declare class Render3D extends Component<Render3DParams> {
+    static componentName: string;
+    visible: boolean;
+    opacity: number;
+    renderOrder: number;
+    sortableChildren: boolean;
+    init(obj?: Render3DParams): void;
+}
+
+interface Camera3DParams {
+    fov?: number;
+    near?: number;
+    far?: number;
+    active?: boolean;
+    lookAtX?: number;
+    lookAtY?: number;
+    lookAtZ?: number;
+    lookAt?: boolean;
+}
+declare class Camera3D extends Component<Camera3DParams> {
+    static componentName: string;
+    fov: number;
+    near: number;
+    far: number;
+    active: boolean;
+    lookAt: boolean;
+    lookAtX: number;
+    lookAtY: number;
+    lookAtZ: number;
+    init(obj?: Camera3DParams): void;
+}
+
+type Light3DKind = 'ambient' | 'directional' | 'hemisphere' | 'point' | 'spot';
+interface Light3DParams {
+    type?: Light3DKind | string;
+    color?: number;
+    intensity?: number;
+    castShadow?: boolean;
+    skyColor?: number;
+    groundColor?: number;
+    distance?: number;
+    decay?: number;
+    angle?: number;
+    penumbra?: number;
+}
+declare class Light3D extends Component<Light3DParams> {
+    static componentName: string;
+    type: string;
+    color: number;
+    intensity: number;
+    castShadow: boolean;
+    skyColor: number;
+    groundColor: number;
+    distance: number;
+    decay: number;
+    angle: number;
+    penumbra: number;
+    init(obj?: Light3DParams): void;
+}
+
+declare class Transform3DSystem extends Renderer3D {
+    static systemName: string;
+    name: string;
+    init(): void;
+    componentChanged(changed: ComponentChanged): void;
+    rendererUpdate(gameObject: GameObject): void;
+    private ensureOn;
+}
+
+declare class Render3DSystem extends Renderer3D {
+    static systemName: string;
+    name: string;
+    init(): void;
+    componentChanged(changed: ComponentChanged): void;
+    rendererUpdate(gameObject: GameObject): void;
+    private applyTo;
+    private apply;
+    private sortChildren;
+}
+
+declare class Camera3DSystem extends Renderer3D {
+    static systemName: string;
+    name: string;
+    private cameras;
+    init(): void;
+    componentChanged(changed: ComponentChanged): void;
+    rendererUpdate(gameObject: GameObject): void;
+    private mount;
+    private sync;
+    private unmount;
+    private activateAnother;
+    private ensureTransform;
+    onDestroy(): void;
+}
+
+declare class Light3DSystem extends Renderer3D {
+    static systemName: string;
+    name: string;
+    private lights;
+    init(): void;
+    componentChanged(changed: ComponentChanged): void;
+    rendererUpdate(_gameObject: GameObject): void;
+    private mount;
+    private createLight;
+    private sync;
+    private unmount;
+    private ensureTransform;
+    onDestroy(): void;
+}
+
 declare const COMBOS_GAME_OBJECT_ID = "combosGameObjectId";
+declare const COMBOS_INSTANCE_GAME_OBJECT_IDS = "combosInstanceGameObjectIds";
+declare const COMBOS_TRANSFORM3D = "combosTransform3D";
+declare function isTransform3DRoot(object: Object3D | null | undefined): boolean;
 /** Stamp a Three.js object (and its children) so Event3D raycasts can resolve the GameObject. */
 declare function tagObject3D(object: Object3D, gameObjectId: number): void;
 declare function gameObjectIdFromObject3D(object: Object3D | null | undefined): number | undefined;
+/** Resolve a raycast hit, including InstancedMesh `instanceId` rows. */
+declare function gameObjectIdFromIntersection(intersection: {
+    object?: Object3D;
+    instanceId?: number;
+} | null | undefined): number | undefined;
 
 declare function requireNamedResource(name: string): Promise<ResourceStruct>;
 declare function textureFromResourceImage(res: ResourceStruct): Texture;
 declare function textureFromNamedImage(name: string): Promise<Texture>;
 
-export { COMBOS_GAME_OBJECT_ID, Renderer3D, Renderer3DManager, Renderer3DSystem, ThreeContext, gameObjectIdFromObject3D, requireNamedResource, tagObject3D, textureFromNamedImage, textureFromResourceImage };
-export type { Renderer3DSystemParams, ThreeContextParams };
+/** True when this GameObject is a scene root (no 3D parent). */
+declare function is3DSceneParent(gameObject: GameObject | undefined | null): boolean;
+declare function has3DChildGameObjects(gameObject: GameObject | undefined | null): boolean;
+
+export { COMBOS_GAME_OBJECT_ID, COMBOS_INSTANCE_GAME_OBJECT_IDS, COMBOS_TRANSFORM3D, Camera3D, Camera3DSystem, Light3D, Light3DSystem, Render3D, Render3DSystem, Renderer3D, Renderer3DManager, Renderer3DSystem, ThreeContext, Transform3D, Transform3DSystem, VisualPoseBridge, copyPose, gameObjectIdFromIntersection, gameObjectIdFromObject3D, has3DChildGameObjects, is3DSceneParent, isIdentityPose, isTransform3DRoot, poseKeyOf, readPose, requireNamedResource, seedTransform3D, tagObject3D, textureFromNamedImage, textureFromResourceImage };
+export type { Camera3DParams, FogParams, HemisphereLightParams, Light3DKind, Light3DParams, PoseLike, Render3DParams, Renderer3DSystemParams, ThreeContextParams, ToneMappingKind, Transform3DLike, Transform3DParams };