扩展开发：引擎接口

// VM 那一半：和往常一样
class MyExtension {
    constructor (runtime) { this.runtime = runtime; }
    getInfo () { return {id: 'myext', name: '我的扩展', blocks: [/* … */]}; }
}
globalThis.tempExt = {Extension: MyExtension, info: {extensionId: 'myext', name: '我的扩展'}};

// 编辑器那一半：宿主准备好了就装，没准备好先排队；不是 Gandi 3.0 就整个跳过
const mod = {
    id: 'myext',
    name: '我的扩展',
    setup (ctx) {
        // 下面各节的 ctx.register… 都写在这里
    }
};
if (window.__gandi3Engine) {
    window.__gandi3Engine.install(mod);
} else if (typeof window !== 'undefined') {
    (window.__gandi3EngineQueue = window.__gandi3EngineQueue || []).push(mod);
}

const obj = ctx.objects.current();       // 当前物体（装配编辑器或角色栏正在看的那个）
obj.id; obj.name; obj.spriteId;
obj.costumes;                            // 属于它的造型名，按顺序
obj.anchors;                             // 挂点 [{id, name, mode, at?, frames?}]
obj.data('light');                       // 这一节的数据（不含默认值）
obj.set('light', {radius: 200});         // 改一部分；进撤销栈，Ctrl+Z 可撤
obj.anchor('a1', costumeName);           // 挂点在某一帧的位置 {x, y}，本地坐标（y 向下）

obj.items('light');                     // 一列的那种节：这个物体上的每一件（不含默认值）
obj.addItem('light', {radius: 200});    // 装一件，名字自动编号（灯 1、灯 2）
obj.setItem('light', id, {radius: 300});
obj.removeItem('light', id);

ctx.objects.list(spriteId);              // 角色的全部物体
ctx.objects.mark(spriteId, '文件夹', true); // 把文件夹设为物体
ctx.objects.on('change', (obj, ns) => {}); // 任何物体的数据改了
ctx.objects.costume();                   // 当前帧（造型名）

{marks: ['文件夹', …], objects: {[folder]: {anchors: [...], data: {[ns]: {...}}, items: {[ns]: [{id, name, …}]}}}}

obj.setItem('light', id, {radius: 300}, {key: 'radius', label: '改半径'});

ctx.objects.scene('physicsWorld');       // {gravityY: -300, …}
ctx.objects.setScene('physicsWorld', {gravityY: -300});

api.objectFor(ns)              // 不带件 = 当前物体那一级（新建落这儿）
api.ownerOf(ns, itemId)        // 这一件所在的那一层（改属性、删件用它）
api.costumeObject()            // 这一张造型自己那一层（「只加到这一张」）
api.layerOf(ns, itemId)        // 'object' | 'costume' | null
api.moveToLayer(ns, itemId, to)// 把一件搬到另一层

objects.resolveItems(target, ns, costumeName)  // {items, fromObject, fromCostume}（fromObject 是各级加起来的）
objects.rowOfItem(target, ns, itemId, costumeName)  // 这一件存在哪一行：文件夹路径或造型作用域
objects.ownCount(target, ns, costumeName)      // 这一张自己加了几件
objects.clearOwnItems(target, ns, costumeName) // 清掉这一张自己加的

ctx.registerObjectSection({
    id: 'light',                 // 数据的命名空间
    title: '光',
    tint: '#ffd34d',
    defaults: {on: false, type: 'point', colour: '#ffd27a', radius: 160},
    summary: d => (d.on ? `${d.radius}px` : '关'),   // 折起来时标题右边那句
    rows: [
        {kind: 'switch', key: 'on', label: '开'},
        {kind: 'anchor', key: 'anchor', label: '挂在', when: d => d.on},
        {kind: 'seg', key: 'type', label: '类型', options: ['point', 'spot'], when: d => d.on},
        {kind: 'colour', key: 'colour', label: '颜色', when: d => d.on},
        {kind: 'number', key: 'radius', label: '半径', suffix: 'px', min: 1, max: 4000, when: d => d.on},
        {kind: 'group', label: '进阶', children: [
            {kind: 'slider', key: 'intensity', label: '强度', min: 0, max: 4, step: 0.05},
            {kind: 'select', key: 'falloff', label: '衰减', options: ['linear', 'quad']}
        ]},
        {kind: 'button', label: '重置', onClick: api => api.set({...api.data(), radius: 160})},
        {kind: 'note', text: '半径按舞台像素算'}
    ]
});

ctx.registerRigTool({
    id: 'light', label: '光源', key: 'L', tint: '#ffd34d', icon: '◐',
    section: 'light',                    // 用哪一节的数据；右栏就是那一节
    draw (g, {data, anchor, selected}) { // data 已合并 defaults
        if (!data.on) return;
        g.ring(anchor.x, anchor.y, data.radius, {tint: '#ffd34d', dash: true});
        if (selected) g.handle('radius', anchor.x + data.radius, anchor.y, {shape: 'big'});
    },
    onDrag (handle, pt, {anchor, set}) {
        if (handle === 'radius') set({radius: Math.round(Math.hypot(pt.x - anchor.x, pt.y - anchor.y))});
    },
    onPlace (pt, {set, nearestAnchor}) {  // 空白处点一下
        set({on: true, anchor: nearestAnchor?.id ?? ''});
    }
});

