@combos-fun/plugin-development-tool 0.0.33 → 0.0.35

package/agent-skill.md

@@ -138,8 +138,8 @@ triggers / spawn points later) but nothing else is registered yet.
   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
+  editing (e.g. `Sound.volume`) go through the normal
+  selection → snapshot (`fieldDescriptors`) → `apply-property` flow and **persist to source** like any
   other scene edit. **The marked object must therefore carry a
   `CombosDevelopmentToolTarget`** added by game code. Objects with a `Sound`
   component must be given a Target when they should be editable even when they
@@ -147,6 +147,14 @@ triggers / spawn points later) but nothing else is registered yet.
   marker badges do not overlap.
 - On (re)build it posts `combos-development-tool:marker-overlay-success` with per-component counts.
 
+## Scene Edit fieldDescriptors
+
+Selection snapshots no longer dump raw component `fields`. The host receives only
+schema-backed `fieldDescriptors` derived from `@Field` metadata (`label`,
+`description`, editor hints, min/max/step, etc.). Fields without a non-empty
+`description` are omitted. Custom game Components that should appear in Creator
+must declare `@Field({ label, description, ... })` in the user's language.
+
 ## Verification
 
 `pnpm --filter @combos-fun/plugin-development-tool run build`.

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

@@ -5,6 +5,7 @@ var engine = require('@combos-fun/engine');
 var pluginRenderer = require('@combos-fun/plugin-renderer');
 var pluginRendererGraphics = require('@combos-fun/plugin-renderer-graphics');
 var pluginRendererEvent = require('@combos-fun/plugin-renderer-event');
+var inspectorDecorator = require('@combos-fun/inspector-decorator');
 
 /** Toggle development-tool selection / parent postMessage. Payload: `{ enabled: boolean }`. */
 const COMBOS_DEVELOPMENT_TOOL_SET = 'combos-development-tool:set';
@@ -201,30 +202,17 @@ function isSceneSourceAnchor(v) {
         typeof v.file === 'string');
 }
 
-const SKIP_KEYS = new Set([
-    'gameObject',
-    'name',
-    'started',
-    '__componentDefaultParams',
-    'destroyed',
-    'inScene',
-    'worldTransform',
-    'children',
-    '_parent',
-]);
-const COMPONENT_SKIP_KEYS = {
-    Graphics: new Set(['graphics']),
-    Physics: new Set([
-        'body',
-        'Body',
-        'PhysicsEngine',
-        'World',
-        'Constraint',
-        'mouseConstraint',
-        'bodyParams',
-    ]),
-    Event: new Set(['hitArea']),
-};
+function resolveValueType(value) {
+    if (typeof value === 'string')
+        return 'string';
+    if (typeof value === 'number')
+        return 'number';
+    if (typeof value === 'boolean')
+        return 'boolean';
+    if (value !== null && typeof value === 'object')
+        return 'object';
+    return 'unsupported';
+}
 function cloneJsonSafe(value, depth = 0) {
     if (value === null || value === undefined)
         return value;
@@ -249,20 +237,171 @@ function cloneJsonSafe(value, depth = 0) {
     }
     return undefined;
 }
