Studio v0.1.1
Studio v0.1.1 · 产品手册

插件 SDK 开发

插件 SDK 开发:GalCraft Studio 操作与参考。

属性内容
范围SDK、插件 0.1.0;引擎 0.1.1;清单 1/2;Web / Windows
分发维护者通过 npm 与 GitHub Release 发布 0.1.0 SDK,代码使用 MPL-2.0

开发者通过 @galcraft/plugins/contracts 获取贡献与服务类型,通过 @galcraft/plugins/react 使用宿主共享 React,通过 @galcraft/plugins/pixi 的 Pixi / PIXI 使用宿主共享 Pixi。插件使用公开接口;宿主组装负责注册表、存储和 IPC。开发者在独立目录安装 contracts 与 plugins 两个 SDK 产物,不引用仓库源码路径。

第一次建议创建 author-tool:它提供一个读取当前语句选区的报告工具,便于核对“构建 → 安装 → 启用 → 实际执行”整条路径。这个练习使用 npm SDK,作者准备好 Node.js 后即可开始。独立插件开发 CLI 要求 Node.js 22.12.0 或更高版本,推荐 Node.js 24 LTS 最新补丁,使用 Node.js 自带的 npm 即可。contracts 与可选 DSL 解析器同时提供浏览器入口,浏览器消费者无需 Node.js。运行已安装插件的普通作者可直接阅读插件安装。

1. 准备 SDK

插件作者从 npm 安装 @galcraft/contracts@0.1.0 和 @galcraft/plugins@0.1.0;读取 GalCraft 语句的插件另安装 @galcraft/dsl@0.1.0。0.1.0 Release同时提供相同 tarball。SDK 许可说明说明 MPL-2.0 与源码入口。

源码维护者需要自行生成 SDK 时,按源码开发准备固定环境,在仓库根执行 node tools/plugin-development/distribute-sdk.mjs out/sdk,取得三个 tarball 与 sdk-distribution.json。

2. 创建并构建第一个插件

在仓库外的工作目录打开 PowerShell。先安装精确 SDK 以取得脚手架命令,再在 example 子目录安装独立插件的依赖:

mkdir my-plugin
cd my-plugin
npm init -y
npm install @galcraft/contracts@0.1.0 @galcraft/plugins@0.1.0
npx --no-install galcraft-plugin create example org.example.plugin author-tool
cd example
npm install @galcraft/contracts@0.1.0 @galcraft/plugins@0.1.0
npm run typecheck
npm run build
npm run check
npm run pack

每条命令成功后再执行下一条。脚手架目标 example 需要为空;已有内容时换一个新目录。

文件或命令用途与成功结果
plugin.config.json编辑插件身份、贡献声明和源码入口;构建读取这份配置
src/definition.ts提供无 DOM 定义、文档字段与文字资源
src/editor.ts实现 Studio 的选区报告和字段编辑器
npm run typecheck核对 TypeScript 与 SDK 类型;通过后继续构建
npm run build从源码生成 package/manifest.json 和逐环境 ESM 产物
npm run check核对生成包的清单、贡献实现及依赖图
npm run pack检查通过后在 dist/ 生成 .galplugin 普通安装包

修改 src/ 或配置后重新构建、检查、打包。生成的 package/ 是装载产物,后续构建会重新生成它。

脚手架还提供 game-system、resource-stage、service-provider 和 complete。熟悉第一个工具后,按实际需要选择游戏状态、素材舞台、制作服务或完整能力示例。

