apply-conventions

引擎约定

针对版本敏感的 API，请查阅已安装的 playcanvas 声明。

坐标

• 右手坐标系，+Y 向上，单位为米。entity.forward、摄像机和 lookAt 使用 -Z。
• 定向光和聚光灯沿局部 -Y 方向照射，默认垂直向下。使用 setEulerAngles 调整方向，不要使用 lookAt。
• glTF 模型通常朝向 +Z；使用 calibrate-model 记录每个模型的偏航角。
• 角度 API 按 XYZ 顺序接收度数。将俯仰、偏航和翻滚作为应用状态保存；切勿将 getEulerAngles() 的结果传回 setEulerAngles()。使用 math.lerpAngle 或 Quat.slerp 进行插值。
• 在语义根节点上使用世界变换设置器，在父节点下方使用 setLocal*。不要缩放刚体根节点 或蒙皮骨骼。

当前 API

• 使用 render 和 anim 组件，而不是 model 和 animation。
• 使用 ESM class X extends Script 和 static scriptName，而不是 createScript。
• 使用 Mesh.fromGeometry(device, new BoxGeometry())，而不是 createBox 和其他 create* 助手函数。
• 从 playcanvas 进行命名导入；已发布脚本仅从 playcanvas/scripts/esm/** 导入。

摄像机

• FOV 是垂直视角，默认值为 45°。编写控制代码前，请检查已发布的摄像机脚本 （reuse-scripts）。

材质和边界

• StandardMaterial.useMetalness 默认为 false；使用 metalness 前请启用它。
• 修改属性后调用 material.update()。每个网格的值使用 meshInstance.setParameter()， 无需更新或克隆。
• 编辑某些网格所用的共享材质（包括导入的材质）前，先克隆它们。
• setParameter 会上传原始值；使用 Color#linear() 转换 sRGB 颜色。
• 默认剔除背面；逆时针绕序为正面。
• 实体没有 aabb；请合并其后代的 meshInstance.aabb。如果 mesh.update() 跳过边界更新， 请自行设置 mesh.aabb，并将任何顶点着色器位移纳入边界。

在运行中的应用中验证

离线值无法证明朝向、姿势或位置正确。使用 inspect-runtime 从运行中的应用读取数值，并且只根据你已检查过的截图判断视觉效果。保存的文件路径并不能作为证据。