@zylem/game-lib 0.9.5 → 0.9.7

package/dist/{stage-PBmwT5-Y.d.ts → stage-CCGJh9TD.d.ts}

@@ -1,17 +1,20 @@
 import { B as BaseNode } from './base-node-idopiSw5.js';
 import { h as SetupFunction, g as UpdateFunction, j as DestroyFunction, a as SetupContext, U as UpdateContext, D as DestroyContext, L as LoadingEvent } from './base-node-life-cycle-BK9xebT9.js';
-import { Scene, Color, Object3D, Vector3, BufferGeometry, Material, Group, Texture } from 'three';
-import { al as ZylemWorld, aj as EntityTypeMap } from './entity-type-map-CrsrKT8c.js';
+import { Box3, Scene, Color, Object3D, Vector3, BufferGeometry, Material, Group, Texture, Camera } from 'three';
+import { an as ZylemWorld, al as EntityTypeMap } from './entity-type-map-BMaPY8cd.js';
 import { E as Entity, L as LifecycleFunction, S as StageEntity } from './entity-BIf_a4dl.js';
-import { G as GameEntity, a as GameEntityOptions } from './entity-XqvuWgPm.js';
-import { l as ZylemCamera, R as RendererManager, e as CameraPerspective, d as CameraContext, C as CameraPose, P as PerspectiveType, f as CameraBehavior, g as CameraAction, h as CameraPipelineState, V as Viewport, Z as ZylemPostEffect } from './zylem-camera-CWhIGXlW.js';
-import { d as ZylemShader } from './material-CxxAyJYp.js';
+import { G as GameEntity, d as GameEntityOptions, b as PointerTargetEntity } from './entity-CY75JJSw.js';
+import { l as ZylemCamera, R as RendererManager, e as CameraPerspective, d as CameraContext, C as CameraPose, P as PerspectiveType, f as CameraBehavior, g as CameraAction, h as CameraPipelineState, V as Viewport, Z as ZylemPostEffect } from './zylem-camera-BA3VPFlS.js';
+import { f as ZylemShader } from './material-D1IVeQc5.js';
 import { a as SimulationBody } from './simulation-body-zQw-emOr.js';
 import { e as Vec3Input, b as Vec2Input, d as Vec3Components } from './vector-D3eDzvcA.js';
 import { StageEvents } from './events.js';
 import { G as GameInputConfig } from './game-interfaces-vF5sRi1n.js';
+import { A as ArmPlacementOptions, P as PlacementSession } from './placement-session-BNQoL7Jb.js';
 import { SwatchApplyResult, SceneOperationEntry, EntityApplySwatchPayload, SceneOperationPayload } from '@zylem/bridge';
+import { a as LevelSyncPayload, L as LevelDocument } from './level-types-D10LiOcn.js';
 import { BehaviorSystem, BehaviorEntityLink, BehaviorRuntime, BehaviorSystemFactory, BehaviorRef } from '@zylem/behaviors/core';
+import { d as GizmoRay } from './transform-gizmo-DappLQ9w.js';
 
 /**
  * Editor-view cameras exist only while an editor is attached.
@@ -24,6 +27,8 @@ interface EditorCameraHost {
     ensureEditorCameras(): Promise<void>;
     destroyEditorCameras(): void;
     activateCameraById(id: string): boolean;
+    /** Copy the gameplay camera onto the free view, then show it. */
+    syncFreeCameraToGame(): void;
 }
 
 /**
@@ -47,6 +52,10 @@ declare class CameraManager implements EditorCameraHost {
     private _lockedEditorIds;
     /** Which editor views pan in screen space (the view plane). */
     private _screenSpacePanIds;
+    /** Side, top, and isometric views that have already been placed on the gameplay camera. */
+    private _framedEditorViews;
+    /** World boxes of stage entities, read when an orthographic view is first shown. */
+    private _entityBounds;
     /** Game camera to restore when the editor releases the main view. */
     private _rememberedGameCamera;
     /**
@@ -76,8 +85,20 @@ declare class CameraManager implements EditorCameraHost {
     get primaryCamera(): ZylemCamera | null;
     /** True while side, top, isometric, or free is the main view. */
     isEditorViewActive(): boolean;
+    /** Id of the editor view that is currently the main camera, if one is. */
+    activeEditorCameraId(): string | null;
     /** True after the four editor views have been created. */
     hasEditorCameras(): boolean;