3. 安装并执行选区报告

  1. 打开一个练习作品,在 Studio → 插件中安装刚生成的 dist/*.galplugin。
  2. 检查包身份 org.example.plugin 和版本 0.1.0,确认安装;选择它并“启用到作品…”,审阅影响后确认,保存全部。
  3. 回到创作页,选中一条语句卡片。通过插件工具列表或命令面板打开“选区报告”。需要语句选区的工具会在适用条件中说明这一点。
  4. 执行工具,报告应显示 Selected statements: 1。再选中多条语句并重新打开工具,核对报告计数。

工具打开时固定本次选择。想检查新的范围时重新打开工具,再执行。这个报告读取选区,不产生作品编辑。

开发期间也可以通过“开发目录”检查并装载 example/package/。修改后先重新构建,再使用开发重载读取新产物;普通安装交付则选择新生成的 .galplugin。

改一段真正执行的代码

在生成的 src/editor.ts 中,找到 tools 数组里报告工具的 run,将该方法改成下面的内容。保留原有工具声明、导入和 fieldEditors:

run: async (_input, context, signal) => {
  if (signal.aborted) return ok({ kind: 'none' as const });
  const count = context.scope?.statementIds.length ?? 0;
  return ok({
    kind: 'report' as const,
    message: `我的插件收到了 ${count} 条选中语句。`,
    issues: [],
  });
},

这里的 ok 由脚手架的 common.ts 提供;context.scope 是本次执行的作者范围,report 让宿主呈现文字结果。重新运行类型检查、构建、检查和打包,再刷新开发目录或重新安装同版本包,关闭并重开工具。选中一条语句时,应看到“我的插件收到了 1 条选中语句。”。

遇到的问题下一步
找不到 SDK .tgz检查 $sdkDirectory 指向的实际交付目录与文件名
脚手架命令不可用确认在运行命令的目录成功安装了本地 plugins SDK;--no-install 只使用本地命令
check 报声明与实现不符对照 plugin.config.json 修正对应入口实现,重新构建再检查
工具不可用打开作品、启用精确版本,并按工具提示选择语句
仍显示旧报告重新构建,重载开发目录或重新安装新包,然后重开工具

插件名称与界面语言

清单的 name 和 description 保存作者原文。在 plugin.config.json 的 manifest 内,可用 localizations 提供其他语言的名称和说明。下面是应合入现有清单的字段片段:

{
  "name": "我的插件",
  "description": "显示当前选中的语句数量。",
  "localizations": {
    "en": {
      "name": "My plugin",
      "description": "Report the number of selected statements."
    }
  }
}

Studio 切换界面语言时同步更新插件展示文字;缺少对应翻译时显示原文。公开 pluginDisplayMetadata(manifest,locale) 按完整语言标记、语言主标记、原文依次解析。包 ID、版本和作品依赖保持原身份。

Studio 插件列表在每个精确版本旁显示当前作品的启用状态。安装在本机与启用到作品分别判断;确认启用/停用变更后,中央继续显示刚操作的插件和更新后的状态。

包和入口

清单 1 保留已有包行为。清单 2 必须提供 entry.definition,并按实际贡献提供 entry.editor、entry.services 和 entry.runtime。sdkMajor: 0 与 engineRange 共同说明兼容范围;当前包使用版本 0.1.0 和引擎范围 ^0.1.0。作品使用精确 Lock,真实变更版本时重新选择依赖。

当前随包引擎为 0.1.1,插件和 SDK 的精确版本保持 0.1.0。重新构建后通过普通安装刷新同版本插件;Studio 启动刷新随包引擎。活动插件先完成原租约,新装载使用更新后的文件;安装不改写作品 Lock、状态或历史任务输入。开发备份位于仓库 versions/0.1.0;安装时选择当前 package/ 或新生成的 .galplugin。清单 schemaVersion、contractVersion、typeVersion 和 stateVersion 各自描述格式或业务数据,不随开发刷新统一改号。

入口导出与环境内容
definitioncreateDefinition(): PluginDefinition 或 definition;无 DOM文档 schema、字段、初值、引用重写、转换、配置映射、语言资源
editorcreatePlugin(): GalCraftPlugin;Studio工具、字段编辑器;具名工作台另导出 createStudioPlugin()
servicescreatePlugin(): GalCraftPlugin;Node生成提供者、资源处理器、发布检查
runtimecreatePlugin(): GalCraftPlugin;试玩与 Player指令、条件、系统、页面、组件、资源、舞台、平台

dependencies 声明所有环境共同的插件依赖。environmentDependencies 分别声明 definition/editor/services/runtime 插件依赖,每项包含 id/range,可用 targets 限定目标。发行读取定义与运行闭包。构建将普通 JS 依赖打入产物,保留共享 React;检查要求相对导入都进入 files,服务入口可使用 node:。定义入口使用同步纯数据回调;需要延迟导入的宿主保留定义句柄直到消费结束。

plugin.config.json 可用 include 列出许可说明和静态资产文件,用 nativeSources: [{target,arch,source}] 构建原生入口。Windows 示例分别生成 x64 与 arm64 的 createPlatformProvider(context);原生依赖使用包内相对路径,并列入同一清单文件闭包。

资源提供者的 files 入参是源目录中的可用文件;inspect 返回入口及实际依赖集合。单文件格式返回 [rootFile],资源组按入口中的引用收集文件,宿主只复制返回的集合。

贡献与消费者

贡献主要接口消费者与结果
documentschema/fields/initial/collectReferences/rewriteReferences;可提供 validate/convert/stateVersion/configMappingM02 创建、编辑、复制、删除;M03 编译配置;备份与发布读取同一定义
toollocations/scope/applicable/runM01 按选区显示入口,执行并呈现报告、编辑提案、任务或候选
fieldEditorcontributionKey/fieldKey/mountM01 在同插件公开文档或指令字段挂载;commit 经宿主提交
command / conditionspec/execute/resume、fields/evaluateM03 表单和脚本同源;M05 执行与恢复
system进度、长期 schema、初值、转换、合并和检查点M05/M07 按插件 ID 持有状态;同包提供一个权威定义
page / componentrender、schema、字段、样例、公开部件、状态绑定M08 配置与预览;M07 在 Player 渲染并返回动作结果
resource / stage服务入口的 inspect(rootFile,files,source?)、运行入口的舞台实例 update/set/capture/pause/disposeM04 解析文件与能力;M06 通过 resourceProviderKey 匹配舞台并调度;M11 打包同一资源集合
generationProvider用途、配置字段、输入输出 schema、能力、createM10 冻结提供者贡献键、精确包版本、配置及能力,管理任务与候选
resourceProcessor输入输出类别、取消能力、字段、processM04 提供受控源读取,验证产物与派生来源,保留原件
platform具名动作、目标、必需/替代策略、invokeM05/M07 调用;Windows 原生入口按目标和架构加载
publishCheckcheck({snapshot,lock,target,settings},signal?)M11 在本次固定快照上汇总 Issue;检查报告问题

PluginDefinition.messages 以语言代码映射贡献命名空间的文字键。字段可使用 labelKey/descriptionKey;显示名使用 titleKey。宿主按当前语言、中文和文字键回退。通用表单调用共享 validatePluginData(schema,data),插件可提供更具体的 DocumentContribution.validate。JSON schema 使用内联属性、类型、枚举、常量、数值/长度范围、数组项和必要字段;外部 $ref 给出诊断。

作者上下文与采用

StudioPluginContext.scope 读取页面、场景、文档、语句、文本范围、素材、插入位置及文档版本,并返回可释放的订阅。navigation 打开公开核心页面或定位 Source。documents 提供查询和事务;semantic/assets/production/playerUi 由所属模块提供。宿主未提供某项服务时,插件检查可选属性并显示相应前置条件。

工具在 PluginContext.studio 获取作者服务,在 scope 获取启动时范围,保留原基准版本。工具返回 PluginToolResult:report、edit、task、candidate 或 none;旧 EditInput|null 仍可用。宿主审阅编辑提案,再由 M02 应用并产生回执。统一保存确认已写入磁盘。取消和版本冲突保留已完成结果及原内容。

插件文档可提供 configMapping: {purpose,mode,required}。M03 按插件 ID 生成 PluginRuntimeConfig,documents 的每项保留贡献键、文档身份、版本、用途和数据。多实例由该数组表示。插件自行决定如何读取这些具名配置;配置必需性和固定实例声明进入编译诊断。

旧扁平配置优先读取 plugins/<pluginId>/documents/config.json,没有该路径时读取 plugins/<pluginId>/config.json。官方插件与普通安装包使用同一公开定义参与作者表单、组件目录和试玩。

字段中的 asset 引用选择素材活动版本,variant 引用固定版本。通用表单列出已存版本;编译、发行、备份和运行解析保留该选择。组件在 FieldSpec 中声明引用,嵌套及数组字段沿同一定义收集和复制重写;普通文字不参与身份改写。插件文档使用自己的 collectReferences/rewriteReferences。固定版本缺失时,所属操作返回定位诊断。

生命周期、任务和恢复

activate 注册贡献;deactivate 释放界面、监听和活动资源。Node 插件可调用 context.onDispose 登记释放函数。异步操作接收取消信号。每次装载复制整个清单文件图到可替换包目录之外,使相对导入绑定该次产物;准备失败保留上次有效贡献。同版本安装和开发重载保留活动旧租约,旧会话消费结束后释放旧图。

页面与组件的每次渲染分别提供 signal/onDispose。插件用该渲染范围释放监听、定时器和临时句柄;卸载失败通过 PLUGIN_DISPOSE 诊断报告,宿主继续释放其余资源。

生成提供者分别声明查询、产物重取、逐任务取消和续接。M10 使用原精确服务包和配置恢复旧任务;无法确认远端状态时返回 unknown,作者决定是否发新请求。取消区分本地停止和远端结果。凭据通过 context.credentials.read(id) 在所属 Node 服务边界读取,不写入贡献定义或包。

生成提供者的 inputSchema 校验完整 PluginGenerationInput。outputSchema 校验输出事件的数据 {artifacts,usage};流式 textDelta 由 M10 累计并保存为文本产物。

页面通过 wait.restorable 声明等待恢复,wait.cancel 决定关闭时继续或保持等待。状态和页面恢复由宿主管理执行令牌。进度、长期资料和配置分别声明转换;转换失败保留原状态和原包。

检查和目标验证

build 和 check 验证清单、字段与 schema、声明和实现、单一状态定义以及逐环境依赖图。pack 在检查成功后生成普通安装包。激活期间只注册贡献;服务调用由实际消费者触发。

运行包结构、类型与装载检查后,在 Studio 试用插件提供的选区、审阅、撤销、保存重开和取消操作。提供生成服务时检查任务与候选;提供运行能力时,在声明的发行目标运行对应页面、组件、素材或平台功能。

素材编辑器、缩略图与预览

在类型定义中关联 editorKey/previewKey/thumbnailKey,在清单声明对应 assetEditor/assetPreview/assetThumbnail,再由 editor 入口返回 assetEditors/assetPreviews/assetThumbnails。类型键、关联键和实现均属于同一个插件;Studio 按作品精确锁装载。专属区域共用宿主管理的通用属性与保存,不替换整个 Inspector。

AssetEditorContext.target.kind 区分素材、指令和实例;resource 给出当前素材及实际变体。素材数据通过 commit(value) 提交 M04/M02,指令和实例由宿主注入所属字段的提交。readonly 或 signal.aborted 时停止提交。类型的 filterFields 只能引用已声明的字符串、数字或布尔字段,目录与选择器按活动版本的值精确匹配。

AssetPreviewContext 包含素材或候选身份、精确变体、只读根与文件清单,使用 resource.read(path) 读取声明文件。专属数据以 variant.typeData.value 为准。预览返回释放函数,异步预览可返回其 Promise;在等待前取得的资源用 onDispose 登记。检查取消信号并释放画布、媒体、监听与动画循环,关闭和重载后不继续提交或占用资源。custom-asset 是普通外部包样例,完整 Live2D 外置运行时规则见其插件说明。

类型化制作操作

在无 DOM definition 的 productionOperations 声明命名空间操作 ID、独立业务版本、字段/schema、类型化输入输出端口、MIME 与采用用途,并关联同插件的生成提供者。类型和操作定义使用 contractVersion: 1;旧文档、索引、快照、任务、候选、草稿与配方外壳继续使用 schemaVersion 1。新记录按需保存严格校验的 typeData 或 operationSnapshot,旧记录打开时沿原映射读取并保留,不自动写回或 POST。

通用制作表单按每个媒体输入端口的 type/mimeTypes/required/multiple 提供选择、替换、追加和逐项移除;提交引用携带所属 port,修改某个端口时保留其他端口。公开 fieldEditor 为可选贡献,可覆盖该操作的输入界面;没有专用编辑器的操作直接使用通用字段和媒体端口。专用控件通过 ProductionFieldEditorContext.commit 提交参数和参考媒体,由 M10 检查草稿修订、保存并使旧发送计划失效,不产生作品修改。作者使用流程见AI 制作帮助;持有源码的开发者可查看 plugins/development-examples/video-generation/README.md 的实际视频协议样例。

已准备的外部 SDK

需要外部 SDK 的插件在 manifest 2 的 externalRuntimeDependencies 声明命名空间能力键。可选 context.runtimeDependencies.resolve(key) 返回已经由宿主核对的 {url,expected};load(key) 由宿主装载该入口,返回相同数据及 module。未声明或未准备的键返回诊断。插件检查实际模块接口和期望版本,再创建自身业务实例;静态插件图继续闭合,外部文件与许可由所属运行时清单管理。

Studio 的相应服务还返回 release()。预览先用 onDispose 登记租约,再等待后续资源;关闭期间迟到的结果仍须释放。舞台的可选 assets.readText/readBytes(resource,path) 只读取已解析资源组声明的文件,Node 解析服务使用 PluginResourceSource.readText/readBytes。宿主未提供端口时显示可恢复的前置条件,不自行猜测磁盘位置或切换其他版本。

Live2D 官方包分别提供无 DOM definition、Node services、runtime 舞台与 editor。Core 保持外置,模型业务由普通精确插件提供。其声明的 builtinKind/resourceProviderAliases 读取既有模型身份;作品打开时不生成新信封或修改锁。模型参数读取可调用可选 studio.assets.inspect(assetId),由 M04 检查当前活动版本并经 M02 更新能力事实;固定引用保持原版本。实际操作见模型预览。

公开目标构建器与原生平台

目标包在清单声明 targetBuilder 贡献及真实 entry.services,服务激活后提供同键的 targetBuilders。公开契约为 TargetBuilderContribution:describe给出目标、架构、环境、工具、选项schema及入口;detect/prepare处理外置工具链;validate检查冻结选项;build只在M11提供的暂存目录内写原生工程与实际产物,并返回相对入口、handoff和artifacts。进度、取消沿提供的context执行。M11负责保存快照、精确依赖、共同Web运行文件、构建计划和原子提交。

官方Android/iOS包与外部包沿同一公开端口安装和选择精确身份。作者构建器在目标构建目录声明;作品 Player 的运行插件写入作品精确依赖 Lock,素材与运行插件分别声明所选目标支持。SDK与完整工具缓存留在作者选择的位置。实现范例见官方目标包README及源码。

Windows原生平台入口导出 createPlatformProvider(context)。上下文的 projectPlatform 来自保存的作品平台配置,runtime提供真实发行目录和可执行宿主;提供方负责初始化、调用、事件与dispose。原生文件按实际Player架构装配。Steam0.1.0使用steamworks.js0.4.0的Windows x64文件,真实账号结果另行验证。

编曲音色与执行图贡献

制作操作可以声明 presets: [{id, name, description, defaults}],其中 id 使用稳定合法身份,defaults 使用操作声明的字段并支持结构化 JSON。M10 把已启用精确插件的预设加入现有方案库,提供只读使用、复制到个人/作品和导出;复制保留操作快照及完整起稿。作者在制作工位选择个人连接、参考媒体和采用目标。保存或使用预设只准备草稿,执行由后续审阅提交触发。

制作操作通过公开 definition 的 fields、references、provider 和采用声明接入。操作可以贡献数据化 workflow 模板,作者在连接中检查并选用;宿主读取真实贡献,不按插件身份拼装业务。语音专用输入保存在制作草稿,角色音色通过 M02 的角色事务提交。

本机编曲包通过声明的 soundbanks 能力访问音色目录。服务上下文只提供只读查询/解析,Studio 编辑器通过所属宿主接口明确安装或导入。普通精确插件包同时携带各环境所需产物;Player 发行闭包使用所采用的音频成品和公开运行契约。