入门与设置 / DAYU TOOLBOX 5.0
普通接入
用完整三个文件接入按钮、参数、下拉框和同步计算。
适用于普通按钮、参数编辑和同步计算。已有复杂业务仍需保留原算法,不应替换成下面的演示计算。
Windows 文档/
DAYUCG/大鱼工具箱/自定义插件/插件包/
我的插件/
plugin.json 插件身份、参数、控件和命令
placement.json 用户选择的分类与排序
main.ms 作者实现的功能
Windows“文档”可能被系统或 OneDrive 重定向,以系统的实际“文档”文件夹为准。插件目录应直接放在 自定义插件/插件包 下。
接入前先确定这几件事
| 情况 | 使用已有合同 |
|---|---|
| 一份脚本提供多个卷展 | 同一个模块 ID,被多个卷展的命令引用;不要为同一文件声明多个独立模块 |
| 共享纯函数或普通 DLL | 声明 libraries 和依赖;库没有业务模块的 Initialize/Stop 生命周期 |
| 仅打开分类、搜索或编辑布局 | 读取声明即可,不在扫描配置时 fileIn、构造业务对象或执行场景命令 |
| 持久参数、临时选区 | 参数明确声明 user/view/scene 范围;节点引用和场景快照不混入跨场景缓存 |
| 命令改动场景 | 正确声明 effect 与 undo,由确定的一个所有者提交或回滚;不以 query 绕过事务 |
| 普通参数错误、取消、部分修改失败 | 通过公开错误合同返回;仅确实未产生副作用时使用 FailBeforeEffects,完成自身回滚后才使用 FailAfterRollback;通用 catch 使用 Fail,框架恢复界面不会重放命令 |
| 被动列表或场景同步 | 可见时补齐数据,隐藏/关闭/Stop 清理观察器;用户已经启动的任务另按任务生命周期管理 |
配置扫描会校验元数据而不执行代码;首次实际加载前仍复查配置、依赖与代码身份。2026-11-07 的优化只复用同一次扫描中已校验的不可变配置,不建立跨扫描或跨更新的永久缓存。公开 Schema 与 MS 接口版本未因此改变。普通同步插件无需实现任务队列、额外授权会话或第二套 UI 格式;复杂能力见复杂接入。
脚本类型与宿主运行时不要混用
modules[].runtime 表示模块的实现类型,MAXScript 填 "maxscript"。可选的 host_targets[].runtimes 表示宿主的 .NET 运行时,允许 "net48"、"net8"、"net10",不能填 "maxscript"。例如仅针对 Max 2026:
"host_targets": [{"product":"3dsmax","minimum_release":2026,"maximum_release":2026,"runtimes":["net8"],"architecture":"x64"}]
Max 2024 使用 net48,Max 2025–2026 使用 net8,Max 2027 使用 net10。普通 MAXScript 可以直接在命令内调用自身的公开 MaxScript API,例如 selection.count;不需要为了读取选区数量编造框架服务。扫描或模块加载阶段不执行这些业务操作。
1. 分类与排序:placement.json
{
// 放到哪个分类:可填已有分类名称,或填写新分类名称。
"category":"自定",
// 排第几个:数字越小越靠前,不要求连续编号。
"order":10
}
数字越小越靠前。相同序号仍按稳定身份排序,不依赖文件夹枚举顺序。普通用户通常只修改这个文件。
2. 参数和界面:plugin.json
下面是完整的纯数值相加示例。它不修改场景,也不演示长度/面积单位。创建新插件时更换唯一 plugin_id;不要占用官方保留的 dayu.* 或 cn.dayu.*。
{
// 1. 插件身份:schema_version 不随意修改;plugin_id 发布后保持稳定。
"schema_version":"1.0.0",
"plugin_id":"org.example.simple_sum",
"version":"1.0.0",
"title":"数值相加示例",
// 2. 功能入口:界面与业务分开;main.ms 实现下方命令。
"modules":[{"id":"main","runtime":"maxscript","entry":"main.ms"}],
// 3. 参数:默认值、范围、显示精度和保存方式。
"fields":[
{"id":"a","type":"number","default":1,"minimum":0,"maximum":100,"step":1,"precision":0,"dimension":"scalar","canonical_unit":"none","display_unit":"none","persistence":"view"},
{"id":"b","type":"number","default":2,"minimum":0,"maximum":100,"step":1,"precision":0,"dimension":"scalar","canonical_unit":"none","display_unit":"none","persistence":"view"},
{"id":"total","type":"number","default":3,"minimum":0,"maximum":200,"step":1,"precision":0,"dimension":"scalar","canonical_unit":"none","display_unit":"none","persistence":"view"}
],
// 4. 命令:按钮通过稳定 ID 绑定,不能仅靠显示文字寻找功能。
"commands":[
{"id":"sum.calculate","module":"main","export":"Calculate","effect":"query","concurrency":"reject","undo":"none","args":{"a":{"field":"a"},"b":{"field":"b"}}}
],
// 5. 界面:每项是一个卷展;布局顺序和显示文字在这里修改。
"panels":[{
"id":"sum","title":"数值相加","activation":"on_command","expanded":true,
"layout":["a.editor","b.editor","total.editor","calculate"],
// 6. 教程:有演示视频时改为 {"kind":"url","url":"真实的HTTPS视频地址"}。
// 每个卷展可填写自己的链接;没有视频时保留文字教程或省略 tutorial。
"tutorial":{"kind":"inline","text":"输入两个数值后计算。此示例不修改 Max 场景。"},
"controls":[
{"id":"a.editor","type":"number","label":"数值 A","bind":"a"},
{"id":"b.editor","type":"number","label":"数值 B","bind":"b"},
{"id":"total.editor","type":"number","label":"结果","bind":"total"},
{"id":"calculate","type":"button","label":"计算","command":"sum.calculate"}
]
}]
}
precision 只控制显示位数,不把业务值变成整数。数量、索引等真正的整数字段还须声明 value_kind:"integer"。
plugin.json 和 placement.json 支持 // 单行注释 与 /* 多行注释 */,文件名不变。注释用于说明用途、单位、允许值和修改影响,不作为可执行配置。字符串内的 https://、// 或 /* */ 原样保留。仍须使用双引号和正确逗号,不支持尾随逗号、重复字段或未知属性;不要自行增加 _comment 字段。编辑器可选择“JSON with Comments”语言模式。已有纯 JSON 文件继续兼容。
统一书写规范:使用 UTF-8、两空格缩进,按“身份 → 模块 → 参数 → 命令 → 卷展/布局/教程”分区。每个参数旁注明用途、单位、默认值和范围;每个命令注明修改场景或文件的影响。中文名称和提示可以修改,已有 id、bind、command、export 是关联标识,不能只改其中一个。注释随源配置保存;框架只在内存中去除注释并生成渲染数据,不回写作者文件。配置或脚本改变后重启 Max 再检查;已发布官方包仍按真实文件字节校验完整性。
无参数的按钮也必须声明 "args": {},不能省略。1.0.0 使用内联 args;1.1.0 可以使用 args_ref,两者只选一个。校验完整 Schema 时要包含 oneOf、allOf 等条件,不能只检查局部 required 列表。
3. 功能实现:main.ms
(
fn executeMyTool sender args =
(
case args.Request.Export of
(
"Calculate":
(
args.SetNumber "total" ((args.Number "a") + (args.Number "b"))
args.Message "计算完成。"
)
default: throw "未知命令。"
)
)
local module = dotNetObject "Dayu.Toolbox.PluginContract.Authoring.AuthorScriptModule"
dotNet.addEventHandler module "Executing" executeMyTool
module
)
框架先加载公共接口,然后读取 main.ms 的最后返回值。不要独立拖入这个文件试图打开窗口,也不要再写 createDialog。fileIn 阶段只返回模块,实际操作在命令中执行。
args.Number 读取清单映射的参数名;SetNumber 返回字段更新;Message 交给框架统一显示。没有字段或消息结果的成功命令可用 args.Success()。使用这些简化方法时,不要在同一次调用另设完整的 args.Result。
没有资源的普通模块只接 Executing 即可。开始接入场景修改、撤销、拾取或动态列表时转到复杂接入,不能继续把所有动作标成 query。
图库与缓存目录
需要用户选择图库或缓存目录时,在 plugin.json 顶层声明 directories,不要在每个卷展重复放路径输入框。设置页从声明读取目录,不执行子脚本;用户点击应用后,框架将路径保存到同一个 user 字段,并更新当前会话。
"directories": [
{
"id": "door.library", // 包内稳定目录标识;改标题时保持此标识
"title": "门图库", // 设置页显示名称
"group": "建模图库", // 设置页分组
"field": "door.root", // fields 中的单行 text,persistence 为 user
"default_subdirectory": "资源库/门", // 相对于 Windows 实际文档/DAYUCG/大鱼工具箱;禁止绝对路径或 ..
"kind": "library", // library 图库,cache 缓存
"description": "保存门模型及其预览图;更改目录不会搬动旧文件。"
}
]
door.root 可以默认空字符串,已有非空自定义路径优先。目录字段不得绑定 change_command 或 edit_command,目录设置不调用业务来保存配置。业务读取同一字段,空值时使用声明对应的默认目录;在需要切换已打开的文件或后台任务时,业务必须保证这些资源仍归属原任务,必要时在 description 说明下次打开生效。框架不会迁移、复制或清理目录中的文件。
卷展需要快捷入口时,使用已有 shell@1 服务的 ShowDirectorySettings("door.library")。只能定位本包声明的目录;这会打开统一设置页,不会再出现第二套目录选择状态。
主操作旁放取消按钮
“检查参数 [×] 保存资产”可用 split_action 标准行,三项依次为主操作、取消、另一操作,全部使用已有 button 控件和各自命令:
// 放在面板 layout 中;三个 ID 都必须已在该面板 controls 中声明。
{"type":"row","template":"split_action","items":["inspect","cancel_preview","store"]}
取消控件配置示例:{"id":"cancel_preview","type":"button","label":"×","help":"取消预览","command":"cancel_preview"}。左半行内主按钮与 22 个逻辑像素的取消按钮贴合,右半行放另一按钮。三个按钮分别命中、启用、触发命令;框架不会把取消行为附着到主按钮,也不会推断如何撤销业务预览。作者提供取消命令即可。此模板要求渲染器能力 layout.split_action,缺少能力时在加载业务前明确拒绝。
普通显式行也可把数值与其相关开关放一起,例如 {"type":"row","items":["band","front"]}。范围输入保留完整数值、正常水平滚动与完整值悬停,不因最大值很长挤出第二行;无需缩短“范围”“反转正面”等标签。
数值步长与拖动
毫米尺寸统一使用1 mm基础步长,包括缝隙和切角。字段采用其他单位时,step填写换算后对应的值;例如规范单位是米,则1 mm步长写0.001。角度、倍率和数量保留各自单位,不把所有数字都当作毫米。precision决定显示的小数位数,不会限制数值只能是整数;数量、分段请另写"value_kind":"integer"。
框架自动提供右侧箭头单击、长按连调和左键上下拖动。拖远加速、反向恢复细速;Shift精调,Ctrl快调,Esc取消。数字正文仍可选字编辑,中键仍用于滚动。作者无需增加拖动事件或定时器。
普通场景change_command在松手时执行一次;纯字段和effect:"viewport"的临时预览会限频实时更新,取消时恢复原值。若确实需要实时改变场景并合并为一次撤销,使用复杂接入中的edit_command连续编辑合同,不要把场景修改伪装成viewport。本能力由框架协商number.gestures,旧框架缺少能力时会在业务加载前提示不支持,不会静默忽略。
数值输入一致性
数值框只呈现数字;框架悬停提示负责完整值、单位和步长,不要在脚本中拼接 mm 后缀。长度声明使用 dimension: "length"、canonical_unit: "mm"、display_unit: "mm",持久值按毫米,显示由用户的框架单位偏好决定;业务调用 Max 几何 API 时才转换为系统世界单位。角度、百分比、数量、像素以及固定光学毫米焦距应保留各自原有计量方式。标记的固定屏幕尺寸是普通数值,不能声明为长度。
模块与共用库
libraries 的每项声明 id、runtime、entry 和交付文件的 sha256;模块通过 libraries 引用它。调用者与所引用库须使用同一 runtime,依赖不得成环。同一个入口文件不能同时作为模块和库。普通库没有模块的 Initialize/Stop 生命周期,不要为库补造业务模块。MAXScript 模块不能把 dotnet 库当作 maxscript 库引用;需要混合实现时先按公开合同划分模块和桥接边界。