+    /**
+     * World boxes used the first time side, top, or isometric is shown.
+     * Pass null to stop contributing boxes.
+     */
+    setEditorEntityBounds(read: (() => readonly Box3[]) | null): void;
+    /**
+     * Copy the gameplay camera onto the free view, then show that view.
+     * Waits for the editor cameras when they have not been created yet.
+     */
+    syncFreeCameraToGame(): void;
     /**
      * Get all registered cameras.
      */
@@ -165,6 +186,15 @@ declare class CameraManager implements EditorCameraHost {
     private showGameCamera;
     /** Enable orbit on the active editor view only. Inactive views keep their pose. */
     private syncEditorOrbit;
+    private isOrthographicEditorView;
+    /** Snapshot the gameplay camera onto the free orbit camera. Does not switch views. */
+    private copyFreeFromGame;
+    private copyGameplayProjection;
+    /**
+     * Place an orthographic view on the gameplay camera's look-at and fit the
+     * stage around that point. Returns false when there is no gameplay camera.
+     */
+    private frameOrthographicView;
     /** Stop game-camera orbit controls from sharing the canvas with an editor view. */
     private suspendOtherOrbits;
     private restoreOrbitFor;
@@ -914,8 +944,9 @@ interface SwatchApplyOutcome {
  * `PlacementGhost` — is live whenever a tool is armed, so the toolbar's buttons
  * work on their own. The debug layer — the wasm simulation's collider
  * wireframes — is the part `debugState.enabled` gates, and is torn down when
- * it goes off while the delegate stays alive to re-activate. Debug mode does
- * not switch cameras; picking and gizmos use whichever camera is rendering.
+ * it goes off while the delegate stays alive to re-activate. This delegate
+ * does not switch cameras; the bridge shows the free camera when debug is
+ * enabled. Picking and gizmos use whichever camera is rendering.
  *
  * Centralizes all of this so `ZylemStage` doesn't have to know about
  * raycasting, DOM input, or debug rendering.
@@ -958,6 +989,9 @@ declare class StageDebugDelegate {
     private selectionBoundsPool;
     private hoverBounds;
     private grid;
+    private levelSession;
+    /** The press belongs to the level session, through pointerup. */
+    private levelPointer;
     private lastTool;
     /** Element the current gizmo drag captured, so pointerup is never missed. */
     private capturedPointer;
@@ -967,6 +1001,13 @@ declare class StageDebugDelegate {
      * point. Without one the tool warns instead of silently doing nothing.
      */
     setAddEntityFactory(factory: AddEntityFactory | null): void;
+    /** Show the level document as an edit preview. Brush faces, no collision. */
+    syncLevel(payload: LevelSyncPayload): void;
+    /** Respawn the document for play: hull collision, hidden brush faces, live zones. */
+    playLevel(document: LevelDocument): void;
+    /** Remove the preview and any play collision. Stage entities stay. */
+    closeLevel(): void;
+    private levelSessionHost;
     /** Camera used for raycasts and gizmos: whichever one is rendering. */
     private getDebugViewCamera;
     private resolveEntity;
@@ -1072,6 +1113,8 @@ declare class StageDebugDelegate {
      * physics raycast here and cannot preview itself.
      */
     private updatePlacementGhost;
+    /** Selection boxes for the first side, top, and isometric placement. Level brushes are not included. */
+    private editorEntityBoxes;
     /** Full teardown — unsubscribes from debugState and cleans up all resources. */
     dispose(): void;
     /**
@@ -1477,6 +1520,113 @@ declare class StageEntityDelegate {
     private unregisterBehaviorLinks;
 }
 
+/**
+ * Geometry for the add tool's placement click.
+ *
+ * Split out from `StageDebugDelegate` because it is pure: rays and bounds in,
+ * a position out, with no scene, world, or entity state involved. Placement is
+ * also the part most worth pinning down — the fallback plane and the surface
+ * offset are what make a click into empty space land somewhere sensible.
+ */
+
+/** A ray/collider intersection, as reported by the physics world. */
+interface PlacementHit {
+    distance: number;
+    normal: [number, number, number];
+}
+
+/**
+ * Play-mode pointer: hover areas, droppable areas, and click-to-place.
+ *
+ * The editor's Add tool owns the canvas while `isEditorInteractionActive()`
+ * is true. This delegate stays out of that — an armed session is hidden and
+ * not cancelled, and its listeners come off so the gizmo and the add ghost
+ * keep the pointer. Left click is swallowed only when a placement commits or
+ * a hover area handles the click, so an empty press still reaches the camera.
+ */
+
+interface StagePointerHost {
+    getScene(): Scene | null;
+    raycast(origin: Vector3, direction: Vector3, maxDistance: number): PlacementHit | null;
+    addSpawn(entity: unknown): void;
+    getCanvas(): HTMLElement | null;
+    getCamera(): Camera | null;
+    /** The durable stage should drop its saved session. Not called while repeating. */
+    onSessionEnded?: () => void;
+}
+declare class StagePointerDelegate {
+    private readonly host;
+    private readonly unsubscribe;
+    private readonly known;
+    private readonly targets;
+    private readonly bounds;
+    private readonly raycaster;
+    private readonly mouseNdc;
+    private session;
+    private view;
+    private closing;
+    private disposed;
+    private hovered;
+    private hoveredId;
+    private lastAim;
+    /** Test and host injection. When set, the camera ray is not used. */
+    private rayOverride;
+    private canvas;
+    private listening;
+    private keys;
+    constructor(host: StagePointerHost);
+    /** True while a click would still try to place. False during the fade-out. */
+    get isPlacing(): boolean;
+    get previewOpacity(): number;
+    get previewPosition(): Vector3 | null;
+    /**
+     * Use this ray instead of the camera. Tests inject one; a live stage leaves
+     * it null and rebuilds the ray from the canvas every frame so a moving
+     * camera does not leave the preview behind.
+     */
+    setRay(ray: GizmoRay | null): void;
+    /** Register a target that is not going through the stage entity list. */
+    registerTarget(entity: PointerTargetEntity): void;
+    unregisterTarget(uuid: string): void;
+    arm(options: ArmPlacementOptions): void;
+    setPayload(payload: unknown): void;
+    setRepresentative(representative: ArmPlacementOptions['representative']): void;
+    cancel(): void;
+    update(delta: number): void;
+    /**
+     * @returns whether the press was handled. Unhandled presses are left for
+     * the camera.
+     */
+    pointerDown(button: number): boolean;
+    dispose(): void;
+    private suspended;
+    private mountView;
+    private syncTarget;
+    private resolveAim;
+    private nearestArea;
+    private hasDroppable;
+    private surfacePoint;
+    private present;
+    private applyHover;
+    private leaveHovered;
+    private fire;
+    private areaContext;
+    private tryCommit;
+    private pointContext;
+    private notifyDrop;
+    private finishCommit;
+    private beginClose;
+    private clickHovered;
+    private currentRay;
+    private syncListeners;
+    private detachListeners;
+    private detachPointer;
+    private onPointerMove;
+    private onPointerDown;
+    private onKeyDown;
+    private trackPointer;
+}
+
 /**
  * The runtime heart of a loaded stage.
  *
@@ -1536,6 +1686,8 @@ declare class ZylemStage extends LifeCycleBase<ZylemStage> {
     scene: ZylemScene | null;
     renderStrategy: RenderStrategyManager | null;
     debugDelegate: StageDebugDelegate | null;
+    /** Play-mode hover, drop, and click-to-place. Suspended while the editor tools are live. */
+    readonly pointerDelegate: StagePointerDelegate;
     uuid: string;
     wrapperRef: Stage | null;
     camera?: CameraWrapper;
@@ -1646,6 +1798,9 @@ declare class Stage {
     private eventDelegate;
     /** Per-stage input configuration overrides. Merged with game-level defaults on stage load. */
     inputConfig: GameInputConfig | null;
+    /** Placement armed before the runtime stage exists, applied on load. */
+    private pendingPlacement;
+    private placementGeneration;
     /**
      * Callback set by the game to trigger input reconfiguration
      * when this stage's input config changes at runtime.
@@ -1679,6 +1834,33 @@ declare class Stage {
      * @example stage.getEntityByName('scoreText', TEXT_TYPE)
      */
     getEntityByName<T extends symbol | void = void>(name: string, type?: T): T extends keyof EntityTypeMap ? EntityTypeMap[T] | undefined : BaseNode | undefined;
+    /**
+     * Follow the cursor with a representative and place an entity on left click.
+     *
+     * Click-to-place, not a drag. A hover area's `onClick` can call this to
+     * pick something up. While the stage has any droppable, the click only
+     * commits over one that accepts `payload`. Otherwise it lands on the
+     * physics hit, or the ground plane. Right click, Escape, and
+     * {@link cancelPlacement} fade the preview out.
+     *
+     * @example
+     * stage.armPlacement({
+     *   payload: 'tower',
+     *   repeat: true,
+     *   representative: entityRepresentative(createBox, { opacity: 0.45 }),
+     *   spawnOnClick: ({ valid, position }) => valid ? createBox({ position }) : false,
+     * });
+     */
+    armPlacement(options: ArmPlacementOptions): PlacementSession;
+    /** Fade out the armed representative and ignore further placement clicks. */
+    cancelPlacement(): this;
+    /**
+     * Drop the session the next load would re-arm.
+     * The pointer delegate calls this after a cancel or a one-shot commit.
+     * It does not touch the live preview — {@link cancelPlacement} does both.
+     * @internal
+     */
+    abandonPlacement(): void;
     /**
      * Add a camera to this stage.
      * @param camera The ZylemCamera or CameraWrapper to add

package/dist/transform-gizmo-DappLQ9w.d.ts

@@ -0,0 +1,123 @@
+import * as three from 'three';
+import { Vector3, Group, Scene, Camera } from 'three';
+
+type GizmoMode = 'translate' | 'rotate' | 'scale';
+/** Single-axis, planar, and uniform handle identifiers. */
+type GizmoAxis = 'x' | 'y' | 'z' | 'xy' | 'yz' | 'xz' | 'xyz';
+/** A raw, unsnapped drag result in world space. */
+type GizmoDelta = {
+    kind: 'translate';
+    offset: Vector3;
+} | {
+    kind: 'rotate';
+    axis: Vector3;
+    angle: number;
+} | {
+    kind: 'scale';
+    factor: Vector3;
+};
+/** A mouse ray in world space. */
+interface GizmoRay {
+    origin: Vector3;
+    direction: Vector3;
+}
+/**
+ * Closest point along an infinite line to a ray, as a distance along the line.
+ *
+ * Returns `null` when the ray is close enough to parallel with the line that the
+ * closest point becomes unstable; see {@link MAX_DRAG_GAIN}.
+ */
+declare function closestAxisValue(ray: GizmoRay, origin: Vector3, axis: Vector3): number | null;
+/**
+ * Intersect a ray with the plane through `origin` with the given normal.
+ *
+ * Returns `null` for a plane seen too close to edge-on, where the hit point
+ * races away across the plane for very little pointer motion.
+ */
+declare function intersectPlane(ray: GizmoRay, origin: Vector3, normal: Vector3, target: Vector3): Vector3 | null;
+declare class TransformGizmo {
+    /** Root added to the scene; carries the pivot transform. */
+    readonly root: Group<three.Object3DEventMap>;
+    private scene;
+    private modeGroups;
+    private handles;
+    private materials;
+    private geometries;
+    private mode;
+    private highlighted;
+    private drag;
+    private raycaster;
+    constructor();
+    addTo(scene: Scene): void;
+    removeFromScene(): void;
+    dispose(): void;
+    setMode(mode: GizmoMode): void;
+    getMode(): GizmoMode;
+    /** Place the gizmo at a pivot and show it. */
+    show(pivot: Vector3): void;
+    hide(): void;
+    get visible(): boolean;
+    get pivot(): Vector3;
+    /**
+     * Keep the gizmo a constant size on screen.
+     *
+     * A world-sized gizmo is unusable in an orbit view: it fills the screen up
+     * close and disappears from a distance.
+     */
+    update(camera: Camera): void;
+    /**
+     * Which handle a ray hits, or `null`.
+     *
+     * Raycasts the gizmo's own meshes rather than the physics world. Handles are
+     * render-only objects with no colliders, so the physics raycast used to pick
+     * entities cannot see them at all.
+     */
+    pick(ray: GizmoRay): GizmoAxis | null;
+    /**
+     * Whether a handle can be dragged from the current viewing angle.
+     *
+     * Each handle type degenerates differently: an arrow aimed at the camera has
+     * no screen-space direction left to follow, while a plane quad or rotation
+     * ring seen edge-on turns a pixel of motion into a huge sweep across it.
+     */
+    private isHandleDraggable;
+    /** Tint a handle to show it is hovered or being dragged. */
+    setHighlight(axis: GizmoAxis | null): void;
+    /**
+     * Begin a drag on a handle.
+     *
+     * @returns `false` when the gesture cannot be tracked (a near-parallel view
+     * of the drag axis), so the caller can ignore the press rather than start a
+     * drag that would jump.
+     */
+    beginDrag(axis: GizmoAxis, ray: GizmoRay, camera: Camera): boolean;
+    /** Raw delta for the current pointer position, or `null` when unusable. */
+    updateDrag(ray: GizmoRay, camera: Camera): GizmoDelta | null;
+    endDrag(): void;
+    get isDragging(): boolean;
+    get draggingAxis(): GizmoAxis | null;
+    private isPlaneAxis;
+    /** Signed angle of the ray's hit point around `normal`, in radians. */
+    private angleOnPlane;
+    /** Distance from pivot to the ray hit on the camera-facing plane. */
+    private cameraPlaneRadius;
+    private applyModeVisibility;
+    private makeMaterial;
+    private track;
+    /**
+     * An invisible, generously sized mesh used only for hit testing.
+     *
+     * The visible shafts and rings are a couple of pixels wide, which is
+     * miserable to click. The raycaster still reaches `visible: false` meshes,
+     * so picking accuracy is decoupled from how thin the handle looks.
+     */
+    private makePicker;
+    private orientAlongAxis;
+    private buildTranslate;
+    private positionPlaneHandle;
+    private buildRotate;
+    private orientRing;
+    private buildScale;
+}
+
+export { type GizmoAxis as G, TransformGizmo as T, type GizmoDelta as a, type GizmoMode as b, closestAxisValue as c, type GizmoRay as d, intersectPlane as i };

package/dist/web-components.d.ts

@@ -1,17 +1,17 @@
-import { G as Game, D as DeviceProfile } from './game-DBt7iVu4.js';
-import { v as DebugTools } from './debug-state-Cg3f5FB6.js';
+import { G as Game, D as DeviceProfile } from './game-CmkhPP-9.js';
+import { v as DebugTools } from './debug-state-BgX5Q0Ff.js';
 import './base-node-life-cycle-BK9xebT9.js';
 import 'three';
 import './stage-transition-CmGpV4tc.js';
 import './game-interfaces-vF5sRi1n.js';
 import './base-node-idopiSw5.js';
-import './stage-PBmwT5-Y.js';
-import './entity-type-map-CrsrKT8c.js';
-import './entity-XqvuWgPm.js';
+import './stage-CCGJh9TD.js';
+import './entity-type-map-BMaPY8cd.js';
+import './entity-CY75JJSw.js';
 import '@zylem/behaviors/core';
 import './simulation-body-zQw-emOr.js';
 import './vector-D3eDzvcA.js';
-import './material-CxxAyJYp.js';
+import './material-D1IVeQc5.js';
 import 'three/webgpu';
 import './collision-builder-BckxkdmA.js';
 import './events.js';
@@ -20,8 +20,11 @@ import './selection-bounds-BKmSo9aG.js';
 import './entity-BIf_a4dl.js';
 import '@zylem/behaviors/particle-emitter';
 import 'three/addons/lines/webgpu/Line2.js';
-import './zylem-camera-CWhIGXlW.js';
+import './zylem-camera-BA3VPFlS.js';
+import './placement-session-BNQoL7Jb.js';
 import '@zylem/bridge';
+import './level-types-D10LiOcn.js';
+import './transform-gizmo-DappLQ9w.js';
 import './default-controls-CAKJ5zlo.js';
 
 /**

package/dist/web-components.js

@@ -1 +1 @@
-import{a}from"./chunk-4CZZZCFB.js";import"./chunk-GPCSX3M6.js";import"./chunk-WOT6VMZA.js";export{a as ZylemGameElement};
+import{a}from"./chunk-JCGW5PIR.js";import"./chunk-UM5VNQPY.js";import"./chunk-WOT6VMZA.js";export{a as ZylemGameElement};

package/dist/{zylem-camera-CWhIGXlW.d.ts → zylem-camera-BA3VPFlS.d.ts}

@@ -514,6 +514,8 @@ declare class ZylemCamera {
      * to ignore pointer input while another camera is showing.
      */
     armEditorOrbit(lockRotation: boolean, screenSpacePan?: boolean): void;
+    /** Let this camera orbit below the horizon. Set before controls are created. */
+    allowFullOrbit(): void;
     /** Ignore pointer input without disposing orbit controls or their pose. */
     disarmEditorOrbit(): void;
     /**
@@ -566,6 +568,13 @@ declare class ZylemCamera {
      * Seed the debug orbit camera to an initial pose.
      */
     seedDebugOrbitPose(position: Vector3, lookAt: Vector3): void;
+    /** Write an orbit pose even when one was already seeded. */
+    replaceOrbitPose(position: Vector3, lookAt: Vector3): void;
+    /**
+     * Resize an orthographic editor view. `frustumSize` is the visible height;
+     * width follows the screen aspect, matching {@link resize}.
+     */
+    applyOrthographicFrame(frustumSize: number, near: number, far: number): void;
     /** Whether the debug orbit camera has received its initial pose. */
     isDebugOrbitPoseSeeded(): boolean;
     /**