@combos-fun/plugin-development-tool 0.0.27 → 0.0.29

package/agent-skill.md

@@ -78,8 +78,32 @@ Outbound `postMessageOrigin` is separate — it limits which parent origin recei
 | parent → iframe | `combos-development-tool:set` | `{ enabled: boolean }` | Enable/disable pick mode |
 | parent → iframe | `combos-development-tool:clear-selection` | `{}` | Clear in-canvas outline |
 | parent → iframe | `combos-development-tool:apply-property` | component field mutation | Live preview |
+| parent → iframe | `combos-development-tool:set-marker-overlay` | `{ enabled: boolean }` | Toggle the marker overlay (independent of pick mode) |
 | iframe → parent | `combos-development-tool:gameobject-selected` | `{ snapshot, pointer }` | Object picked |
 | iframe → parent | `combos-development-tool:gameobject-deselected` | `{ reason }` | Selection cleared (`parent-request`, `pick-disabled`, `target-removed`) |
+| iframe → parent | `combos-development-tool:marker-overlay-success` | `{ enabled, total, markers: { componentName, count }[] }` | Marker overlay finished (re)building |
+
+## Marker overlay (surface invisible components)
+
+A reusable "pin a persistent icon on every object owning an otherwise invisible
+component" layer. Registry-driven (`markerLayer.ts` → `MARKER_COMPONENTS`).
+**For now it is `Sound` only** — the mechanism is generic (append `Physics` / `Camera` /
+triggers / spawn points later) but nothing else is registered yet.
+
+- Independent toggle, orthogonal to pick mode and mute: `setMarkerOverlay(true)` or
+  `postMessage({ type: 'combos-development-tool:set-marker-overlay', enabled: true })`
+  (also `window` CustomEvent / `game.emit`).
+- Draws the icon **in-engine** (a `Graphics` child GO pinned to the owner, so it
+  follows the object). The layer is **purely visual** — it does not wire up its own
+  selection. Because the icon adds to the owner's rendered bounds, the owner's own
+  `CombosDevelopmentToolTarget` pick gets a clickable hit area, so selecting and
+  editing (e.g. `Sound.config.volume`) go through the normal
+  selection → snapshot → `apply-property` flow and **persist to source** like any
+  other scene edit. **The marked object must therefore carry a
+  `CombosDevelopmentToolTarget`** (added by the game code — see the game template's
+  Scene Edit rules; objects with a `Sound` component must be given a Target even
+  when they render nothing).
+- On (re)build it posts `combos-development-tool:marker-overlay-success` with per-component counts.
 
 ## Verification
 

package/dist/plugin-development-tool.cjs.js

@@ -31,6 +31,18 @@ const COMBOS_DEVELOPMENT_TOOL_READY = 'combos-development-tool:ready';
 const COMBOS_DEVELOPMENT_TOOL_SET_MUTED = 'combos-development-tool:set-muted';
 /** iframe → parent (and `game.emit`): current mute snapshot after a successful change. */
 const COMBOS_DEVELOPMENT_TOOL_STATE_CHANGED = 'combos-development-tool:state-changed';
