SuperAPI AI 工具集

blockbench-plugins

编程与开发

查看项目

更新于 10-15 12:14

技能介绍

用途

本技能用于 Blockbench 插件/扩展的开发。Blockbench 是一款 3D 建模工具,可运行在桌面端和网页端,并向插件暴露宿主 API 以及内置的渲染/UI 库。适用于为 Blockbench 创建、修改或调试 JavaScript 插件的场景。

在开始前,应先确认目标宿主版本及其类型定义再选择 API;插件变量隔离并不代表可以无限制访问原生模块或文件系统。当旧版 wiki 示例与宿主行为冲突时,应以当前生成的 API 参考和目标检出为准。variant 与 min_version 应设置为实际验证过的环境。

主要能力

  • 插件注册与生命周期:通过 Plugin.register() 注册插件,提供 onload、onunload、oninstall 等回调。
  • Action:可点击命令,可加入菜单、工具栏和快捷键。资料还提到 Toggle(开关状态)与 Tool(视口交互)两种变体。
  • Dialog:表单对话框,支持 text、number、checkbox、select、color 等字段以及条件字段。
  • Panel:侧边栏面板,使用 Vue 组件,可指定默认位置(left_bar、right_bar、bottom)。
  • 模型操作:使用 Undo.initEdit() → 修改 → Undo.finishEdit() 的流程进行可撤销的编辑。
  • 元素创建:Cube(立方体)、Group(骨骼/组)、Texture(纹理)等,并记录到 Undo 事务中。
  • 全局集合:Cube、Group、Mesh、Texture、Animation 的 .all / .selected,以及 Outliner.elements。
  • 事件系统:通过 Blockbench.on() 订阅、Blockbench.removeListener() 退订,并给出常见事件列表。
  • 自定义菜单:通过 new Menu([...]) 组合已有 action、自定义项和子菜单。
  • Format 与 Codec:自定义导入/导出格式,实现 compile() 与 parse()。

使用方式

插件目录结构为 plugins/my_plugin/,其中主文件 my_plugin.js 为必需项,且插件 ID 必须与文件名一致;about.md 和 icon.png(48x48)为可选。

注册时通过 Plugin.register('my_plugin', {...}) 填写 title、author、description、icon、version、variant、min_version、tags,并在 onload 中初始化组件、在 onunload 中删除全部组件(资料强调这是防止内存泄漏的关键)。

常用做法包括:用 new Action() 创建命令并通过 MenuBar.addAction() 加入菜单;用 new Dialog() 创建表单;用 new Panel() 创建带 Vue 组件模板的面板;修改模型时先用 Undo.initEdit() 开始追踪,修改后调用 Canvas.updateView() 更新视图,再用 Undo.finishEdit() 提交。创建元素时需要在事务完成时记录新对象。

自定义格式需实现 Codec 的 compile()(模型→文件内容)和 parse()(文件内容→模型),并配合 ModelFormat 声明 box_uv、bone_rig、animation_mode 等能力。

条件判断支持函数形式,也支持 { formats, modes, project, selected, method } 对象形式(按 AND 组合)。

代码风格约定:类名 PascalCase,方法 camelCase,属性 snake_case,事件/Action ID 为 snake_case。

TypeScript 支持:npm i --save-dev blockbench-types,并使用 /// <reference types="blockbench-types" />。

内置库(不应打包):THREE、Vue、JSZip、marked、Molang。

图标支持 Material 图标、Font Awesome、Blockbench 自定义以及 Base64 图片。

适用场景与限制

本技能适用于为 Blockbench 开发插件、扩展菜单/面板/对话框、实现自定义模型格式的导入导出,以及带撤销的模型编辑逻辑。

资料明确列出的反模式包括:不保存引用导致内存泄漏、不使用 Undo 导致用户无法撤销、重复打包 THREE.js(已是全局可用)、以及污染全局(如 window.myData = {})。

资料强调:格式功能标志只是声明宿主行为,并不等于在自定义 codec 中实现了缺失的校验或运行时序列化;组的 origin 是枢轴,父子关系不会把该 origin 作为平移加到立方体边界上;原生 action 或绘制 API 可能自带事务,不应再添加嵌套的竞争事务。

验证建议:用代表性项目验证插件改动——检查预期数据/预览、执行 Undo 后 Redo,以及卸载/重载后的清理;对于格式/codec,应检查一次代表性的导出与重新导入,包括 UV 尺寸、层级、名称、纹理引用,以及支持情况下的动画行为。编译通过并不代表验证了原生编辑器状态或序列化输出。

关于本技能的收费、价格或具体平台支持范围,资料暂未提供。