用途
本技能用于 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 尺寸、层级、名称、纹理引用,以及支持情况下的动画行为。编译通过并不代表验证了原生编辑器状态或序列化输出。
关于本技能的收费、价格或具体平台支持范围,资料暂未提供。