+/**
+ * Parent → iframe (also `window` CustomEvent / `game.emit`): toggle the marker
+ * overlay — a persistent, clickable icon on every object owning an otherwise
+ * invisible registered component (Sound first). Independent of pick mode and
+ * mute. Payload: `{ enabled: boolean }`.
+ */
+const COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY = 'combos-development-tool:set-marker-overlay';
+/**
+ * iframe → parent (and `game.emit`): marker overlay finished (re)building.
+ * Payload: `{ enabled: boolean, total: number, markers: { componentName, count }[] }`.
+ */
+const COMBOS_DEVELOPMENT_TOOL_MARKER_OVERLAY_SUCCESS = 'combos-development-tool:marker-overlay-success';
 
 /**
  * Marks a `GameObject` as selectable in editor pick mode. While the development tool is enabled,
@@ -48,6 +60,73 @@ class CombosDevelopmentToolTarget extends engine.Component {
     }
 }
 
+/**
+ * Registered marker kinds, in priority order: a GameObject is marked by the
+ * first registered component it owns. For now this is **`Sound` only**; the
+ * mechanism is generic (append Physics / Camera / triggers / spawn points later
+ * to reuse the same layer) but only audio is wanted right now.
+ */
+const MARKER_COMPONENTS = [
+    { componentName: 'Sound', badgeColor: 0x8b5cf6, glyph: 'speaker' },
+];
+/** Fixed badge size in the owner's local space. */
+const MARKER_ICON_SIZE = 28;
+/**
+ * First registered marker def whose component is present on `go`, else `null`.
+ * Priority follows {@link MARKER_COMPONENTS} order.
+ */
+function resolveMarkerDef(go, registry = MARKER_COMPONENTS) {
+    for (const def of registry) {
+        if (go.getComponent(def.componentName)) {
+            return def;
+        }
+    }
+    return null;
+}
+const GLYPH_COLOR = 0xffffff;
+/** Draw the rounded badge background shared by every glyph. */
+function drawBadge(g, def, size) {
+    g.clear();
+    g.roundRect(0, 0, size, size, size * 0.22);
+    g.fill({ color: def.badgeColor, alpha: 0.92 });
+    g.roundRect(0, 0, size, size, size * 0.22);
+    g.stroke({ width: Math.max(1, size * 0.05), color: 0xffffff, alpha: 0.6 });
+}
+/** A speaker cone + two volume bars, normalized to the `size` box. */
+function drawSpeakerGlyph(g, s) {
+    g.poly([
+        s * 0.28, s * 0.4,
+        s * 0.42, s * 0.4,
+        s * 0.55, s * 0.26,
+        s * 0.55, s * 0.74,
+        s * 0.42, s * 0.6,
+        s * 0.28, s * 0.6,
+    ]);
+    g.fill({ color: GLYPH_COLOR, alpha: 0.96 });
+    g.rect(s * 0.62, s * 0.44, s * 0.045, s * 0.12);
+    g.fill({ color: GLYPH_COLOR, alpha: 0.96 });
+    g.rect(s * 0.71, s * 0.39, s * 0.045, s * 0.22);
+    g.fill({ color: GLYPH_COLOR, alpha: 0.96 });
+}
+/** Generic fallback glyph for component kinds without a dedicated icon. */
+function drawDotGlyph(g, s) {
+    g.circle(s * 0.5, s * 0.5, s * 0.18);
+    g.fill({ color: GLYPH_COLOR, alpha: 0.96 });
+}
+/** Render a full marker (badge + glyph) into `g`, sized to `size` (local units). */
+function drawMarkerIcon(g, def, size = MARKER_ICON_SIZE) {
+    drawBadge(g, def, size);
+    switch (def.glyph) {
+        case 'speaker':
+            drawSpeakerGlyph(g, size);
+            break;
+        case 'dot':
+        default:
+            drawDotGlyph(g, size);
+            break;
+    }
+}
+
 /** Default inbound postMessage host suffixes (host + all subdomains). */
 const DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES = [
     'knoffice.tech',
@@ -371,6 +450,7 @@ function isClearSelectionMessage(data) {
 }
 
 const OUTLINE_GO_NAME = '__combosDevelopmentToolOutline';
+const MARKER_GO_NAME_PREFIX = '__combosDevelopmentToolMarker:';
 /**
  * **Off** at start. While enabled:
  * - soft-disables game `Event` hit targets (`container.interactive = false`, restored on disable);
@@ -411,6 +491,18 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         this.lastOutlineBounds = null;
         /** Remembered mute when `SoundSystem` is not registered yet. */
         this.mutedWithoutSoundSystem = false;
+        /**
+         * Marker overlay (see {@link markerLayer}): a visual-only icon layer, toggled
+         * independently of pick mode + mute. Selection/persistence are NOT handled here
+         * — a marked object (e.g. Sound) carries its own `CombosDevelopmentToolTarget`
+         * (added by the game code), so it is picked and serialized through the normal
+         * Target path. The icon just makes the invisible object visible and, by adding
+         * to the owner's rendered bounds, gives its Target pick a clickable hit area.
+         */
+        this.markerOverlayEnabled = false;
+        this.needsMarkerRescan = false;
+        /** ownerGoId → its marker GO (icon child, Graphics only). */
+        this.markerGoByOwner = new Map();
         this.onWindowSet = (e) => {
             const d = e.detail;
             if (d && typeof d.enabled === 'boolean') {
@@ -423,6 +515,17 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
                 this.setMuted(d.muted);
             }
         };
+        this.onWindowSetMarkerOverlay = (e) => {
+            const d = e.detail;
+            if (d && typeof d.enabled === 'boolean') {
+                this.setMarkerOverlay(d.enabled);
+            }
+        };
+        this.onGameSetMarkerOverlay = (payload) => {
+            if (payload && typeof payload.enabled === 'boolean') {
+                this.setMarkerOverlay(payload.enabled);
+            }
+        };
         this.onWindowMessage = (e) => {
             if (!isAllowedMessageOrigin(e.origin, this.allowedMessageOrigins)) {
                 return;
@@ -436,6 +539,10 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
             else if (d.type === COMBOS_DEVELOPMENT_TOOL_SET_MUTED && typeof d.muted === 'boolean') {
                 this.setMuted(d.muted);
             }
+            else if (d.type === COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY &&
+                typeof d.enabled === 'boolean') {
+                this.setMarkerOverlay(d.enabled);
+            }
             else if (d.type === COMBOS_DEVELOPMENT_TOOL_REFRESH) {
                 this.requestSceneRescan();
             }
@@ -470,11 +577,13 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         if (typeof window !== 'undefined') {
             window.addEventListener(COMBOS_DEVELOPMENT_TOOL_SET, this.onWindowSet);
             window.addEventListener(COMBOS_DEVELOPMENT_TOOL_SET_MUTED, this.onWindowSetMuted);
+            window.addEventListener(COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY, this.onWindowSetMarkerOverlay);
             window.addEventListener(COMBOS_DEVELOPMENT_TOOL_REFRESH, this.onWindowRefresh);
             window.addEventListener('message', this.onWindowMessage);
         }
         this.game.on(COMBOS_DEVELOPMENT_TOOL_SET, this.onGameSet);
         this.game.on(COMBOS_DEVELOPMENT_TOOL_SET_MUTED, this.onGameSetMuted);
+        this.game.on(COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY, this.onGameSetMarkerOverlay);
         this.game.on(COMBOS_DEVELOPMENT_TOOL_REFRESH, this.onGameRefresh);
         if (this.enabled) {
             this.needsRescan = true;
@@ -484,13 +593,16 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         if (typeof window !== 'undefined') {
             window.removeEventListener(COMBOS_DEVELOPMENT_TOOL_SET, this.onWindowSet);
             window.removeEventListener(COMBOS_DEVELOPMENT_TOOL_SET_MUTED, this.onWindowSetMuted);
+            window.removeEventListener(COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY, this.onWindowSetMarkerOverlay);
             window.removeEventListener(COMBOS_DEVELOPMENT_TOOL_REFRESH, this.onWindowRefresh);
             window.removeEventListener('message', this.onWindowMessage);
         }
         this.game.off(COMBOS_DEVELOPMENT_TOOL_SET, this.onGameSet);
         this.game.off(COMBOS_DEVELOPMENT_TOOL_SET_MUTED, this.onGameSetMuted);
+        this.game.off(COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY, this.onGameSetMarkerOverlay);
         this.game.off(COMBOS_DEVELOPMENT_TOOL_REFRESH, this.onGameRefresh);
         this.detachAllPicks();
+        this.detachAllMarkers();
         this.restoreDisabledGameEvents();
         this.clearSelectionAndNotify('pick-disabled');
     }
@@ -512,6 +624,35 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
     get isEnabled() {
         return this.enabled;
     }
+    /**
+     * Toggle the marker overlay: pin a persistent icon on every object that owns a
+     * registered invisible component ({@link markerLayer}, Sound first). Independent
+     * of pick mode / mute. This layer is purely visual — the icon makes the object
+     * visible and adds to its rendered bounds so the owner's own
+     * `CombosDevelopmentToolTarget` pick gets a clickable hit area. Selecting and
+     * persisting edits (e.g. volume) still go through that Target, exactly like any
+     * other scene edit, so the object must carry a Target (added by the game code).
+     */
+    setMarkerOverlay(on) {
+        if (this.markerOverlayEnabled === on)
+            return;
+        this.markerOverlayEnabled = on;
+        if (on) {
+            // `attachMarkers` requests the pick rescan itself, once the icons exist.
+            this.needsMarkerRescan = true;
+        }
+        else {
+            this.detachAllMarkers();
+            this.postMarkerOverlaySuccess(false, []);
+            // Shrink owners' pick hit areas back now that the icons are gone.
+            if (this.enabled) {
+                this.needsRescan = true;
+            }
+        }
+    }
+    get isMarkerOverlayEnabled() {
+        return this.markerOverlayEnabled;
+    }
     /** Master mute when `SoundSystem` exists; otherwise the last requested value. */
     get isMuted() {
         const sound = this.getSoundSystem();
@@ -540,11 +681,26 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
             this.attachEditMode();
             this.postSetSuccess(true);
         }
+        // Attaching markers is deferred to run *after* the pick rescan above so that a
+        // newly drawn icon's rebuild lands on a later frame (see `attachMarkers`): the
+        // icon child needs a rendered container before it contributes to the owner's
+        // bounds, and only then does the owner's Target pick get a hit area over it.
+        if (this.markerOverlayEnabled && this.needsMarkerRescan) {
+            this.needsMarkerRescan = false;
+            this.attachMarkers();
+        }
         for (const go of [...this.tapOwners.values()]) {
             if (go.destroyed) {
                 this.releasePick(go);
             }
         }
+        // Drop markers whose owner disappeared while the overlay is on.
+        for (const [ownerId, marker] of [...this.markerGoByOwner.entries()]) {
+            const owner = this.findGameObjectById(ownerId);
+            if (!owner || owner.destroyed || marker.destroyed) {
+                this.removeMarker(ownerId);
+            }
+        }
         if (!this.enabled || !this.selected || !this.outlineGo)
             return;
         this.updateSelectionOutline();
@@ -566,11 +722,14 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
             }
         }
     }
