用途:这是 Navara 引擎自身的开发规范,用于在该仓库中新增、修改或审查代码(包括 Rust crate、WASM 等)时遵循统一的设计不变量与编码规则。
主要能力与规则:
- 先读对应指南。guide/ 目录按主题存放各子系统的深入说明。进行非琐碎改动前,先列出 guide/ 并阅读涉及领域的文件;若改动改变了指南所记录的行为,需在同一次改动中更新该指南。
- 复用子系统既有机制。每份指南记录受认可的范式(如 BATCH_TEXTURE.md 的“Slot mechanisms”),应扩展最接近的机制,而非发明新机制;共享同一代码路径的所有 mesh 类型须保持语义一致。
- 优先使用 CPU 侧解析的固定默认值,而不是把材质状态层层传递,或添加着色器侧的兜底宏/哨兵值。哨兵值仅作为属性无有意义常量时的最后手段。
- 注释只写代码无法表达的约束,不要把设计历史或讨论背景(被否决的方案、契约长文)写进注释,这些应放在 PR 描述或指南中。
- 删除因重构而变得空洞的测试,例如零初始化缓冲区按构造即满足的断言,或被相邻测试重复覆盖的用例。
- 不处理逻辑上不可能的情况。对周边不变量已排除的状态,不加兜底、守卫或错误路径,以免产生死代码并模糊真实契约;若某不变量值得强制,应使用断言(如 Rust 的 debug_assert!/unreachable!,TS 的 throw)而非静默处理。
适用场景:在 Navara 仓库内进行引擎开发、代码审查与重构时。
限制:资料未提供具体安装命令、依赖版本、平台支持范围与收费信息,暂未提供。