入门与设置 / DAYU TOOLBOX 5.0
复杂接入
处理动态列表、拾取、连续编辑、后台任务和状态释放。
复杂功能不需要框架项目或官方插件源码,也不使用另一套插件格式。在基础三文件上增加声明的资源、模块或公共服务;只引入实际需要的能力。
精确字段结构见插件声明结构,类型、参数和返回值见公共接口,可请求的服务见公共能力。不得通过猜测方法名调用私有实现。
| 功能 | 接入方式 | 必须保留的语义 |
|---|---|---|
| 参数改变后自动联动 | 字段 change_command,返回 typed 字段更新 |
一次结果统一验证,多处控件共享同一字段 |
| 拖动数值、曲线、颜色并实时预览 | 字段 edit_command,与 change_command 二选一 |
预览/提交/取消;绝对值设置,不能每帧累加;场景编辑只有一次撤销 |
| 展开卷展时刷新内容 | 面板 prepare_command |
同步只读准备;不要在展开查询中修改场景 |
| 列表、表格、树和预览图库 | 声明数据来源;用 SetSource 发布带稳定 ID 的快照 |
选择与右击目标分开;排序、过滤、分页后仍按 ID 对应 |
| 多个动态参数组 | 模板和实例状态 | 有界实例数量,字段身份稳定,删除时清理所属状态 |
| 操作选择和场景对象 | 请求已实现的宿主服务,声明实际场景效果与撤销方式 | 对象存活、场景代次、取消与失败,不能以 query 隐瞒修改 |
| 选点、选对象、材质或贴图 | 公共宿主交互服务 | 使用当前会话的引用;完成、取消、关闭均释放资源 |
| 后台任务与进度 | 公共异步命令服务 | 后台不访问 Max/UI;回到拥有者线程提交,过期结果不能覆盖新状态 |
| 持久参数与配置升级 | 声明持久范围及状态版本,按需增加迁移 | 用户配置不清空;临时对象句柄/材质引用不能当作重启后身份 |
| 计时器与订阅 | 公共 timer、事件及生命周期服务 | 所有者关闭时释放;失败停止须保留可重试状态 |
| 图片和外部文件 | 声明资源,使用受约束资源/文件服务 | 不写入安装目录;不把任意绝对文件地址伪装成资源 URI |
初始化与停止
需要服务时,在模块 Initializing 事件获取 args.Environment.Services,按公共能力名称和版本获取已声明服务。Stopping 负责释放作者持有的资源。基础模块无需为了形式完整而添加空回调。
服务不存在时明确报错或使用文档允许的可选回退,不使用反射去找框架私有实现。场景修改只发生在拥有者线程。Stop 不等于在当前 Max 进程中卸载 CLR DLL;更新 DLL 后重启 Max。
MS 事件处理中捕获错误后,用 args.Fail "script_error" (getCurrentException()) 返回失败;不要用 Message 或 Success 代替失败。失败会丢弃本次尚未提交的字段/数据源输出,并保留具体错误供界面和侦听器查看。初始化失败也使用对应事件参数的 Fail。
数据与 UI
字段定义业务值,控件只是该值的视图。每次结果只能选择简化 args.Set* 方式或完整 AuthorResultBuilder / args.Result 方式之一。动态数据源及选择应在同一次结果中保持一致。
number 的规范单位和显示单位分开;color 是界面 RGB,不等于场景线性色。color4 保留 HDR/透明度。持久值范围为 view/user/scene/transient;会话资源 token 和宿主引用不得跨重启保存。
命令的 async: true 只支持实现 IAuthorAsyncModule 的 dotnet 模块,不能直接给 MAXScript 命令加 async。PrepareCommand 与 CompleteCommand 在拥有者 GUI 线程执行,worker 只处理纯数据,不访问 Max、MAXScript 或 Qt 对象。同步命令只能使用 concurrency: "reject";replace 仅用于异步 query;queue 必须声明 1–32 的 queue_limit。场景撤销不跨 worker 阶段。
change_command 必须指向已声明的同步命令,其 args 或 args_ref 必须包含本字段映射。回调按映射后的参数名读取候选值,不会自动收到全部字段;结果验证通过后统一提交。edit_command 同样须接收本字段,仅支持 number/curve/color4 的同步 query/scene 命令,与 change_command 互斥。
MS 与 C#
托管模块的 entry 为包内 DLL 相对路径,factory 为实现 IAuthorModule 的公开非抽象类型全名,并须有公开无参构造函数。仅实现接口但未声明可实例化的 factory 不足以加载。
普通转换优先保留用户自己的 MS 算法。确实使用 C# 时,实现公开 IAuthorModule,并选择安装版本兼容的目标运行时。只引用公开接口,不引用 UI、Workspace 或内部加载器实现;不将框架/Qt DLL 复制进用户插件目录。
Max 2024–2027 的运行时和 Qt 并非完全相同。不能把某一版编译的 DLL 重命名后宣称通用;框架负责宿主适配,作者仍须声明和验证自身业务依赖的 Max 功能范围。
普通 MS 模块使用同一套公共声明,无需为 Qt 单独开发。C# 模块的 modules[].runtime 写 dotnet,MS 写 maxscript。宿主兼容范围使用 host_targets[].runtimes 的 net48、net8、net10:分别对应 Max 2024、2025–2026、2027。它只是兼容声明,不会自动切换 DLL;按当前合同提供匹配的程序集/包,不在清单中发明按版本自动选择入口。不要把依赖随意装进 Max 主目录。
关键规则编译与升级(2026-10-26)
需要保护或独立维护的任务调度、文件命名、持久化、校验、图像处理等规则,可放入作者自己的 C# 业务程序集;MAXScript 保留 Max API 适配。不要把原脚本文本嵌入 DLL 后再执行,并把它称为算法原生化。只有测量确认的性能热点或 SDK 能力才进一步评估 C++,不因此另建 UI 或使用框架私有类。
编译和混淆只能提高逆向成本,不等于加密或“无法破解”。混淆须保留公共合同、脚本直接调用入口、反射和序列化身份;状态文件字段及稳定命令 ID 不得随内部重命名变化。更新配套 DLL、依赖、脚本桥接和资源清单,明确版本及数据升级办法;已加载程序集须退出宿主后替换,不把重新打开卷展当成 DLL 热更新。
发布只包含明确声明的运行文件与第三方许可,不携带 PDB、测试程序集、缓存、私钥或 Token。凭据使用单独的受保护存储,不写入普通插件配置、任务文件、导出或错误日志。保护构建后的加载、执行、数据重读、失败恢复仍需专项验收;不能只验证未混淆版本。
可继续的文件任务(2026-10-26)
长任务先定义可重复执行的最小单位,并分别记录待执行、运行、成功、失败、停用和后处理状态。任务级继续只跳过已核验完整的结果;当前图片中断后整张重新渲染,不用“断点续渲”暗示恢复渲染器采样。恢复或打开卷展不自动重放失败命令。
保存稳定场景身份及源文件版本,重新开始前核验;不要把只在当前会话有效的临时引用写入恢复文件。输出使用暂存、完整性检查和原子替换;普通取消与移除任务不删除已完成成图或用户场景。默认目录通过公共 directories 声明,已开始的任务固定输出目录/策略,不能半途把结果分散到新位置。
后台可调度文件和外部进程,不能调用 Max 场景 API。切换场景的任务应隔离于用户当前场景,进程控制必须同时核验自有进程 ID 与启动身份;不能按名字结束所有 Max。保存、发布等临界阶段须有明确取消和恢复边界。操作失败、过期选择、队列进程退出后应有停止/重试入口,不留下永久忙状态;场景与输出恢复未经确认时如实说明。
主动任务可在卷展收起后继续,被动列表同步仍遵守下方可见性规则。列表提供明确的暂停、停止、跳过与重试含义;通知、自动保存与关机等扩展默认关闭,关机仅本次启用且可取消。测试通知必须显式触发,不用真实通知或关机作为普通自动检查。
有原生资源或撤销逻辑的迁移
动态生成的预览图片可请求 resources.publish@1,将图片字节交给 IAuthorResourcePublisher.PublishBytes,保存返回的租约并把 Uri 绑定到图片字段。替换图片或停止模块时释放旧租约;需要缩略图时另请求 thumbnails@1。不把用户文件的任意绝对路径直接作为界面资源。
resources.files@1 用于按需读取已有文件:通过 IAuthorFileResourcePublisher.RegisterFile(absolutePath) 注册经校验的普通文件,持有返回的 IAuthorFileResourceLease,用其 Uri 绑定界面。注册不等于已读取完整字节,首次资源需求时读取并缓存。当前单文件须为 1 字节至 4 MiB,最多 16384 项注册;在拥有者线程释放租约会撤销 URI,不删除原文件。文件更新后注册新 URI,不跨资源代次或重启复用旧 URI。这个接口允许外部绝对文件路径,与清单中模块 entry 的包内相对路径规则不同。
变换锁通过 host.transforms@1 的 IAuthorTransformLocks.SetLocked 设置,传入当前场景和有效对象引用,且必须处于声明为 scene 的命令中。
默认场景命令继续用 undo: "single",由框架管理一次撤销;业务不要再次 Begin/Accept/Cancel 同一个外层撤销。原算法完整管理原生撤销、启动由 Max 接管的原生创建工具,或执行会重置撤销历史的场景合并时,声明 undo: "module" 并请求 scene.module-undo@1。命令入口同步返回;原生工具之后的用户交互由 Max 管理,不能把外层框架撤销一直留到用户完成。不要为了通过校验把修改场景的命令标为只读。
2026-10-24 起,执行事件参数提供 args.FailBeforeEffects "code" "说明" 和 args.FailAfterRollback "code" "说明"。前者仅用于确认尚未改变场景的前置检查;后者仅用于模块确实完成自有回滚后。普通未知异常仍用 args.Fail。不能把整个 catch 一律标为安全失败;框架还会检查撤销边界是否干净。
普通拒绝不锁住下一步。真正未知的效果仍如实报告失败,框架先停止本功能的资源,再按当前场景重建会话并保留已提交参数;不会自动重放失败命令,也不会声称现场已回滚。关闭再打开卷展栏会触发恢复重试。其他分类不继承此功能的错误状态;若 Max 仍持有外部原生操作,先结束该操作,框架不能擅自取消它。接入验收须包含“失败后执行有效操作、跨分类继续、关闭重开恢复”,而非只检查成功路径。
交给 AI 的复杂功能验收要求
可见期间的被动同步(2026-10-25)
选区联动、相机列表和目录自动刷新等被动同步,声明 lifecycle.visibility@1。MAXScript 模块在 Initializing 中调用 sender.WatchPanel e.Environment "所属面板ID",预先绑定 PanelChanged 事件。用 e.Kind.ToString() 判断 Shown / Hidden / Closed,不要使用 as string 比较 .NET 枚举。只有 Shown 启动同步;隐藏、折叠、切换分类或关闭工具条时停止并释放计时器,重新显示时补齐当前状态。停止模块时必须清理资源。多个相关面板共用一个计时器,并统计实际可见面板,不能由其中一个面板关闭就停止另一个仍可见面板所需的同步。
手动发起的渲染或文件处理任务不属于被动同步,不因切换分类被自动取消。更新列表应保留稳定 ID,选区变化不要重复生成全部行。动态下拉框最多128项,安装组件较多时先筛选再发布;显示中文名称,保存和执行使用稳定 Class ID。完整脚本加载、实际事件和后续有效操作均需验证,不能只验证抽取的算法函数。
必须列出选择、单击、双击、右击、拖动、滚轮、取消、场景切换及关闭的实际行为;不以“控件名字相似”代替语义转换。原算法不支持的功能、公共接口缺口和未运行的宿主检查分别列明。没有实现的动作不生成成功提示或空按钮。
数据源若需要保留资源编号或修改器栈的原顺序,可声明 preserve_order: true 并省略 sort_field。此时筛选、翻页保持发布顺序;显式排序字段优先。快照中的 ID 仍须稳定,不能用行号替代资源身份。
标准图库由框架提供翻页:滚轮或中键拖动逐行浏览;右击编号、空槽或间隙可临时输入页码,回车跳转,Esc取消,每页六项。图片正文的右击仍执行你声明的辅助动作。无需自行添加页码输入或上一页/下一页按键,也无需实现跳页命令。
MS 创建无图片的列表项时,使用 AuthorSourceItem 的两个字符串参数构造函数;需要详情和角标时使用公开静态方法 WithoutResource(id, label, details, badge)。不要把 undefined 作为 .NET 构造函数的资源 URI 参数传入。