@waica/engine 0.24.0 → 0.26.0

package/dist/components/point-light.d.ts

@@ -0,0 +1,75 @@
+import * as THREE from 'three/webgpu';
+import { Component, type ComponentSpace } from '../component.js';
+/**
+ * A point light in a 3D scene (ADR 0027, `CONTEXT.md` Point Light): it shines
+ * in every direction from the entity's position plus an offset (in the
+ * entity's local frame: it turns and scales with the entity, so a lantern's
+ * offset follows the object it hangs on), reaching
+ * `distance` world units (0 = without limit) and fading with `decay` (2 is
+ * physical). Not the 2D `Light`, which paints a light-map. No shadows. In a
+ * 2D scene it creates nothing; the three light lives under the entity's node
+ * and leaves with it.
+ */
+export declare class PointLight extends Component {
+    static componentName: string;
+    static space: ComponentSpace;
+    static displayName: string;
+    static params: {
+        color: {
+            label: string;
+            kind: "color";
+        };
+        intensity: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        distance: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        decay: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        offsetX: {
+            label: string;
+        };
+        offsetY: {
+            label: string;
+        };
+        offsetZ: {
+            label: string;
+        };
+    };
+    static transient: string[];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light: THREE.PointLight | null;
+    private _color;
+    private _intensity;
+    private _distance;
+    private _decay;
+    private _offsetX;
+    private _offsetY;
+    private _offsetZ;
+    get color(): number;
+    set color(value: number);
+    get intensity(): number;
+    set intensity(value: number);
+    /** World units the light reaches; 0 reaches without limit. */
+    get distance(): number;
+    set distance(value: number);
+    get decay(): number;
+    set decay(value: number);
+    get offsetX(): number;
+    set offsetX(value: number);
+    get offsetY(): number;
+    set offsetY(value: number);
+    get offsetZ(): number;
+    set offsetZ(value: number);
+    onReady(): void;
+    onDestroy(): void;
+    private place;
+}

package/dist/components/point-light.js

@@ -0,0 +1,102 @@
+import * as THREE from 'three/webgpu';
+import { Component } from '../component.js';
+/**
+ * A point light in a 3D scene (ADR 0027, `CONTEXT.md` Point Light): it shines
+ * in every direction from the entity's position plus an offset (in the
+ * entity's local frame: it turns and scales with the entity, so a lantern's
+ * offset follows the object it hangs on), reaching
+ * `distance` world units (0 = without limit) and fading with `decay` (2 is
+ * physical). Not the 2D `Light`, which paints a light-map. No shadows. In a
+ * 2D scene it creates nothing; the three light lives under the entity's node
+ * and leaves with it.
+ */
+export class PointLight extends Component {
+    static componentName = 'PointLight';
+    static space = '3d';
+    static displayName = 'Point light (3D)';
+    static params = {
+        color: { label: 'Color', kind: 'color' },
+        intensity: { label: 'Intensity', min: 0, step: 0.5 },
+        distance: { label: 'Distance (0 = unlimited)', min: 0, step: 0.5 },
+        decay: { label: 'Decay', min: 0, step: 0.1 },
+        offsetX: { label: 'x offset' },
+        offsetY: { label: 'y offset' },
+        offsetZ: { label: 'z offset' },
+    };
+    static transient = ['light'];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light = null;
+    _color = 0xffffff;
+    _intensity = 1;
+    _distance = 0;
+    _decay = 2;
+    _offsetX = 0;
+    _offsetY = 0;
+    _offsetZ = 0;
+    get color() {
+        return this._color;
+    }
+    set color(value) {
+        this._color = value;
+        this.light?.color.setHex(value);
+    }
+    get intensity() {
+        return this._intensity;
+    }
+    set intensity(value) {
+        this._intensity = value;
+        if (this.light)
+            this.light.intensity = value;
+    }
+    /** World units the light reaches; 0 reaches without limit. */
+    get distance() {
+        return this._distance;
+    }
+    set distance(value) {
+        this._distance = value;
+        if (this.light)
+            this.light.distance = value;
+    }
+    get decay() {
+        return this._decay;
+    }
+    set decay(value) {
+        this._decay = value;
+        if (this.light)
+            this.light.decay = value;
+    }
+    get offsetX() {
+        return this._offsetX;
+    }
+    set offsetX(value) {
+        this._offsetX = value;
+        this.place();
+    }
+    get offsetY() {
+        return this._offsetY;
+    }
+    set offsetY(value) {
+        this._offsetY = value;
+        this.place();
+    }
+    get offsetZ() {
+        return this._offsetZ;
+    }
+    set offsetZ(value) {
+        this._offsetZ = value;
+        this.place();
+    }
+    onReady() {
+        if (this.game.space !== '3d')
+            return;
+        this.light = new THREE.PointLight(this._color, this._intensity, this._distance, this._decay);
+        this.entity.node.add(this.light);
+        this.place();
+    }
+    onDestroy() {
+        this.light?.removeFromParent();
+    }
+    place() {
+        this.light?.position.set(this._offsetX, this._offsetY, this._offsetZ);
+    }
+}

