开发概要与最佳实践

开发概要与最佳实践

Resonite 是一款功能强大、选项丰富的引擎。然而，某些方法或习惯可能会带来问题，或者导致你的作品在未来版本中失效。本页面列出了应尽量避免的做法、背后的原因以及建议的替代方案。你可以自由决定是否继续使用这些功能，但需了解其风险。

注意：本页面列出的项目并不违反《用户指南 (Guidelines)》。

尽管如此，我们仍建议尽可能避免使用这些方法。这份列表并非为了指责任何人，而是为了帮助你改进创作，并确保引擎更新或其他用户的操作不会在无意中破坏你的作品。

如果你觉得某种做法像是“歪门邪道（Hacky）”，请向社区或团队咨询。如果你发现了希望解决的问题，请在 GitHub 上提交 Issue。

应对不支持或尚未实现的功能

某些尚未正式实现的功能可以通过修改内部系统和属性来“强行实现（Hack in）”。虽然我们鼓励实验和探索，但请注意，这些方法极有可能在没有预先警告且没有官方替代方案的情况下失效。

这可能导致你的内容损坏且无法修复。因此，我们建议优先寻找基于已支持功能的替代方法。你可以在 GitHub 上为计划中的功能投票，以便我们优先开发。对于官方功能，我们始终将内容的长期兼容性放在首位。

利用 Bug 的行为

如果你遇到了看起来不正常或不像是预期功能的行为，请尽快报告，不要依赖该 Bug 的行为进行创作。一旦 Bug 被修复，你的内容可能会因此“损坏”。Bug 本身是不可靠的，可能只在特定条件下触发。

Slot（插槽）

在 ProtoFlux 或组件中，避免依赖你不拥有或不控制的 Slot 名称或层级结构。这些 Slot 的名称和结构随时可能更改，从而破坏你的逻辑。

1. 用户根节点 (User Root) 的结构

随着新功能的加入，用户根节点下的 Slot 可能会被添加、删除或重新排序。

• 应避免： 使用 Find Child By Name 或通过多次 Get Parent / Get Child 来硬编码定位 Slot。
• 解决方案： 使用专用的 User Root Nodes 或 User Nodes。

2. 虚拟形象 (Avatar) 的结构

虚拟形象是非常复杂的。

• 应避免： 依赖 Find Child By Name 定位形象部位，或假设形象具有固定的层级（例如，头部和手部形象可能没有“Avatar Root”）。
• 解决方案： 使用专用的 Avatar Nodes。

3. 他人世界的结构

当你访问他人的世界时，你是一名客人。

• 应避免：
  • 将道具（如武器弹头）直接生成在世界根节点（Root Slot）。
  • 假设世界的生成点、光照等层级是标准化的。
  • 在 Root Slot 调用 Dynamic Impulses 或放置 Dynamic Variables。
  • 离开时留下垃圾。请确保你的道具（如子弹、粒子）在离开房间时会自动清理（设为非持久性或自动销毁）。
• 解决方案： 使用 Local User Space 节点作为父级，而不是直接指向 Root。

4. Slot 混淆 / “加密”

为了保护作品，你可能会尝试重命名、缩放或移动 Slot 来混淆视听。

• 事实： 对于拥有 Builder 权限的高级用户来说，这种应用内的混淆非常容易被破解。
• 解决方案：
  • 形象请使用 Simple Avatar Protection 组件。
  • 在受保护的世界中，不要随便给不信任的人 Builder 权限。
  • 不要在不信任的人开设的房间中生成敏感物品。

形象 (Avatars)

• 禁用关键组件： 不要禁用形象维持功能所需的关键组件。
• 禁用射线检测 (Raycasts)： 很多玩家为了防止被“击退枪”等道具干扰而禁用形象射线检测，但这会导致正常的交互系统失效。
  • 注意： 未经同意干扰他人形象违反了《用户指南》。请利用房间管理工具或提交违规报告，而不是通过破坏形象功能来防御。

组件 (Components)

• 强制启用自动禁用的组件： 如果一个组件自动禁用，通常意味着其设置或所在的 Slot 有问题。不要强制将其驱动（Drive）为开启状态。
• Ref Hacking（引用黑客）： 通过引用 ID 绕过限制是不可靠的。引用 ID 随时会变，且某些用法可能涉及安全风险或违规。请优先使用 Allocating User 等专用节点。
• 依赖组件顺序： 组件在 Inspector（及轮盘菜单中看到的列表）里的顺序是非确定性的。不要让你的逻辑（如多个 Button 事件）依赖于组件的上下排列顺序。
  • 解决方案： 使用 ProtoFlux Impulse 链，它的执行顺序是绝对确定的。

ProtoFlux

• 对复杂类型使用 ToString： 不要依赖 ToString 节点对用户、Slot、数据类型等的输出结果，这些文本格式随时会更新。请使用对应的 User Root 或 Type 节点。
• 过度使用 Fire On True：
  • 应避免： 监控按钮组件的 IsPressed 布尔值来触发 Impulse。
  • 解决方案： 使用 Button Events 节点，它更高效且功能更全（支持按下、按住、释放等）。
  • 工具： 同样的，RawDataTool 请使用 RawDataTool Events 节点。
• Mono-Packing（节点压缩）： 试图通过插件将所有节点压缩到一个 Slot 里以减少 Slot 计数。
  • 弊端： 这会导致 ProtoFlux 难以阅读、修改，且破坏了引擎未来的自动优化能力。Slot 数量并不直接等于性能损耗。

图形 (Graphics)

• 材质堆叠 (Material Stacking)： 在同一个 Mesh Renderer 里的同一个材质槽添加多个材质。
  • 风险： 这在未来的渲染引擎更新（如 Sauce）中极有可能失效。
  • 替代方案： 在同一位置创建多个 Mesh Renderer，每个使用不同的材质。
• 切换 Shader 的 URL： 手动更换 StaticShader 资源的 URL 以实现视觉效果。
  • 风险： 随着自定义 Shader 功能的上线，这种做法将会失效。

资产 (Assets)

• 使用 .7zbson/json 原始文件： 这种手动提取文件并修改的做法不受官方支持，且极易因文件层级或交叉引用变化而失效。请使用官方支持的 .resonitepackage 格式。
• Cloud Spawning（云生成）： 利用键盘组件模拟触发云端物品生成。这并非真正的官方功能，未来可能会失效。

背包 (Inventory)

• 复杂文件夹名称： 避免在文件夹名中使用过长的文本或 ASCII 字符画。这在不同平台上显示效果不一，且会干扰未来的搜索索引。可以使用适量的 Emoji 或颜色标签。