ctx.registerRigPage({
    label: '碰撞', order: 0,
    anchors: false,                       // 这一页不要挂点工具
    tint: '#7c5cff',
    status (object, costume) {            // 页头右边那句：现在配成什么样
        const n = object.items('hull').length;
        return n ? {text: `${n} 个形状`, tone: 'ok'} : {text: '逐像素', tone: 'warn', hint: '没画碰撞体'};
    }
});

ctx.registerRigPage({
    label: '粒子', chrome: {right: false},
    right (host, api) {
        host.append(buildMyPanel(api));
        return () => host.replaceChildren();   // 返回值当卸载函数
    }
});

right (host, api) {
    const paint = () => { host.textContent = api.costume + ' / ' + api.selection.kind; };
    paint();
    return api.on(paint);   // 选中、造型、物体、这个角色名下的数据，任一变化就叫一声
}

render (host, api) {
    host.innerHTML = '<div class="my-side"></div><div class="my-canvas"></div>';
    const off = api.mountCanvas(host.querySelector('.my-canvas'));
    return () => { off(); host.replaceChildren(); };
}

ctx.registerRigPage({label: '粒子', order: 2, tint: '#ff9a4d', host: 'particles'});

ctx.registerStageLayer({
    id: 'light', label: '光照', tint: '#ffd34d',
    defaultOn: 'selected',               // 'on' | 'selected'（只有选中角色时）| 'off'
    draw (g, {targets}) {
        for (const t of targets) {       // {targetId, object, costume, x, y, direction, size, selected}
            const d = t.object && {...DEFAULTS, ...t.object.data('light')};
            if (!d?.on) continue;
            g.ring(t.x, -t.y, d.radius * t.size / 100, {tint: '#ffd34d'});
        }
    }
});

ctx.registerEditor({
    id: 'path', scope: 'sprite', title: s => `路径（${s.name}）`, icon: '↝', group: '应用',
    chrome: {left: false, strip: false},   // 裁掉左栏和帧条；left/canvas/right/strip 四块
    tools: ['hull'],                       // 骨架里只留这些装配工具；不给就全部
    draw (g, {object, costume}) {          // 编辑器自己的手柄
        const pts = object.data('path').points ?? [];
        g.outline(pts, {tint: '#f0f'});
        g.nodes(pts, {tint: '#f0f', idPrefix: 'p'});
    },
    onDrag (handle, pt, {object}) {
        const i = Number(handle.split(':')[1]);
        const points = (object.data('path').points ?? []).map((p, k) => (k === i ? pt : p));
        object.set('path', {points});
    },
    onPlace (pt, {object}) {
        object.set('path', {points: [...(object.data('path').points ?? []), pt]});
    },
    render (host, {object, costume, frames, setFrame}) {   // 右栏，三档写法任选
        host.textContent = `${object.name} · ${frames.length} 帧`;
    }
});

ctx.registerEditor({
    id: 'sheet', scope: 'sprite', title: '表格', chrome: false,
    render (host, {subjectId, target, vm}) {
        host.innerHTML = '<table>…</table>';
        return () => {/* 关掉时清理 */};
    }
    // 或 component: MySheet —— props 是 {subjectId, target, vm}
});

ctx.registerPanelWith('curve', '曲线编辑器', host => {
    host.textContent = '…';
    return () => {/* 关掉时清理 */};
}, {
    icon: '<svg …>',     // SVG、内置图标名，或一两个字
    group: '应用',       // 抽屉里分在哪一组
    hint: '编辑缓动曲线',
    placement: {group: 'float'},
    bar: true            // false 则不进抽屉，只能由扩展自己打开
});

ctx.contribute('sprite.inspector.fields', {
    where: 'after', target: 'size',
    rows: [{kind: 'number', key: 'mass', label: '质量', suffix: 'kg'}]
});

ctx.runtime.objectData(target, ns)      // 这一只角色 / 克隆体此刻的一节数据（含临时覆盖，含默认值前请自己合并）
ctx.runtime.override(target, ns, patch) // 积木改的临时覆盖；null 清掉
ctx.runtime.anchor(target, anchorId)    // 挂点在舞台上的位置（已按位置、方向、大小换算）
ctx.runtime.objectId(target)            // 这一只此刻属于哪个物体
ctx.runtime.sceneData(ns)               // 场景级数据
ctx.runtime.frameBudgetMs()             // 一帧的预算，超了就该降质量

ctx.vm                                  // scratch-vm
ctx.react / ctx.reactDom                // 宿主那一份 React，别自己再打包一份
ctx.ui                                  // {Field, Group, NumberField, ColourField, Segmented, Select, IconButton}
ctx.settings.get / set                  // 插件设置（插件系统的）
ctx.registerEntry / registerSettings / registerPanel / openPanel   // 插件系统原有的

const lighting = renderer.lighting;
// 自己的一组灯：和场景的灯叠在一起，按 key 分开，互不覆盖；null 或 [] 撤掉
lighting.setExtraLights('particles', [
    {type: 'point', x, y, color: [1, 0.6, 0.2], intensity: 0.8, radius: 60, height: 20, halo: 0.5, shadows: false}
]);