@zylem/game-lib 0.9.5 → 0.9.6

package/dist/api/game-lib.api.md

@@ -688,6 +688,7 @@ export class CameraManager implements EditorCameraHost {
     activateCameraById(id: string): boolean;
     // Warning: (ae-forgotten-export) The symbol "ZylemCamera" needs to be exported by the entry point public.d.ts
     get activeCameras(): ReadonlyArray<ZylemCamera>;
+    activeEditorCameraId(): string | null;
     addActiveCamera(nameOrRef: string | ZylemCamera): boolean;
     addCamera(camera: ZylemCamera, name?: string): string;
     get allCameras(): ReadonlyArray<ZylemCamera>;
@@ -1582,7 +1583,7 @@ export type DebugEntityResolver = (uuid: string) => GameEntity<any> | null;
 export const debugState: DebugState;
 
 // @public (undocumented)
-export type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'add' | 'none';
+export type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'add' | 'brush' | 'clip' | 'vertex' | 'none';
 
 // @public (undocumented)
 export const DEFAULT_SNAP_SETTINGS: SnapSettings;
@@ -2198,6 +2199,10 @@ export interface GameBridgeHost {
         seek(time: number): void;
         unload(): void;
     };
+    levelClose?(): void;
+    levelPlay?(document: LevelDocument): void;
+    // Warning: (ae-forgotten-export) The symbol "LevelSyncPayload" needs to be exported by the entry point public.d.ts
+    levelSync?(payload: LevelSyncPayload): void;
     pickEntity?(ndc: BridgeNdc): EntitySummaryPayload | null;
     resolveEntity(uuid: string): GameEntity<any> | null;
     setStageVariable?(key: string, value: unknown): void;
@@ -2567,6 +2572,7 @@ export type GameEntityOptions = {
     position?: Vec3Input;
     hideUntilPositioned?: boolean;
     visible?: boolean;
+    editorOwned?: boolean;
     category?: RenderCategory_2;
     runtime?: RuntimeEntityOptions;
     collision?: Partial<CollisionOptions>;
@@ -2830,6 +2836,9 @@ export { GameToEditorMessages }
 
 export { GameVariablePayload }
 
+// @public
+export function getActiveLevelDocument(): LevelDocument | null;
+
 // @public
 export function getActiveSongPlayer(): SongPlayer | null;
 
@@ -3180,6 +3189,24 @@ export function lerpVec3(a: Vec3Def, b: Vec3Def, t: number): Vec3Def;
 
 export { LevelBuffer }
 
+// @public
+export interface LevelDocument {
+    // Warning: (ae-forgotten-export) The symbol "DoodadPlacement" needs to be exported by the entry point public.d.ts
+    //
+    // (undocumented)
+    doodads: DoodadPlacement[];
+    // Warning: (ae-forgotten-export) The symbol "EntityPlacement" needs to be exported by the entry point public.d.ts
+    //
+    // (undocumented)
+    entities: EntityPlacement[];
+    // Warning: (ae-forgotten-export) The symbol "BrushSolid" needs to be exported by the entry point public.d.ts
+    //
+    // (undocumented)
+    solids: BrushSolid[];
+    // (undocumented)
+    version: 2;
+}
+
 // @public
 export interface LevelStage {
     // (undocumented)
@@ -3669,6 +3696,9 @@ export function radiansToDegrees(radians: number): number;
 // @public (undocumented)
 export const RECT_TYPE: unique symbol;
 
+// @public (undocumented)
+export type RectShape = 'rect' | 'ellipse';
+
 export { registerCooldown }
 
 // @public
@@ -6058,7 +6088,7 @@ export class ZylemRect extends GameEntity<ZylemRectOptions> {
     // (undocumented)
     static type: symbol;
     // (undocumented)
-    updateRect(options?: Partial<Pick<ZylemRectOptions, 'width' | 'height' | 'fillColor' | 'strokeColor' | 'strokeWidth' | 'radius'>>): void;
+    updateRect(options?: Partial<Pick<ZylemRectOptions, 'width' | 'height' | 'fillColor' | 'strokeColor' | 'strokeWidth' | 'radius' | 'shape' | 'image'>>): void;
 }
 
 // @public
@@ -6201,15 +6231,15 @@ export class ZylemZone extends GameEntity<ZylemZoneOptions> implements Collision
 
 // Warnings were encountered during analysis:
 //
-// dist/entity-XqvuWgPm.d.ts:332:5 - (ae-forgotten-export) The symbol "RenderCategory_2" needs to be exported by the entry point public.d.ts
-// dist/entity-XqvuWgPm.d.ts:333:5 - (ae-forgotten-export) The symbol "RuntimeEntityOptions" needs to be exported by the entry point public.d.ts
-// dist/entity-XqvuWgPm.d.ts:334:5 - (ae-forgotten-export) The symbol "CollisionOptions" needs to be exported by the entry point public.d.ts
-// dist/entity-XqvuWgPm.d.ts:343:9 - (ae-forgotten-export) The symbol "IBuilder" needs to be exported by the entry point public.d.ts
-// dist/entity-XqvuWgPm.d.ts:343:9 - (ae-forgotten-export) The symbol "EntityMeshBuilder" needs to be exported by the entry point public.d.ts
-// dist/entity-XqvuWgPm.d.ts:344:9 - (ae-forgotten-export) The symbol "EntityCollisionBuilder" needs to be exported by the entry point public.d.ts
-// dist/entity-XqvuWgPm.d.ts:345:9 - (ae-forgotten-export) The symbol "MaterialBuilder" needs to be exported by the entry point public.d.ts
-// dist/game-DBt7iVu4.d.ts:258:5 - (ae-forgotten-export) The symbol "StageInterface" needs to be exported by the entry point public.d.ts
-// dist/stage-PBmwT5-Y.d.ts:1150:5 - (ae-forgotten-export) The symbol "StageAssetLoaderConfig" needs to be exported by the entry point public.d.ts
+// dist/entity-DC0P747T.d.ts:337:5 - (ae-forgotten-export) The symbol "RenderCategory_2" needs to be exported by the entry point public.d.ts
+// dist/entity-DC0P747T.d.ts:338:5 - (ae-forgotten-export) The symbol "RuntimeEntityOptions" needs to be exported by the entry point public.d.ts
+// dist/entity-DC0P747T.d.ts:339:5 - (ae-forgotten-export) The symbol "CollisionOptions" needs to be exported by the entry point public.d.ts
+// dist/entity-DC0P747T.d.ts:348:9 - (ae-forgotten-export) The symbol "IBuilder" needs to be exported by the entry point public.d.ts
+// dist/entity-DC0P747T.d.ts:348:9 - (ae-forgotten-export) The symbol "EntityMeshBuilder" needs to be exported by the entry point public.d.ts
+// dist/entity-DC0P747T.d.ts:349:9 - (ae-forgotten-export) The symbol "EntityCollisionBuilder" needs to be exported by the entry point public.d.ts
+// dist/entity-DC0P747T.d.ts:350:9 - (ae-forgotten-export) The symbol "MaterialBuilder" needs to be exported by the entry point public.d.ts
+// dist/game-mu6OSCrq.d.ts:258:5 - (ae-forgotten-export) The symbol "StageInterface" needs to be exported by the entry point public.d.ts
+// dist/stage-B_KdSEK6.d.ts:1163:5 - (ae-forgotten-export) The symbol "StageAssetLoaderConfig" needs to be exported by the entry point public.d.ts
 
 // (No @packageDocumentation comment for this package)
 

package/dist/api/game-lib.d.ts

@@ -822,6 +822,35 @@ export { BridgeNdc }
 
 export { BridgeVec3 }
 
+declare interface BrushPlane {
+    normal: BrushVec3;
+    /** The solid is `normal · point <= distance`. */
+    distance: number;
+}
+
+/** One convex solid. Planes are world-space half-spaces. */
+declare interface BrushSolid {
+    id: string;
+    planes: BrushPlane[];
+}
+
+/**
+ * Convex brush kernel.
+ *
+ * A brush is the intersection of half-spaces: a point is inside when
+ * `normal · point <= distance` for every plane. The normal points outward.
+ * Planes are world-space, so moving a brush shifts every distance by
+ * `normal · delta`. No Three.js and no physics types.
+ *
+ * Copy of `packages/bridge/src/level/brush.ts`, kept inside this package so
+ * the declaration build does not reach outside `src`.
+ */
+declare interface BrushVec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+
 /** Cuboid collider sized as `size.xyz` (full extents — half-extents are computed). */
 export declare function buildBoxCollider(size: Vec3Input, options?: RuntimeColliderOptions): StageColliderConfig;
 
@@ -1003,6 +1032,8 @@ export 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;
     /**
@@ -2545,7 +2576,7 @@ declare interface DebugState {
 
 export declare const debugState: DebugState;
 
-export declare type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'add' | 'none';
+export declare type DebugTools = 'select' | 'translate' | 'rotate' | 'scale' | 'delete' | 'add' | 'brush' | 'clip' | 'vertex' | 'none';
 
 export declare const DEFAULT_SNAP_SETTINGS: SnapSettings;
 
@@ -2706,6 +2737,14 @@ export declare const DollyPathSchema: _sinclair_typebox.TObject<{
 /** Point along a dolly path at `u` in 0…1 (arc-length parameterised). */
 export declare function dollyPointAt(path: DollyPath, u: number): Vec3Def;
 
+/** A visual placement. Spawned with no collider. */
+declare interface DoodadPlacement {
+    id: string;
+    typeId: string;
+    pose: BridgePose;
+    props: Record<string, unknown>;
+}
+
 export { dot }
 
 /**
@@ -2919,6 +2958,20 @@ export { EntityPickPayload }
 
 export { EntityPickResultPayload }
 
+/**
+ * A gameplay marker.
+ *
+ * `typeId` is `spawn` or `zone`. Spawn props carry `spawnKind`
+ * (`player` | `enemy` | `item`) and `archetype`. Trigger props carry `size`.
+ */
+declare interface EntityPlacement {
+    id: string;
+    typeId: string;
+    name: string;
+    pose: BridgePose;
+    props: Record<string, unknown>;
+}
+
 /**
  * Runtime entity blueprint (open `data` for factory spreading).
  * Prefer {@link EntityJsonSchema} for editor / Monaco JSON Schema.
@@ -3695,6 +3748,12 @@ export declare interface GameBridgeHost {
     };
     /** Describe the live camera (`camera:pose:get`), for capturing framing into a cutscene. */
     cameraPose?(): Omit<CameraPosePayload, 'requestId'> | null;
+    /** Draw the level document as an edit preview (`level:sync`). */
+    levelSync?(payload: LevelSyncPayload): void;
+    /** Spawn collision, doodads, and triggers for play (`level:play`). */
+    levelPlay?(document: LevelDocument): void;
+    /** Remove the level preview (`level:close`). */
+    levelClose?(): void;
 }
 
 /**
@@ -4284,6 +4343,11 @@ export declare type GameEntityOptions = {
     hideUntilPositioned?: boolean;
     /** Explicit render visibility. When false, entity stays hidden until {@link GameEntity.reveal}. */
     visible?: boolean;
+    /**
+     * Level-mode object. Stays out of the entity list so the live stage cannot
+     * be written back over the level document.
+     */
+    editorOwned?: boolean;
     /** Render path: `environment` (bundle), `pack` (instanced), or `none` (default). */
     category?: RenderCategory_2;
     runtime?: RuntimeEntityOptions;
@@ -4535,6 +4599,18 @@ export { GameToEditorMessages }
 
 export { GameVariablePayload }
 
+/**
+ * The stage's picture of the level document.
+ *
+ * The editor owns the file. This session draws it, reports finished gestures,
+ * and on play swaps the brush faces for one static body of convex hulls.
+ * Nothing it creates is a normal stage entity except play-mode trigger zones,
+ * and those are marked editor-owned so they are not published back.
+ */
+
+/** The document currently previewed or playing, for hosts that spawn from markers. */
+export declare function getActiveLevelDocument(): LevelDocument | null;
+
 /** The most recently created, still-live song player, if any. */
 export declare function getActiveSongPlayer(): SongPlayer | null;
 
@@ -5058,6 +5134,41 @@ export declare function lerpVec3(a: Vec3Def, b: Vec3Def, t: number): Vec3Def;
 
 export { LevelBuffer }
 
+/**
+ * The level file. The editor owns it; the stage only previews and plays it.
+ *
+ * `version` is 2 so a v1 catalog buffer is recognisable and left alone.
+ */
+export declare interface LevelDocument {
+    version: 2;
+    solids: BrushSolid[];
+    doodads: DoodadPlacement[];
+    entities: EntityPlacement[];
+}
+
+/**
+ * Level document shapes shared with the editor over the bridge.
+ *
+ * Defined here, matching `packages/bridge/src/protocol.ts`, because the
+ * installed `@zylem/bridge` build does not export them yet and the
+ * declaration build cannot import files outside this package.
+ */
+
+/** Which list in a level document an edit or a visibility toggle addresses. */
+declare type LevelLayerId = 'solid' | 'doodad' | 'entity';
+
+/** What the Add tool will write into the document on the next click. */
+declare type LevelPlacementArm = {
+    kind: 'doodad';
+    typeId: string;
+    props?: Record<string, unknown>;
+} | {
+    kind: 'spawn';
+} | {
+    kind: 'trigger';
+    size: BridgeVec3;
+};
+
 /**
  * Stream a level buffer into a stage through the catalog.
  *
@@ -5071,6 +5182,15 @@ export declare interface LevelStage {
     spawnEntity(node: BaseNode): Promise<void> | void;
 }
 
+/** Edit-time preview. Hidden layers are omitted; play ignores this and streams everything. */
+declare interface LevelSyncPayload {
+    document: LevelDocument;
+    hiddenLayers: LevelLayerId[];
+    selectedIds: string[];
+    activeLayer: LevelLayerId;
+    placement: LevelPlacementArm | null;
+}
+
 /**
  * Provides BaseNode-like lifecycle without ECS/children. Consumers implement
  * the protected hooks and may assign public setup/update/destroy callbacks.
@@ -5961,6 +6081,8 @@ export declare const RECT_TYPE: unique symbol;
 
 declare type RectOptions = BaseNode | Partial<ZylemRectOptions>;
 
+export declare type RectShape = 'rect' | 'ellipse';
+
 export { registerCooldown }
 
 /**
@@ -6658,13 +6780,13 @@ export declare interface ScheduleOptions {
 export declare function scheduleSong(song: SongDefinition, options?: ScheduleOptions): SongSchedule;
 
 /**
- * CooldownIcon -- a WoW-style cooldown icon UI entity.
+ * Viewport placement shared by the camera-attached HUD entities.
  *
- * Renders a square icon with a semi-transparent clockwise sweep overlay
- * that reflects cooldown progress from the CooldownStore. Optionally shows
- * remaining time text in the center.
- *
- * Modeled after ZylemRect's canvas-based viewport-attached sprite pattern.
+ * Text, rects, and cooldown icons all pin a canvas-drawn sprite to a point on
+ * screen by parenting it to the camera and placing it on a plane `zDistance`
+ * in front of the lens. This module holds what they share: the named viewport
+ * anchors, the viewport size layouts resolve against, and the camera-local
+ * transform for a box of a given pixel size pinned to a point on screen.
  */
 
 /**
@@ -7693,6 +7815,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;
@@ -7702,6 +7827,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;
@@ -9989,21 +10121,13 @@ declare class ZylemCooldownIcon extends GameEntity<ZylemCooldownIconOptions> {
     private createSprite;
     private redraw;
     private toCssColor;
-    private getResolution;
     private iconSetup;
     private iconUpdate;
-    /**
-     * Resolve screen position to pixels.
-     * Computes the anchor point in pixels, then adds the view-unit offset.
-     */
-    private resolveScreenPosition;
     /**
      * Resolve `iconSize` to screen pixels using the view-unit grid.
      * Viewport height = {@link VIEW_UNITS_HEIGHT} units; width scales with aspect ratio.
      */
     private resolveIconSize;
-    /** Compute the world-space half-extents at a given distance from the camera. */
-    private computeWorldExtents;
     private updateStickyTransform;
     /**
      * Dispose Three.js / DOM resources when the entity is destroyed.
@@ -10627,25 +10751,27 @@ export declare class ZylemRect extends GameEntity<ZylemRectOptions> {
     private _cameraRef;
     private _lastCanvasW;
     private _lastCanvasH;
+    private _image;
+    private _imageSource;
     constructor(options?: ZylemRectOptions);
     private createSprite;
+    /** Starts loading `options.image` when it differs from what is drawn. */
+    private loadImage;
     private redrawRect;
     getWidth(): number;
     getHeight(): number;
     private roundedRectPath;
     private toCssColor;
-    /**
-     * Get the viewport resolution from the renderer DOM element,
-     * falling back to the camera's screenResolution if the renderer
-     * is not available (e.g. when using the new RendererManager path).
-     */
-    private getResolution;
     private rectSetup;
     private rectUpdate;
+    /** Where the rect's anchor goes on screen, in pixels from the top-left. */
+    private screenPoint;
+    /** Point of the rect placed on its screen position, as 0..1 fractions of its box. */
+    private pivot;
     private updateStickyTransform;
     private worldToScreen;
     private computeScreenBoundsFromOptions;
-    updateRect(options?: Partial<Pick<ZylemRectOptions, 'width' | 'height' | 'fillColor' | 'strokeColor' | 'strokeWidth' | 'radius'>>): void;
+    updateRect(options?: Partial<Pick<ZylemRectOptions, 'width' | 'height' | 'fillColor' | 'strokeColor' | 'strokeWidth' | 'radius' | 'shape' | 'image'>>): void;
     buildInfo(): Record<string, any>;
 }
 
@@ -10657,9 +10783,23 @@ declare type ZylemRectOptions = GameEntityOptions & {
     strokeWidth?: number;
     radius?: number;
     padding?: number;
+    /** `ellipse` inscribes an ellipse in the width × height box and ignores `radius`. */
+    shape?: RectShape;
+    /** Image URL drawn over the fill, stretched to the box and clipped to the shape. */
+    image?: string | null;
     stickToViewport?: boolean;
+    /**
+     * Viewport point the rect is positioned from. When set, `screenPosition` is
+     * a pixel offset from it (+x right, +y down) and `anchor` defaults to the
+     * same point, so a `bottom-right` rect sits inside that corner.
+     */
+    screenAnchor?: ScreenAnchor;
     screenPosition?: Vec2Input;
     zDistance?: number;
+    /**
+     * Point of the rect placed on its screen position, 0-100 per axis. Defaults
+     * to the `screenAnchor` point when one is set, otherwise top-left (0,0).
+     */
     anchor?: Vec2Input;
     bounds?: {
         screen?: {
@@ -10993,10 +11133,8 @@ export declare class ZylemText extends GameEntity<ZylemTextOptions> {
     private toCssColor;
     private textSetup;
     private textUpdate;
-    private getResolution;
-    private getScreenPixels;
-    private computeWorldExtents;
-    private updateSpriteScale;
+    /** Where the text's pivot goes on screen, in pixels from the top-left. */
+    private screenPoint;
     private updateWorldSpriteScale;
     private updateStickyTransform;
     updateText(_text: string): void;
@@ -11015,6 +11153,14 @@ declare type ZylemTextOptions = GameEntityOptions & {
     backgroundColor?: Color | string | null;
     padding?: number;
     stickToViewport?: boolean;
+    /**
+     * Viewport point the text is positioned from. When set, `screenPosition` is
+     * a pixel offset from it (+x right, +y down) and the text aligns to the same
+     * point, so `top-right` text ends at that corner. Without it,
+     * `screenPosition` is the text's centre, in pixels or as 0..1 fractions of
+     * the viewport.
+     */
+    screenAnchor?: ScreenAnchor;
     screenPosition?: Vec2Input;
     zDistance?: number;
 };