@zylem/game-lib 0.8.3 → 0.8.4

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

@@ -1438,7 +1438,6 @@ export class GameBridge {
         paused?: boolean;
         debug?: boolean;
     }): void;
-    // (undocumented)
     publishVariable(payload: GameVariablePayload): void;
     queueEntityRemoved(uuids: string[]): void;
     queueEntityUpsert(entities: EntitySummaryPayload[]): void;
@@ -3134,6 +3133,7 @@ export class SimulationBody implements PhysicsRenderPoseProvider {
     linvel(): PhysicsVector3;
     lockRotations(locked: boolean, _wakeUp?: boolean): void;
     lockTranslations(locked: boolean, _wakeUp?: boolean): void;
+    markPoseDiscontinuity(): void;
     // (undocumented)
     mass(): number;
     // Warning: (ae-forgotten-export) The symbol "PhysicsQuaternion" needs to be exported by the entry point public.d.ts
@@ -3240,6 +3240,15 @@ export type SpriteImage = {
     file: string;
 };
 
+// @public
+export type SpriteSheet = {
+    file: string;
+    columns: number;
+    rows: number;
+    frames: Array<string | null>;
+    filter?: 'nearest' | 'linear';
+};
+
 // @public
 export const STAGE_STATE_CHANGE = "STAGE_STATE_CHANGE";
 
@@ -4534,9 +4543,11 @@ export class ZylemSprite extends GameEntity<ZylemSpriteOptions> {
     // (undocumented)
     protected createAnimations(animations: SpriteAnimation[]): void;
     // (undocumented)
+    protected createSpriteFromSheet(sheet: SpriteSheet): void;
+    // (undocumented)
     protected createSpritesFromImages(images: SpriteImage[]): void;
     // (undocumented)
-    protected currentAnimation: any;
+    protected currentAnimation: string | null;
     // (undocumented)
     protected currentAnimationFrame: string;
     // (undocumented)
@@ -4546,9 +4557,14 @@ export class ZylemSprite extends GameEntity<ZylemSpriteOptions> {
     // (undocumented)
     protected currentSpriteIndex: number;
     // (undocumented)
+    protected flippedX: boolean;
+    // (undocumented)
+    isFlippedX(): boolean;
     setAnimation(name: string, delta: number): void;
+    setFlipX(flip: boolean): void;
     // (undocumented)
     setSprite(key: string): void;
+    protected sheetTexture: Texture | null;
     // (undocumented)
     spriteDestroy(params: DestroyContext<ZylemSpriteOptions>): void;
     // (undocumented)
@@ -4629,16 +4645,16 @@ export class ZylemZone extends GameEntity<ZylemZoneOptions> implements Collision
 
 // Warnings were encountered during analysis:
 //
-// dist/entity-BGEq1yfC.d.ts:423:5 - (ae-forgotten-export) The symbol "RenderCategory_2" needs to be exported by the entry point public.d.ts
-// dist/entity-BGEq1yfC.d.ts:424:5 - (ae-forgotten-export) The symbol "RuntimeEntityOptions" needs to be exported by the entry point public.d.ts
-// dist/entity-BGEq1yfC.d.ts:425:5 - (ae-forgotten-export) The symbol "CollisionOptions" needs to be exported by the entry point public.d.ts
-// dist/entity-BGEq1yfC.d.ts:426:5 - (ae-forgotten-export) The symbol "MaterialOptions" needs to be exported by the entry point public.d.ts
-// dist/entity-BGEq1yfC.d.ts:434:9 - (ae-forgotten-export) The symbol "IBuilder" needs to be exported by the entry point public.d.ts
-// dist/entity-BGEq1yfC.d.ts:434:9 - (ae-forgotten-export) The symbol "EntityMeshBuilder" needs to be exported by the entry point public.d.ts
-// dist/entity-BGEq1yfC.d.ts:435:9 - (ae-forgotten-export) The symbol "EntityCollisionBuilder" needs to be exported by the entry point public.d.ts
-// dist/entity-BGEq1yfC.d.ts:436:9 - (ae-forgotten-export) The symbol "MaterialBuilder" needs to be exported by the entry point public.d.ts
-// dist/game-NHkubIfI.d.ts:951:5 - (ae-forgotten-export) The symbol "StageAssetLoaderConfig" needs to be exported by the entry point public.d.ts
-// dist/game-NHkubIfI.d.ts:1563:5 - (ae-forgotten-export) The symbol "StageInterface" needs to be exported by the entry point public.d.ts
+// dist/entity-BI7cSlK8.d.ts:423:5 - (ae-forgotten-export) The symbol "RenderCategory_2" needs to be exported by the entry point public.d.ts
+// dist/entity-BI7cSlK8.d.ts:424:5 - (ae-forgotten-export) The symbol "RuntimeEntityOptions" needs to be exported by the entry point public.d.ts
+// dist/entity-BI7cSlK8.d.ts:425:5 - (ae-forgotten-export) The symbol "CollisionOptions" needs to be exported by the entry point public.d.ts
+// dist/entity-BI7cSlK8.d.ts:426:5 - (ae-forgotten-export) The symbol "MaterialOptions" needs to be exported by the entry point public.d.ts
+// dist/entity-BI7cSlK8.d.ts:434:9 - (ae-forgotten-export) The symbol "IBuilder" needs to be exported by the entry point public.d.ts
+// dist/entity-BI7cSlK8.d.ts:434:9 - (ae-forgotten-export) The symbol "EntityMeshBuilder" needs to be exported by the entry point public.d.ts
+// dist/entity-BI7cSlK8.d.ts:435:9 - (ae-forgotten-export) The symbol "EntityCollisionBuilder" needs to be exported by the entry point public.d.ts
+// dist/entity-BI7cSlK8.d.ts:436:9 - (ae-forgotten-export) The symbol "MaterialBuilder" needs to be exported by the entry point public.d.ts
+// dist/game-4fsy55uN.d.ts:951:5 - (ae-forgotten-export) The symbol "StageAssetLoaderConfig" needs to be exported by the entry point public.d.ts
+// dist/game-4fsy55uN.d.ts:1563:5 - (ae-forgotten-export) The symbol "StageInterface" needs to be exported by the entry point public.d.ts
 
 // (No @packageDocumentation comment for this package)
 

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

@@ -2055,6 +2055,12 @@ export { EntitySummaryPayload }
 /**
  * Generates and caches entity thumbnail previews for the editor entity list.
  * Renders a cloned Object3D into an offscreen RenderTarget on the shared WebGPU renderer.
+ *
+ * A rendered URL leaves this cache the moment it is read, and the editor holds
+ * it for as long as the entity is listed. Dropping an entry here therefore
+ * must not revoke its blob URL — the consumer owns that lifetime and releases
+ * it when the thumbnail is replaced, the entity is removed, or the stage
+ * changes.
  */
 export declare class EntityThumbnailCache {
     private cache;
@@ -2542,6 +2548,12 @@ export declare class GameBridge {
      * Run a callback when an editor first subscribes to entity data, so the
      * game can backfill state produced while nothing was listening.
      *
+     * An editor takes out both entity subscriptions as it mounts, and each is
+     * a first-subscriber transition. Backfilling on both would republish the
+     * config, the whole stage snapshot, and every thumbnail twice per mount,
+     * so a signal is ignored while the other entity type still has a
+     * listener — that is the same editor finishing its setup, not a new one.
+     *
      * @returns An unsubscribe function.
      */
     onEditorAttached(callback: () => void): () => void;
@@ -2551,6 +2563,14 @@ export declare class GameBridge {
         paused?: boolean;
         debug?: boolean;
     }): void;
+    /**
+     * Publish a global's new value.
+     *
+     * Sent rather than queued: a queued payload is merged into the pending one
+     * for its type, and since each message names a single `path`, two globals
+     * changing in the same frame would collapse into one and the first
+     * variable's update would never reach the editor.
+     */
     publishVariable(payload: GameVariablePayload): void;
     /** Surface a diagnostic message in the editor console. */
     publishNotice(level: GameNoticePayload['level'], message: string): void;
@@ -5338,8 +5358,16 @@ export declare class SimulationBody implements PhysicsRenderPoseProvider {
      */
     private interpolationValidAfterStep;
     constructor(simulation: Simulation, handle: EntityHandle, clock: SimulationStepClock);
-    /** Suppress interpolation until the render buffers catch up. */
-    private markPoseDiscontinuity;
+    /**
+     * Suppress interpolation until the render buffers catch up.
+     *
+     * Called automatically by the pose setters below. Wasm-side behaviors that
+     * teleport a body during a step (e.g. `screen_wrap`) bypass those setters,
+     * so their host systems must call this after the step and before render
+     * poses are synced — otherwise the render buffers straddle the teleport and
+     * the body is drawn sweeping between the two poses.
+     */
+    markPoseDiscontinuity(): void;
     private isInterpolationStale;
     translation(): PhysicsVector3;
     rotation(): PhysicsQuaternion;
@@ -5497,6 +5525,21 @@ export declare type SpriteImage = {
 
 declare type SpriteOptions = BaseNode | Partial<ZylemSpriteOptions>;
 
+/**
+ * A single texture divided into a uniform grid of frames, addressed by UV
+ * offset. Prefer this over {@link SpriteImage} lists for character sheets: one
+ * texture and one draw call instead of one per frame.
+ */
+export declare type SpriteSheet = {
+    file: string;
+    columns: number;
+    rows: number;
+    /** Frame names in row-major order. `null` marks an unused cell. */
+    frames: Array<string | null>;
+    /** Texture filtering. Defaults to `nearest`, which keeps pixel art crisp. */
+    filter?: 'nearest' | 'linear';
+};
+
 declare class Stage {
     wrappedStage: ZylemStage | null;
     options: StageOptionItem[];
@@ -8255,15 +8298,34 @@ export declare class ZylemSprite extends GameEntity<ZylemSpriteOptions> {
     protected spriteMap: Map<string, number>;
     protected currentSpriteIndex: number;
     protected animations: Map<string, any>;
-    protected currentAnimation: any;
+    protected currentAnimation: string | null;
     protected currentAnimationFrame: string;
     protected currentAnimationIndex: number;
     protected currentAnimationTime: number;
+    /** Set only in sheet mode; the shared texture whose UV window we shift. */
+    protected sheetTexture: Texture | null;
+    protected flippedX: boolean;
     constructor(options?: ZylemSpriteOptions);
     create(): this;
     protected createSpritesFromImages(images: SpriteImage[]): void;
+    protected createSpriteFromSheet(sheet: SpriteSheet): void;
     protected createAnimations(animations: SpriteAnimation[]): void;
     setSprite(key: string): void;
+    /**
+     * Mirror the sprite horizontally, for characters whose sheet only contains
+     * one facing direction.
+     *
+     * In sheet mode this flips the UV window rather than the sprite scale,
+     * because {@link syncSpriteMaterials} rewrites scale from `options.size`
+     * every frame and would immediately undo a negative scale.
+     */
+    setFlipX(flip: boolean): void;
+    isFlippedX(): boolean;
+    private applySheetFrame;
+    /**
+     * Advance a named clip. Call once per frame from an update loop; `delta` is
+     * seconds, so scaling it scales playback rate.
+     */
     setAnimation(name: string, delta: number): void;
     private getCurrentRotationQuaternion;
     private syncSpriteMaterials;
@@ -8275,6 +8337,7 @@ export declare class ZylemSprite extends GameEntity<ZylemSpriteOptions> {
 
 declare type ZylemSpriteOptions = GameEntityOptions & {
     images?: SpriteImage[];
+    sheet?: SpriteSheet;
     animations?: SpriteAnimation[];
     size?: Vec3Input;
     collisionSize?: Vec3Input;