package/dist/components/rigid-body.d.ts

@@ -0,0 +1,114 @@
+import { Component, type ComponentSpace } from '../component.js';
+import type { Vec3Json } from '../scene-camera-3d.js';
+export type RigidBodyType = 'dynamic' | 'kinematic';
+export declare const RIGID_BODY_TYPES: readonly RigidBodyType[];
+/** A 3D vector as the body's public API reads and writes it. */
+export interface BodyVector {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Makes the entity's `Collider` a body that moves (ADR 0028). A `dynamic` body
+ * is Rapier's: it falls under the scene's gravity, bounces, stacks and rests,
+ * and after every Simulation Step the engine writes the entity's position and
+ * rotation from it. A `kinematic` body is moved by code. It needs a `Collider`
+ * on the same entity (`validate_project` reports a body without one, and at
+ * runtime none is created). `mass` is the collider's mass; `velocity` is the
+ * initial linear velocity. A `kinematic` body is a character: every step the
+ * engine moves it through Rapier's character controller by its
+ * `desiredVelocity` on x and z and its own vertical velocity under gravity,
+ * stopping at walls, climbing steps up to `stepHeight` and slopes up to
+ * `maxSlope`, sticking to the ground within `snapDistance`, and pushing
+ * dynamic bodies it walks into. A param outside its range (`type` unknown,
+ * `mass` under the minimum, a `velocity` that is not three numbers) creates
+ * no body and warns once; `validate_project` reports it as
+ * `invalid-rigid-body-param`. A RigidBody in a 2D scene creates nothing.
+ */
+export declare class RigidBody extends Component {
+    static componentName: string;
+    static space: ComponentSpace;
+    static params: {
+        type: {
+            label: string;
+            options: RigidBodyType[];
+        };
+        mass: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        gravityScale: {
+            label: string;
+            step: number;
+        };
+        linearDamping: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        angularDamping: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        lockRotations: {
+            label: string;
+        };
+        velocity: {
+            label: string;
+            kind: "vector3";
+        };
+        stepHeight: {
+            label: string;
+            min: number;
+            step: number;
+        };
+        maxSlope: {
+            label: string;
+            min: number;
+            max: number;
+            step: number;
+        };
+        snapDistance: {
+            label: string;
+            min: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    type: RigidBodyType;
+    mass: number;
+    gravityScale: number;
+    linearDamping: number;
+    angularDamping: number;
+    lockRotations: boolean;
+    /** The initial linear velocity `[x, y, z]`, applied when the body is created. */
+    velocity: Vec3Json;
+    /** Kinematic only: the tallest step it climbs without jumping. */
+    stepHeight: number;
+    /** Kinematic only: the steepest slope it climbs, in degrees. */
+    maxSlope: number;
+    /** Kinematic only: how far below its feet it still sticks to the ground (walking down steps and slopes). */
+    snapDistance: number;
+    /**
+     * Kinematic only: where it walks, in units per second on the world x and z
+     * axes. A motor sets it; the physics step reads it every Simulation Step and
+     * moves the body through the character controller. It stays until set again.
+     */
+    desiredVelocity: {
+        x: number;
+        z: number;
+    };
+    /** The body's linear velocity now, in units per second; zero before it exists. Assigning sets it. */
+    get linearVelocity(): BodyVector;
+    set linearVelocity(value: BodyVector);
+    /** Launches a kinematic body upward at `speed` (units per second), only while it stands on something; whether it did. */
+    jump(speed: number): boolean;
+    /** Whether the body stands on something; only a kinematic body moved by the character controller can. */
+    get grounded(): boolean;
+    /** Pushes a dynamic body with an instantaneous impulse (mass · velocity change); a no-op on any other body. */
+    applyImpulse(impulse: BodyVector): void;
+    onReady(): void;
+    onDestroy(): void;
+}

package/dist/components/rigid-body.js

@@ -0,0 +1,83 @@
+import { Component } from '../component.js';
+export const RIGID_BODY_TYPES = ['dynamic', 'kinematic'];
+const ZERO = { x: 0, y: 0, z: 0 };
+/**
+ * Makes the entity's `Collider` a body that moves (ADR 0028). A `dynamic` body
+ * is Rapier's: it falls under the scene's gravity, bounces, stacks and rests,
+ * and after every Simulation Step the engine writes the entity's position and
+ * rotation from it. A `kinematic` body is moved by code. It needs a `Collider`
+ * on the same entity (`validate_project` reports a body without one, and at
+ * runtime none is created). `mass` is the collider's mass; `velocity` is the
+ * initial linear velocity. A `kinematic` body is a character: every step the
+ * engine moves it through Rapier's character controller by its
+ * `desiredVelocity` on x and z and its own vertical velocity under gravity,
+ * stopping at walls, climbing steps up to `stepHeight` and slopes up to
+ * `maxSlope`, sticking to the ground within `snapDistance`, and pushing
+ * dynamic bodies it walks into. A param outside its range (`type` unknown,
+ * `mass` under the minimum, a `velocity` that is not three numbers) creates
+ * no body and warns once; `validate_project` reports it as
+ * `invalid-rigid-body-param`. A RigidBody in a 2D scene creates nothing.
+ */
+export class RigidBody extends Component {
+    static componentName = 'RigidBody';
+    static space = '3d';
+    static params = {
+        type: { label: 'Type', options: [...RIGID_BODY_TYPES] },
+        mass: { label: 'Mass', min: 0.001, step: 0.1 },
+        gravityScale: { label: 'Gravity scale', step: 0.1 },
+        linearDamping: { label: 'Linear damping', min: 0, step: 0.1 },
+        angularDamping: { label: 'Angular damping', min: 0, step: 0.1 },
+        lockRotations: { label: 'Lock rotations' },
+        velocity: { label: 'Initial velocity', kind: 'vector3' },
+        stepHeight: { label: 'Step height', min: 0, step: 0.05 },
+        maxSlope: { label: 'Max slope (degrees)', min: 0, max: 89, step: 1 },
+        snapDistance: { label: 'Snap to ground', min: 0, step: 0.05 },
+    };
+    // Live reads and writes of the body, not authorable defaults (they need a Game to answer).
+    static transient = ['linearVelocity', 'desiredVelocity'];
+    type = 'dynamic';
+    mass = 1;
+    gravityScale = 1;
+    linearDamping = 0;
+    angularDamping = 0;
+    lockRotations = false;
+    /** The initial linear velocity `[x, y, z]`, applied when the body is created. */
+    velocity = [0, 0, 0];
+    /** Kinematic only: the tallest step it climbs without jumping. */
+    stepHeight = 0.3;
+    /** Kinematic only: the steepest slope it climbs, in degrees. */
+    maxSlope = 45;
+    /** Kinematic only: how far below its feet it still sticks to the ground (walking down steps and slopes). */
+    snapDistance = 0.2;
+    /**
+     * Kinematic only: where it walks, in units per second on the world x and z
+     * axes. A motor sets it; the physics step reads it every Simulation Step and
+     * moves the body through the character controller. It stays until set again.
+     */
+    desiredVelocity = { x: 0, z: 0 };
+    /** The body's linear velocity now, in units per second; zero before it exists. Assigning sets it. */
+    get linearVelocity() {
+        return this.game.physics.velocityOf(this.entity) ?? { ...ZERO };
+    }
+    set linearVelocity(value) {
+        this.game.physics.setVelocityOf(this.entity, value);
+    }
+    /** Launches a kinematic body upward at `speed` (units per second), only while it stands on something; whether it did. */
+    jump(speed) {
+        return this.game.physics.jumpOf(this.entity, speed);
+    }
+    /** Whether the body stands on something; only a kinematic body moved by the character controller can. */
+    get grounded() {
+        return this.game.physics.groundedOf(this.entity);
+    }
+    /** Pushes a dynamic body with an instantaneous impulse (mass · velocity change); a no-op on any other body. */
+    applyImpulse(impulse) {
+        this.game.physics.applyImpulseTo(this.entity, impulse);
+    }
+    onReady() {
+        this.game.physics.attach(this.entity);
+    }
+    onDestroy() {
+        this.game.physics.detach(this.entity);
+    }
+}

package/dist/components/solid.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import { type CollisionPoint, type CollisionShape } from '../collision-shape.js';
 /**
  * Static collider. Character motors (e.g. PlatformerMotor) collide against
@@ -9,6 +9,7 @@ import { type CollisionPoint, type CollisionShape } from '../collision-shape.js'
  */
 export declare class Solid extends Component {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         offsetX: {
             label: string;

package/dist/components/solid.js

@@ -9,6 +9,7 @@ import { collisionBounds, resolveCollisionPoints, } from '../collision-shape.js'
  */
 export class Solid extends Component {
     static componentName = 'Solid';
+    static space = '2d';
     static params = {
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },

package/dist/components/sprite.d.ts

@@ -1,4 +1,4 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import type { YSortParticipant } from '../render-sort.js';
 export type SpriteShape = 'rectangle' | 'circle';
 /**
@@ -7,6 +7,7 @@ export type SpriteShape = 'rectangle' | 'circle';
  */
 export declare class Sprite extends Component implements YSortParticipant {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         offsetX: {
             label: string;
@@ -32,6 +33,9 @@ export declare class Sprite extends Component implements YSortParticipant {
             max: number;
             step: number;
         };
+        emissive: {
+            label: string;
+        };
     };
     static transient: string[];
     private _width;
@@ -55,6 +59,9 @@ export declare class Sprite extends Component implements YSortParticipant {
     set anchorX(value: number);
     get anchorY(): number;
     set anchorY(value: number);
+    private _emissive;
+    get emissive(): boolean;
+    set emissive(value: boolean);
     /** Optional texture URL; with pixelArt on it filters in nearest. */
     texture?: string;
     pixelArt: boolean;

package/dist/components/sprite.js

@@ -3,6 +3,7 @@ import { Component } from '../component.js';
 import { spritePlacement } from '../sprite-placement.js';
 import { reportRejection } from '../report-rejection.js';
 import { spriteBatchesOf, spriteInstanceOf } from '../sprite-batches.js';
+import { setEmissive, TRANSPARENT_TEXEL_ALPHA } from '../render-layers.js';
 const clampAnchor = (value) => Math.min(1, Math.max(0, value));
 /**
  * Textured or flat-color quad. In the unified pipeline, a 2D sprite is a
@@ -10,12 +11,14 @@ const clampAnchor = (value) => Math.min(1, Math.max(0, value));
  */
 export class Sprite extends Component {
     static componentName = 'Sprite';
+    static space = '2d';
     static params = {
         offsetX: { label: 'x offset' },
         offsetY: { label: 'y offset' },
         anchorX: { label: 'x anchor', min: 0, max: 1, step: 0.25 },
         anchorY: { label: 'y anchor', min: 0, max: 1, step: 0.25 },
         layer: { label: 'layer', min: -5, max: 5, step: 1 },
+        emissive: { label: 'emissive' },
     };
     static transient = ['mesh'];
     // Size, color and offset are reactive so inspector edits update the live quad.
@@ -80,6 +83,17 @@ export class Sprite extends Component {
         this._anchorY = clampAnchor(value);
         this.syncQuad();
     }
+    // Emissive (issue #78 CA-10): never darkened by the light-map, drawn after
+    // it at full brightness. On its own render layer.
+    _emissive = false;
+    get emissive() {
+        return this._emissive;
+    }
+    set emissive(value) {
+        this._emissive = value === true;
+        if (this.mesh)
+            setEmissive(this.mesh, this._emissive);
+    }
     /** Optional texture URL; with pixelArt on it filters in nearest. */
     texture;
     pixelArt = false;
@@ -127,11 +141,12 @@ export class Sprite extends Component {
         if (!this.mesh)
             return;
         this.mesh.position.z = this.layer * 0.01;
+        setEmissive(this.mesh, this._emissive);
         this.syncQuad();
         this.entity.node.add(this.mesh);
     }
     buildMesh() {
-        const material = new THREE.MeshBasicMaterial({ color: this.color, transparent: true });
+        const material = new THREE.MeshBasicMaterial({ color: this.color, transparent: true, alphaTest: TRANSPARENT_TEXEL_ALPHA });
         if (this.texture) {
             // Its own clone of the cached base (game.assets, ADR 0019): filters
             // are per clone, colour space comes with the base, and the image lands

package/dist/components/sun.d.ts

@@ -0,0 +1,46 @@
+import * as THREE from 'three/webgpu';
+import { Component, type ComponentSpace } from '../component.js';
+import type { Vec3Json } from '../scene-camera-3d.js';
+/**
+ * The 3D scene's sunlight (ADR 0027, `CONTEXT.md` Sun): a directional light
+ * that shines along `direction`, in world space — where its entity stands, or
+ * how it is rotated, does not matter. Color is `0xrrggbb`; no shadows. A Sun
+ * in a 2D scene creates nothing. The three light lives in the Game's scene,
+ * moves with its props, and leaves with the entity.
+ */
+export declare class Sun extends Component {
+    static componentName: string;
+    static space: ComponentSpace;
+    static params: {
+        direction: {
+            label: string;
+            kind: "vector3";
+        };
+        color: {
+            label: string;
+            kind: "color";
+        };
+        intensity: {
+            label: string;
+            min: number;
+            step: number;
+        };
+    };
+    static transient: string[];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light: THREE.DirectionalLight | null;
+    private _direction;
+    private _color;
+    private _intensity;
+    /** Where the light travels, as a world-space vector `[x, y, z]`; any length but zero. */
+    get direction(): Vec3Json;
+    set direction(value: Vec3Json);
+    get color(): number;
+    set color(value: number);
+    get intensity(): number;
+    set intensity(value: number);
+    onReady(): void;
+    onDestroy(): void;
+    /** Puts the light on the opposite side of the origin from where it travels, targeting the origin. */
+    private aim;
+}

package/dist/components/sun.js

@@ -0,0 +1,74 @@
+import * as THREE from 'three/webgpu';
+import { Component } from '../component.js';
+const DEFAULT_DIRECTION = [-1, -2, -1];
+/** Scene JSON is untyped at runtime: only an array of three finite numbers, not all zero, aims a light. */
+const finiteDirection = (value) => Array.isArray(value) && value.length === 3 && value.every(Number.isFinite) && value.some((component) => component !== 0);
+/**
+ * The 3D scene's sunlight (ADR 0027, `CONTEXT.md` Sun): a directional light
+ * that shines along `direction`, in world space — where its entity stands, or
+ * how it is rotated, does not matter. Color is `0xrrggbb`; no shadows. A Sun
+ * in a 2D scene creates nothing. The three light lives in the Game's scene,
+ * moves with its props, and leaves with the entity.
+ */
+export class Sun extends Component {
+    static componentName = 'Sun';
+    static space = '3d';
+    static params = {
+        direction: { label: 'Direction', kind: 'vector3' },
+        color: { label: 'Color', kind: 'color' },
+        intensity: { label: 'Intensity', min: 0, step: 0.1 },
+    };
+    static transient = ['light'];
+    /** The three light, null in a 2D scene or before the component is ready. */
+    light = null;
+    _direction = [...DEFAULT_DIRECTION];
+    _color = 0xffffff;
+    _intensity = 1;
+    /** Where the light travels, as a world-space vector `[x, y, z]`; any length but zero. */
+    get direction() {
+        return [...this._direction];
+    }
+    set direction(value) {
+        // A zero or unreadable direction keeps the last good one: there is nothing to aim along.
+        if (!finiteDirection(value))
+            return;
+        this._direction = [...value];
+        this.aim();
+    }
+    get color() {
+        return this._color;
+    }
+    set color(value) {
+        this._color = value;
+        this.light?.color.setHex(value);
+    }
+    get intensity() {
+        return this._intensity;
+    }
+    set intensity(value) {
+        this._intensity = value;
+        if (this.light)
+            this.light.intensity = value;
+    }
+    onReady() {
+        if (this.game.space !== '3d')
+            return;
+        const light = new THREE.DirectionalLight(this._color, this._intensity);
+        this.light = light;
+        // The target joins the scene too, or three never updates its world matrix.
+        this.game.scene.add(light, light.target);
+        this.aim();
+    }
+    onDestroy() {
+        this.light?.removeFromParent();
+        this.light?.target.removeFromParent();
+    }
+    /** Puts the light on the opposite side of the origin from where it travels, targeting the origin. */
+    aim() {
+        if (!this.light)
+            return;
+        const [x, y, z] = this._direction;
+        this.light.position.set(-x, -y, -z).normalize();
+        this.light.target.position.set(0, 0, 0);
+    }
+}

package/dist/components/tilemap.d.ts

@@ -1,10 +1,11 @@
-import { Component } from '../component.js';
+import { Component, type ComponentSpace } from '../component.js';
 import { SOLID_SOURCE_SYMBOL, type SolidSource } from '../scene-solids.js';
 import { type TilemapCell, type TilemapCellBounds } from '../tilemap-grid.js';
 import { Solid } from './solid.js';
 /** One authorable cell map rendered as a single merged geometry. */
 export declare class Tilemap extends Component implements SolidSource {
     static componentName: string;
+    static space: ComponentSpace;
     static params: {
         color: {
             label: string;

package/dist/components/tilemap.js

@@ -6,9 +6,12 @@ import { SOLID_SOURCE_SYMBOL } from '../scene-solids.js';
 import { cellAt as gridCellAt, cellBounds as gridCellBounds, cellIndex as gridCellIndex, } from '../tilemap-grid.js';
 import { Solid } from './solid.js';
 import { reportRejection } from '../report-rejection.js';
+import { markOccludersChanged } from '../scene-lighting.js';
+import { TRANSPARENT_TEXEL_ALPHA } from '../render-layers.js';
 /** One authorable cell map rendered as a single merged geometry. */
 export class Tilemap extends Component {
     static componentName = 'Tilemap';
+    static space = '2d';
     static params = {
         color: { label: 'color' },
         cols: { label: 'tileset columns', min: 1, step: 1 },
@@ -175,6 +178,7 @@ export class Tilemap extends Component {
         this.loadedTexture?.dispose();
         this.loadedTexture = undefined;
         this.derivedSolids = [];
+        markOccludersChanged(this.game.lighting);
     }
     solids() {
         return this.derivedSolids;
@@ -255,6 +259,7 @@ export class Tilemap extends Component {
         return new THREE.MeshBasicMaterial({
             color: this.color,
             transparent: true,
+            alphaTest: TRANSPARENT_TEXEL_ALPHA,
         });
     }
     rebuildGeometry() {
@@ -349,5 +354,7 @@ export class Tilemap extends Component {
             next.push(solid);
         }
         this.derivedSolids = next;
+        // Occlusion is rebuilt from the solid tiles only when they change (inference 9).
+        markOccludersChanged(this.game.lighting);
     }
 }

package/dist/entity-transform.d.ts

@@ -0,0 +1,18 @@
+import type { Entity } from './entity.js';
+/** A scene entity's position: `[x, y]` (z is 0) or `[x, y, z]`. */
+export type PositionJson = [number, number] | [number, number, number];
+/** The transform a scene or prefab entity declares, applied when it spawns. */
+export interface TransformJson {
+    /** `[x, y]` (z = 0) or `[x, y, z]`; in a 3D scene z is a world axis. */
+    position?: PositionJson;
+    /** Euler angles in degrees, order XYZ, applied to the entity's node (3D scenes). */
+    rotation?: [number, number, number];
+    /** Per-axis scale of the entity's node. */
+    scale?: [number, number, number];
+}
+/**
+ * Applies a declared transform to a freshly spawned entity. A two-number
+ * position behaves exactly as it always did (z = 0); `rotation` is converted
+ * from degrees and `scale` replaces the node's unit scale.
+ */
+export declare function applyTransformJson(entity: Entity, json: TransformJson): void;