GalCraft插件SDK
这个 galcraft-plugin development CLI支持Node.js 22.12.0及以上版本。为独立的插件项目使用最新的Node.js 24 LTS补丁；源代码开发和CI使用Node.js 24.21.0和pnpm 12.3.4。生成的Node服务和本地条目目标Node.js 22.12；浏览器条目保留其浏览器目标。契约和可选的DSL解析器导出也为浏览器消费者提供服务，并且不需要在这些消费者中使用Node运行时。插件作者从npm安装准确的SDK版本： npm install @galcraft/[email protected] @galcraft/[email protected]． 解析器使用者还安装 @galcraft/[email protected].
SDK导出插件契约 @galcraft/plugins/contracts，主机共享的React实例在 @galcraft/plugins/react，主机共享的Pixi名称空间在 @galcraft/plugins/pixi，以及创作工具 @galcraft/plugins/development． 插件使用这些公共导出；主机程序集使用 @galcraft/plugins/host 和 @galcraft/plugins/registry.
galcraft-plugin create <directory> <pluginId> <template> 创建一个独立的TypeScript项目。模板是 author-tool， game-system， resource-stage， service-provider, complete． 安装合同和插件 npm install @galcraft/[email protected] @galcraft/[email protected]，然后跑 npm run typecheck， npm run build， npm run check, npm run pack． 包目录支持Studio开发加载； .galplugin 文件支持普通安装程序。
清单v1仍然受支持。Manifest v2需要一个无dom的定义条目，并支持单独的编辑器、Node服务和运行时条目以及环境依赖项。主机与声明的引擎范围一起检查SDK major 0。当前本地开发的引擎、插件和SDK包版本保持在0.1.0；示例插件声明 ^0.1.0． 普通安装可以刷新相同的包版本，活动租约在可替换包目录之外保留完整的图，直到发布。精确的项目锁对包版本保持权威，包括版本缺失诊断。插件状态对每个插件使用一个系统贡献。
包版本不能替代清单版本， contractVersion: 1或独立的类型、操作和状态数据版本。现有的文档、资产索引、快照、任务、候选、草稿和配方信封保留在schemaVersion 1中。旧的记录保留其原始的读映射；打开它们不会写入扩展字段或提交生成请求。
清单 name 和 description 包含作者的原始文本。可选 localizations 将区域设置键映射为complete { name, description } 比如翻译 localizations.en 和 localizations.ja． Studio使用当前界面区域设置解析显示文本，然后是其语言，然后是源文本。 pluginDisplayMetadata(manifest, locale) 通过以下方式公开此规则 @galcraft/plugins/contracts． 显示文本不会更改包id、版本或项目锁。
SDK发行版包括契约和插件包构件，以及可选的DSL解析器构件，用于编写读取《GalCraft》语句的插件 @galcraft/dsl/parser． 分发命令构建并打包这些构件；普通插件安装契约/插件，而解析器使用者也安装匹配的DSL工件。构建捆绑普通依赖项，保留主机共享的React条目，并为每个执行环境验证ESM图。在测量清单文件大小之前，构建将从每个环境中生成的JavaScript语法（包括本地条目）中删除尾随空格和制表符。 通过复制的文字内容和文件 include 保留其原始字节。服务可以使用 node: 进口。定义项包含同步数据回调，并且独立于UI和服务执行。
参见存储库开发人员指南 docs/reference/plugins.md 对于生命周期、文档映射、服务和接受边界。GalCraft SDK代码采用了mpls -2.0。分布式SDK包带有许可证和源代码可用性通知 dist/licenses/project/． 开发构建器收集插件项目自己的许可证，复制，通知和 licenses/ 文件加上捆绑的依赖项许可证报告；它保留了作者声明的许可。新项目从“未授权”开始，直到其作者选择条款。读 LICENSING.md 在项目材料范围的源代码树中。
资产UI扩展使用 AssetEditorContribution， AssetPreviewContribution, AssetThumbnailContribution 从合同出口。类型描述符关联 editorKey， previewKey, thumbnailKey 具有匹配的清单声明和编辑器贡献。编辑器目标区分资产元数据、命令字段和阶段实例；只通过上下文回调提交。上下文还公开所选资源/版本和只读标志。
预览上下文标识一个已索引的资产或未采用的候选资产，携带其确切的变体/typeData和只读资源集合，并提供 signal 加上 onDispose． 挂载可能返回同步清理或清理承诺。将等待操作之前获得的资源注册为 onDispose;检查 signal 在附加异步结果之前。Studio隔离每个挂载，并在切换、停用、重新加载和关闭时释放旧范围。外部 custom-asset 示例演示了真实的顶点/颜色编辑，静态预览，缩略图，正式引用和精确的标量 filterFields 声明。
类型化的生产操作在无dom的定义中声明它们的字段和媒体端口。主机为每个端口的类型、MIME、所需规则和多个规则提供通用控制，包括选择、替换和单独删除，同时保留其他端口。一个公共 fieldEditor 是可选的;它的提交回调更新个人M10草案，检查其修订并使先前的发送计划无效。它不提交M02工作编辑。看到 plugins/development-examples/video-generation/README.md 对于本地视频协议的示例及其验证限制。