@umicat/phaser-sdk 1.0.0

package/dist/editor/EditorOverlayScene.d.ts

@@ -0,0 +1,333 @@
+import Phaser from 'phaser';
+/**
+ * Editor overlay — slice 2.
+ *
+ * Runs ABOVE the world/HUD scenes. Its job:
+ *
+ * 1. Render selection rectangle around the currently selected entity
+ * 2. Render world bounds rectangle (visual cue for "edge of the game world")
+ * 3. Capture pointer events:
+ *    - pointerdown on an entity → posts pickEntity to host
+ *    - drag → mutates the entity's x/y in real time (visual only)
+ *    - pointerup → posts dragEnd with before/after to host
+ *
+ * The overlay scene is launched by EditorBridge when entering Edit mode,
+ * stopped on exit. It holds no persistent state of its own — selection +
+ * drag info live in the shared EditorState attached to the Phaser game.
+ */
+export declare const EDITOR_OVERLAY_KEY = "__UmicatEditorOverlay";
+interface EditorOverlayInitData {
+    /** World bounds rect to draw (slice 2 draws but doesn't allow editing). */
+    worldBounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /**
+     * Callback to resolve the entity at a given world point. Provided by the
+     * EditorBridge so the overlay doesn't have to know about the EntityRegistry.
+     * Returns the topmost (highest depth) entity at that point or null.
+     */
+    hitTest: (worldX: number, worldY: number) => Phaser.GameObjects.GameObject | null;
+    /**
+     * FB.9a — return ALL entities at (worldX, worldY), sorted by depth desc.
+     * Used by Alt+click cycle (selecting underlying entities when 2+ overlap).
+     */
+    hitTestAll: (worldX: number, worldY: number) => Phaser.GameObjects.GameObject[];
+    /**
+     * postMessage helpers (so the scene can send pickEntity / dragEnd).
+     *
+     * `prefabId` is set when the picked GameObject was spawned via `spawnPrefab`
+     * (tagged with `entityPrefabId` by the SDK at spawn time). The host uses
+     * it to open the Prefab Inspector instead of the Entity Inspector — see
+     * `EditorSelectionPickedMessage` in protocol.ts.
+     */
+    postPick: (entityId: string | null, modifiers: {
+        shift: boolean;
+        cmdOrCtrl: boolean;
+        alt: boolean;
+    }, prefabId?: string) => void;
+    postDragEnd: (entityId: string, before: {
+        x: number;
+        y: number;
+    }, after: {
+        x: number;
+        y: number;
+    }) => void;
+    /**
+     * Forward an editor keyboard shortcut to the host. Set when the iframe has
+     * focus (which is always after the user clicks the canvas to select);
+     * native Cmd+Z / Backspace otherwise can't reach the host.
+     */
+    postShortcut: (action: 'undo' | 'redo' | 'save' | 'delete') => void;
+    /**
+     * P1 infinite canvas — apply pan/zoom to the world camera. Called from
+     * the overlay scene's wheel + middle-button + space-drag handlers.
+     * Routed through EditorBridge (not called directly here) to keep the
+     * pan/zoom mutation in one place + avoid a circular import between
+     * overlay scene and bridge.
+     */
+    applyPanZoom: (msg: {
+        scrollX?: number;
+        scrollY?: number;
+        zoom?: number;
+        relative?: boolean;
+    }) => void;
+}
+export declare class EditorOverlayScene extends Phaser.Scene {
+    private graphics;
+    private worldBounds?;
+    private hitTest;
+    private hitTestAll;
+    private postPick;
+    private postDragEnd;
+    private postShortcut;
+    private applyPanZoom;
+    private panActive;
+    private spaceHeld;
+    private panStartScreen;
+    private panStartScroll;
+    private wheelHandler?;
+    constructor();
+    init(data: EditorOverlayInitData): void;
+    create(): void;
+    private handleShortcut;
+    /**
+     * Pointer coords mode-aware. World mode uses world coords (camera-relative);
+     * HUD mode transforms pointer through the HUD scene's camera to land in
+     * HUD-intrinsic coords (the coord space widget positions live in).
+     *
+     * Pre-0.2.90 this returned `pointer.x/y` (canvas pixels) for HUD mode
+     * — fine when HUD cam was an identity camera (viewport == canvas,
+     * zoom == 1). But 0.2.89 changed HUD cam to render INSIDE the camera-
+     * viewport rect on the editor canvas with editor-cam zoom, so canvas
+     * pixels no longer equal HUD-intrinsic coords. Hit-test against
+     * widgets (positioned in HUD-intrinsic) would only match a tiny
+     * patch near the canvas top-left, hence the user's "have to click
+     * many times" complaint. Using `hudCam.getWorldPoint(...)` applies
+     * the cam's inverse transform (subtract viewport offset, divide by
+     * zoom) and lands in widget coord space.
+     */
+    private pointerCoords;
+    private handlePointerDown;
+    private handlePointerMove;
+    private handlePointerUp;
+    /**
+     * Pointer-down inside paint mode. Returns true when the pointer hit the
+     * active layer (stroke began); false when the pointer fell outside the
+     * tilemap's bounds (caller falls through to normal selection).
+     *
+     * Begins a stroke + applies the first cell. brush/eraser tools paint
+     * incrementally per pointermove; rect/fill/picker (Phase B.4) handle
+     * pointerdown specially — for now only brush + eraser are wired.
+     */
+    private handleTilemapPaintDown;
+    private handleTilemapPaintMove;
+    /**
+     * Compose stroke into one TilemapEditOp + post to host. Host records the
+     * undo command + persists on next flush. Stroke state is cleared.
+     *
+     * Brush stroke → `paint` op with all cells. Eraser stroke → `erase` op.
+     * (Phase B.4 adds rect / fill emit paths.)
+     */
+    private handleTilemapPaintUp;
+    /**
+     * Compose a `fillRect` op from the completed rect drag + apply it live +
+     * post tilemapEdited. `previousCells` captures every cell the rect
+     * overwrites so undo replays them onto the layer.
+     */
+    private commitTilemapRect;
+    /**
+     * Bucket fill (4-connected flood). Captures every cell the flood
+     * touches into previousCells before applying, then posts one tilemapEdited
+     * so undo restores the whole flooded area.
+     *
+     * Reads the layer in one pass to compute the visited set + previous
+     * indices, then commits via Phaser's putTileAt. Single-pass because
+     * applyTilemapOp would re-walk + duplicate work.
+     */
+    private applyBucketFill;
+    /**
+     * Slice 6 Phase D — autotile bucket fill. 4-connected flood over cells
+     * with matching tile index (or all empties), then runs the wang cascade
+     * for each flooded cell. The resulting `autotilePaint` op carries every
+     * flooded cell as a clicked cell; `previousCells` covers the flood +
+     * its 1-cell border for cascade-correct undo.
+     */
+    private applyAutotileBucketFill;
+    /**
+     * Look up the active TilemapLayer in the world scene's entity registry,
+     * then walk the container's children for the layer with matching
+     * `tilemapLayerId` data tag.
+     */
+    private findActiveTilemapLayer;
+    /**
+     * Same as findActiveTilemapLayer but returns the container too. Callers
+     * that need to convert world coords to tile coords need the container's
+     * position to shift the input — `TilemapLayer.worldToTileXY` doesn't
+     * apply the container transform on its own (the layer's `x`/`y` are
+     * local to the container, not world coords).
+     */
+    private findActiveTilemapLayerWithContainer;
+    /**
+     * Apply one stroke cell: read prev index (for undo), apply the new
+     * value via Phaser's tilemap API, push the cell into the stroke
+     * accumulator. Dedup happens in `appendTilemapStrokeCell` so dragging
+     * over the same cell multiple times only records once.
+     */
+    private applyStrokeCell;
+    /**
+     * Slice 6 Phase D — resolve `{ asset, terrain }` for the layer's
+     * tileset + a requested terrain id. Returns null when:
+     *  - the layer has no `tilemapTilesetId` stamp (legacy / unattached layer)
+     *  - the manifest has no asset for that id
+     *  - the asset's tileset metadata lacks `autotile.terrains` with that id
+     * Callers fall back to stamp-mode behavior on null.
+     */
+    private resolveAutotileTerrainContext;
+    /**
+     * Slice 6 Phase D — autotile-mode stroke cell. Runs the Wang cascade
+     * via `applyAutotile`, threads every affected cell (clicked + cascade
+     * neighbors) into the stroke accumulator so the pointerup commit can
+     * emit one `autotilePaint` op + a previousCells array that captures
+     * the entire region the click changed.
+     *
+     * Per-frame metadata + sub-tile body sync is handled by the host-
+     * driven `handleEditTilemap` path when undo replays inverse ops; the
+     * live stroke only touches `layer.data` (cell indices) — fine because
+     * cell-rect collision is re-armed at the next handleEditTilemap call.
+     */
+    private applyAutotileStrokeCell;
+    /**
+     * Sync every tilemap entity's TilemapLayers to its container's
+     * current world position. Runs every frame in edit mode (see update()).
+     * Matches the play-mode hook in SceneLoader#installTilemapLayerSync —
+     * same logic, different trigger source (overlay vs world scene event).
+     * Cheap: handful of number assignments per tilemap.
+     */
+    private syncTilemapLayersFromContainers;
+    /**
+     * Read the selected tilemap entity's bounds + return the 8 handle
+     * positions in world coords. Returns null when the selected entity
+     * is not a tilemap (no handles to draw / hit-test).
+     */
+    private tilemapHandlePositions;
+    /**
+     * Hit-test the resize handles. Corners (NW/NE/SW/SE) use a dedicated
+     * ~14px square click target. Edges (N/S/E/W) are grabbable along the
+     * ENTIRE edge line (Figma / Sketch convention) — clicking anywhere on
+     * the blue bounds line resizes that edge. Corner zones take priority
+     * over edges so dragging right at a corner gives diagonal resize, not
+     * single-axis.
+     *
+     * All click targets are zoom-invariant via `1/zoom` scaling so they
+     * stay constant size on screen regardless of how zoomed in/out.
+     */
+    private hitTestTilemapResizeHandle;
+    /**
+     * Set canvas cursor to a resize-arrow when hovering a handle, or restore
+     * default. Direction matches the handle's axis (Figma / Sketch / browser
+     * native convention):
+     *   NW/SE corners → `nwse-resize` (↖↘)
+     *   NE/SW corners → `nesw-resize` (↗↙)
+     *   N/S edges → `ns-resize` (↕)
+     *   E/W edges → `ew-resize` (↔)
+     *
+     * Active drag (getTilemapResize non-null) pins the cursor to the dragged
+     * handle so it doesn't flicker back to default when the cursor briefly
+     * leaves the handle's 14px target box during fast drag.
+     */
+    private updateResizeCursor;
+    /**
+     * Begin a resize-handle drag. Snapshots the starting size + center so
+     * pointermove can compute deltas relative to drag-start.
+     */
+    private beginTilemapResizeDrag;
+    /**
+     * Update preview dims based on cursor position. Snaps to integer cells.
+     * The handle dictates which edges move — opposite edges stay fixed.
+     *
+     * Algorithm: from the cursor position + handle, compute the new L/R/T/B
+     * edges; opposite edges are pinned to start values. New size = R-L, B-T
+     * in pixels → divide by tileSize for cell counts. New center = midpoint
+     * of new L/R/T/B.
+     */
+    private updateTilemapResizeDrag;
+    /**
+     * Commit the resize drag — post a `resize` op via `editTilemap` channel,
+     * carrying the new dims + transformDelta to keep the opposite edge
+     * anchored. Posted directly to host (skipping the local SDK apply path)
+     * because the host's draft + iframe runtime BOTH need the op — host
+     * records the command for undo + applies the same op back via the
+     * normal editTilemap dispatch (which mutates the live runtime).
+     */
+    private commitTilemapResize;
+    update(): void;
+    /**
+     * Render the 8 resize handles (when paint mode is active) and the
+     * orange ghost-rect preview (when a resize drag is in progress).
+     * Handles are zoom-invariant ~12px squares; preview rect snaps to
+     * cell boundaries via the resize-drag's running preview state.
+     */
+    private drawTilemapResizeOverlay;
+    /**
+     * Walks the world entity registry and draws each sprite's `hitbox` rect +
+     * `depthAnchor` crosshair (when present on the entity's Asset). Sprites
+     * without metadata get nothing drawn — chat-only Workflow A respect.
+     *
+     * Per-frame mode: reads the sprite's CURRENT frame index and looks up the
+     * override (falls back to default) so the rendered rect tracks what the
+     * SDK is actually applying to the body at runtime.
+     */
+    private drawHitboxDebug;
+    /**
+     * For per-frame hitboxes, pick the shape the SDK would currently be
+     * applying — the override for the playing frame, falling back to default.
+     * For single-shape hitboxes, just return the rect.
+     */
+    private resolveCurrentHitboxShape;
+    private findWorldSceneInstance;
+    /**
+     * Find the world scene's main camera so the overlay can mirror it.
+     * In edit mode, the world scene is paused but its camera state is what
+     * the overlay's pointer math should use.
+     */
+    private findWorldSceneCamera;
+    /**
+     * P1 infinite canvas — read the editor camera installed by
+     * `installEditorCameras` in EditorBridge. Returns null on the boot race
+     * when the overlay scene's `create` runs before the bridge attaches it
+     * (resolved by the next `applyEditorPanZoom` mirror).
+     */
+    private findEditorCamera;
+    /**
+     * The camera the editor is currently viewing through. Prefers the
+     * editor cam; falls back to the game's cameras.main if the editor cam
+     * hasn't been installed yet (boot race). All pan/zoom math + selection
+     * rects should use this, NOT cameras.main directly.
+     */
+    private findActiveEditorCamera;
+    /**
+     * P1 infinite canvas — install native DOM listeners for wheel + space
+     * tracking. Phaser's pointer events don't surface `wheel`, and we want
+     * Space to be a global modifier (held while moving cursor), not tied to
+     * a specific GameObject. Listeners are torn down on scene shutdown.
+     *
+     * World mode only: HUD has identity camera + anchor-positioned widgets,
+     * panning/zooming it would rip widgets off their anchors.
+     */
+    private installPanZoomInput;
+    /**
+     * Be polite to text input — don't intercept Space when the user is
+     * typing into a form control inside the iframe (shouldn't normally
+     * happen, but be defensive).
+     */
+    private isTypingTarget;
+    /**
+     * Mode-aware registry lookup. World mode skips the HUD scene; HUD mode
+     * picks the HUD scene specifically.
+     */
+    private findEntityRegistry;
+}
+export {};