-    /** Re-bind pick targets after dynamic scene changes while enabled. */
+    /** Re-bind pick targets / markers after dynamic scene changes while active. */
     requestSceneRescan() {
-        if (!this.enabled)
-            return;
-        this.needsRescan = true;
+        if (this.enabled) {
+            this.needsRescan = true;
+        }
+        if (this.markerOverlayEnabled) {
+            this.needsMarkerRescan = true;
+        }
     }
     attachEditMode() {
         this.detachAllPicks();
@@ -598,7 +757,10 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         }
     }
     isIgnoredPickGo(go) {
-        return go.name === OUTLINE_GO_NAME || go === this.outlineGo;
+        return go.name === OUTLINE_GO_NAME || go === this.outlineGo || this.isMarkerGo(go);
+    }
+    isMarkerGo(go) {
+        return typeof go.name === 'string' && go.name.startsWith(MARKER_GO_NAME_PREFIX);
     }
     stripGameEvent(go) {
         if (this.disabledGameEventGoIds.has(go.id))
@@ -815,6 +977,78 @@ let CombosDevelopmentToolSystem$1 = class CombosDevelopmentToolSystem extends en
         }
         this.game.emit(COMBOS_DEVELOPMENT_TOOL_STATE_CHANGED, state);
     }
+    /** (Re)build markers for every object owning a registered marker component. */
+    attachMarkers() {
+        this.detachAllMarkers();
+        const list = [];
+        for (const tr of this.game.scene.transform.children) {
+            this.collectGameObjects(tr.gameObject, list);
+        }
+        const counts = new Map();
+        for (const go of list) {
+            if (this.isIgnoredPickGo(go))
+                continue;
+            const def = resolveMarkerDef(go);
+            if (!def)
+                continue;
+            this.createMarker(go, def);
+            counts.set(def.componentName, (counts.get(def.componentName) ?? 0) + 1);
+        }
+        const markers = [...counts.entries()].map(([componentName, count]) => ({
+            componentName,
+            count,
+        }));
+        this.postMarkerOverlaySuccess(true, markers);
+        // Rebuild picks next frame: the icons just added need a rendered container
+        // before they enlarge their owners' bounds into a clickable hit area. Runs on
+        // a later frame because the pick rescan block already executed above.
+        if (this.enabled) {
+            this.needsRescan = true;
+        }
+    }
+    createMarker(owner, def) {
+        if (this.markerGoByOwner.has(owner.id))
+            return;
+        const bounds = this.resolvePickBounds(owner);
+        const marker = new engine.GameObject(MARKER_GO_NAME_PREFIX + owner.id, {
+            size: { width: MARKER_ICON_SIZE, height: MARKER_ICON_SIZE },
+            position: { x: bounds.x, y: bounds.y },
+            origin: { x: 0, y: 0 },
+        });
+        const gfx = marker.addComponent(new pluginRendererGraphics.Graphics());
+        if (gfx?.graphics) {
+            drawMarkerIcon(gfx.graphics, def, MARKER_ICON_SIZE);
+        }
+        owner.addChild(marker);
+        this.markerGoByOwner.set(owner.id, marker);
+    }
+    removeMarker(ownerId) {
+        const marker = this.markerGoByOwner.get(ownerId);
+        if (!marker)
+            return;
+        this.markerGoByOwner.delete(ownerId);
+        if (!marker.destroyed) {
+            marker.destroy();
+        }
+    }
+    detachAllMarkers() {
+        for (const ownerId of [...this.markerGoByOwner.keys()]) {
+            this.removeMarker(ownerId);
+        }
+        this.markerGoByOwner.clear();
+    }
+    postMarkerOverlaySuccess(enabled, markers) {
+        const total = markers.reduce((sum, m) => sum + m.count, 0);
+        const state = { enabled, total, markers };
+        const payload = {
+            type: COMBOS_DEVELOPMENT_TOOL_MARKER_OVERLAY_SUCCESS,
+            ...state,
+        };
+        if (typeof window !== 'undefined' && window.parent && window.parent !== window) {
+            window.parent.postMessage(payload, this.postMessageOrigin);
+        }
+        this.game.emit(COMBOS_DEVELOPMENT_TOOL_MARKER_OVERLAY_SUCCESS, state);
+    }
     getSoundSystem() {
         const system = this.game.getSystem('SoundSystem');
         if (!system ||
@@ -1001,30 +1235,36 @@ var CombosDevelopmentToolSystem = CombosDevelopmentToolSystem$1;
 /** Auto-generated by scripts/build-package.mjs — do not edit. */
 Object.assign(CombosDevelopmentToolSystem, {
     packageName: "@combos-fun/plugin-development-tool",
-    packageVersion: "0.0.27",
+    packageVersion: "0.0.28",
 });
 
 exports.COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY = COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY;
 exports.COMBOS_DEVELOPMENT_TOOL_CLEAR_SELECTION = COMBOS_DEVELOPMENT_TOOL_CLEAR_SELECTION;
 exports.COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_DESELECTED = COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_DESELECTED;
 exports.COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_SELECTED = COMBOS_DEVELOPMENT_TOOL_GAMEOBJECT_SELECTED;
+exports.COMBOS_DEVELOPMENT_TOOL_MARKER_OVERLAY_SUCCESS = COMBOS_DEVELOPMENT_TOOL_MARKER_OVERLAY_SUCCESS;
 exports.COMBOS_DEVELOPMENT_TOOL_READY = COMBOS_DEVELOPMENT_TOOL_READY;
 exports.COMBOS_DEVELOPMENT_TOOL_REFRESH = COMBOS_DEVELOPMENT_TOOL_REFRESH;
 exports.COMBOS_DEVELOPMENT_TOOL_SET = COMBOS_DEVELOPMENT_TOOL_SET;
+exports.COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY = COMBOS_DEVELOPMENT_TOOL_SET_MARKER_OVERLAY;
 exports.COMBOS_DEVELOPMENT_TOOL_SET_MUTED = COMBOS_DEVELOPMENT_TOOL_SET_MUTED;
 exports.COMBOS_DEVELOPMENT_TOOL_SET_SUCCESS = COMBOS_DEVELOPMENT_TOOL_SET_SUCCESS;
 exports.COMBOS_DEVELOPMENT_TOOL_STATE_CHANGED = COMBOS_DEVELOPMENT_TOOL_STATE_CHANGED;
 exports.CombosDevelopmentToolSystem = CombosDevelopmentToolSystem;
 exports.CombosDevelopmentToolTarget = CombosDevelopmentToolTarget;
 exports.DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES = DEFAULT_ALLOWED_MESSAGE_HOST_SUFFIXES;
+exports.MARKER_COMPONENTS = MARKER_COMPONENTS;
+exports.MARKER_ICON_SIZE = MARKER_ICON_SIZE;
 exports.applyPropertyValue = applyPropertyValue;
 exports.applyPropertyWithHooks = applyPropertyWithHooks;
 exports.buildGameObjectDeselectedPayload = buildGameObjectDeselectedPayload;
 exports.buildGameObjectSnapshot = buildGameObjectSnapshot;
+exports.drawMarkerIcon = drawMarkerIcon;
 exports.isAllowedMessageOrigin = isAllowedMessageOrigin;
 exports.isClearSelectionMessage = isClearSelectionMessage;
 exports.mergeAllowedMessageOrigins = mergeAllowedMessageOrigins;
 exports.readPropertyValue = readPropertyValue;
 exports.readSourceAnchor = readSourceAnchor;
+exports.resolveMarkerDef = resolveMarkerDef;
 exports.shouldNotifyGameObjectDeselected = shouldNotifyGameObjectDeselected;
 //# sourceMappingURL=plugin-development-tool.cjs.js.map