+function readFieldReflectSchema(ctor) {
+    const properties = Reflect.getMetadata(inspectorDecorator.IDE_PROPERTY_METADATA, ctor) ||
+        {};
+    return Object.keys(properties).map(key => ({
+        key,
+        ...properties[key],
+    }));
+}
+/** Legacy `@type` / `@step` write `constructor.IDEProps` as an object keyed by property name. */
+function readLegacyIdePropsSchema(ctor) {
+    const raw = ctor.IDEProps;
+    if (!raw || Array.isArray(raw) || typeof raw !== 'object') {
+        return [];
+    }
+    return Object.keys(raw).map(key => {
+        const entry = raw[key] || {};
+        return {
+            key,
+            type: typeof entry.type === 'string' ? entry.type : undefined,
+            step: typeof entry.step === 'number' ? entry.step : undefined,
+            min: typeof entry.min === 'number' ? entry.min : undefined,
+            max: typeof entry.max === 'number' ? entry.max : undefined,
+            label: typeof entry.label === 'string' ? entry.label : undefined,
+            description: typeof entry.description === 'string' ? entry.description : undefined,
+            group: typeof entry.group === 'string' ? entry.group : undefined,
+            editor: entry.editor,
+            enumOptions: Array.isArray(entry.enumOptions) ? entry.enumOptions : undefined,
+            unit: typeof entry.unit === 'string' ? entry.unit : undefined,
+        };
+    });
+}
+function collectSchemaProps(comp) {
+    const ctor = comp.constructor;
+    const fromField = readFieldReflectSchema(ctor);
+    if (fromField.length > 0) {
+        return fromField;
+    }
+    return readLegacyIdePropsSchema(ctor);
+}
+function mapEditorKind(options, valueType) {
+    if (options.editor) {
+        return options.editor;
+    }
+    if (valueType === 'boolean')
+        return 'toggle';
+    if (options.enumOptions?.length && valueType === 'string')
+        return 'enum';
+    if (valueType === 'number') {
+        if (options.min !== undefined && options.max !== undefined) {
+            return 'number-slider';
+        }
+        return 'number-stepper';
+    }
+    if (valueType === 'string')
+        return 'text';
+    return undefined;
+}
+function buildNumberMeta(options) {
+    if (options.min === undefined &&
+        options.max === undefined &&
+        options.step === undefined &&
+        options.unit === undefined) {
+        return undefined;
+    }
+    return {
+        min: options.min,
+        max: options.max,
+        step: options.step,
+        unit: options.unit,
+    };
+}
+function titleCaseLeaf(leaf) {
+    return leaf
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .replace(/_/g, ' ')
+        .replace(/^./, char => char.toUpperCase());
+}
+function resolveLabel(options, path) {
+    if (options.label?.trim()) {
+        return options.label.trim();
+    }
+    const leaf = path[path.length - 1];
+    return leaf ? titleCaseLeaf(leaf) : undefined;
+}
+function leafDescriptorsFromValue(componentName, options, path, value) {
+    const description = options.description?.trim();
+    if (!description) {
+        // Scene Edit only exposes fields that include a human description.
+        return [];
+    }
+    const valueType = resolveValueType(value);
+    if (valueType === 'unsupported') {
+        return [];
+    }
+    const typeHint = options.type;
+    const isVector = typeHint === 'vector2' ||
+        (valueType === 'object' &&
+            value !== null &&
+            'x' in value &&
+            'y' in value);
+    const isSize = typeHint === 'size' ||
+        (valueType === 'object' &&
+            value !== null &&
+            'width' in value &&
+            'height' in value);
+    if (isVector || isSize) {
+        const record = value;
+        const axes = isSize ? ['width', 'height'] : ['x', 'y'];
+        const baseLabel = resolveLabel(options, path) ?? componentName;
+        const out = [];
+        for (const axis of axes) {
+            const axisValue = record[axis];
+            const axisType = resolveValueType(axisValue);
+            if (axisType === 'unsupported' || axisType === 'object')
+                continue;
+            const axisPath = [...path, axis];
+            out.push({
+                path: axisPath,
+                value: axisValue,
+                valueType: axisType,
+                label: `${baseLabel} ${axis.toUpperCase()}`,
+                description,
+                group: options.group ?? componentName,
+                editorKind: mapEditorKind(options, axisType),
+                numberMeta: buildNumberMeta(options),
+                persistTarget: componentName === 'Transform' ? 'gameObjectConstructor' : 'component',
+            });
+        }
+        return out;
+    }
+    if (valueType === 'object') {
+        return [];
+    }
+    const label = resolveLabel(options, path);
+    if (!label) {
+        return [];
+    }
+    return [
+        {
+            path,
+            value: cloneJsonSafe(value),
+            valueType,
+            label,
+            description,
+            group: options.group ?? componentName,
+            editorKind: mapEditorKind(options, valueType),
+            enumOptions: options.enumOptions,
+            numberMeta: buildNumberMeta(options),
+            persistTarget: componentName === 'Transform' ? 'gameObjectConstructor' : 'component',
+        },
+    ];
+}
 function serializeComponent(comp) {
-    const out = {};
-    const componentSkips = COMPONENT_SKIP_KEYS[comp.name];
-    for (const key of Object.keys(comp)) {
-        if (SKIP_KEYS.has(key) || key.startsWith('_'))
-            continue;
-        if (componentSkips?.has(key))
-            continue;
-        const value = comp[key];
+    const componentName = comp.name;
+    const schema = collectSchemaProps(comp);
+    if (schema.length === 0) {
+        return [];
+    }
+    const out = [];
+    const record = comp;
+    for (const prop of schema) {
+        const value = record[prop.key];
         if (typeof value === 'function')
             continue;
-        const cloned = cloneJsonSafe(value);
-        if (cloned !== undefined)
-            out[key] = cloned;
+        out.push(...leafDescriptorsFromValue(componentName, prop, [prop.key], value));
     }
     return out;
 }
@@ -281,8 +420,9 @@ function buildGameObjectSnapshot(go) {
         .filter(c => c.name !== 'CombosDevelopmentToolTarget')
         .map(c => ({
         componentName: c.name,
-        fields: serializeComponent(c),
-    }));
+        fieldDescriptors: serializeComponent(c),
+    }))
+        .filter(c => c.fieldDescriptors.length > 0);
     return {
         id: go.id,
         name: go.name,
@@ -1235,7 +1375,7 @@ 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.33",
+    packageVersion: "0.0.35",
 });
 
 exports.COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY = COMBOS_DEVELOPMENT_TOOL_APPLY_PROPERTY;