apply-conventions

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Engine conventions

引擎约定

Read

package.json

and the installed

playcanvas

source before relying on version-sensitive API details. Apply these stable conventions throughout the project.

在依赖版本敏感的API细节之前，请先阅读

package.json

和已安装的

playcanvas

源代码。在整个项目中遵循这些稳定的约定。

Coordinates and angles

坐标与角度

Use the right-handed coordinate system: +Y is up and the gameplay ground plane is XZ.
Treat
```
entity.forward
```
and the camera viewing direction as -Z;
```
entity.right
```
is +X and
```
entity.up
```
is +Y.
```
lookAt
```
points -Z at the target.
Expect glTF models authored toward +Z to need a yaw correction. Inspect and calibrate each directional model instead of applying one global correction.
Pass degrees in XYZ order to high-level angle APIs.
Keep pitch, yaw, and roll as application state. Do not repeatedly read
```
getEulerAngles()
```
and feed its decomposition back into
```
setEulerAngles()
```
.
Interpolate periodic angles with
```
math.lerpAngle()
```
or rotations with
```
Quat.slerp()
```
, not scalar lerp across the 0/360 seam.

使用右手坐标系：+Y轴向上，游戏地面平面为XZ平面。
将
```
entity.forward
```
和相机视角方向视为-Z方向；
```
entity.right
```
为+X方向，
```
entity.up
```
为+Y方向。
```
lookAt
```
方法会将-Z方向指向目标。
注意面向+Z方向制作的glTF模型可能需要偏航角修正。请检查并校准每个定向模型，而非应用全局统一修正。
向高层角度API传递角度时，采用XYZ顺序的度数。
将俯仰角（pitch）、偏航角（yaw）和滚转角（roll）作为应用状态保存。不要反复读取
```
getEulerAngles()
```
并将分解结果重新传入
```
setEulerAngles()
```
。
使用
```
math.lerpAngle()
```
对周期性角度进行插值，或使用
```
Quat.slerp()
```
对旋转进行插值，不要在0/360度接缝处使用标量插值。

Transforms and units

变换与单位

Use
```
setPosition
```
,
```
setRotation
```
, and
```
setEulerAngles
```
for world transforms.
Use the
```
setLocal*
```
variants below a parent.
Treat units as metres. Physics gravity defaults to
```
(0, -9.81, 0)
```
.
Keep gameplay transforms on a semantic root and asset-authoring corrections on a child.
Do not scale rigid-body roots or skinned bones.

使用
```
setPosition
```
、
```
setRotation
```
和
```
setEulerAngles
```
设置世界变换。
在父实体下使用
```
setLocal*
```
系列方法设置局部变换。
将单位视为米。物理重力默认值为
```
(0, -9.81, 0)
```
。
将游戏玩法变换放在语义根实体上，将资源制作修正放在子实体上。
不要缩放刚体根实体或蒙皮骨骼。

Cameras, materials, and bounds

相机、材质与边界

Perspective camera FOV is vertical and defaults to 45 degrees.
Smooth an orbit camera's focus, yaw, pitch, and distance, then derive its position. Do not
```
Vec3.lerp()
```
between orbit positions on opposite sides of the focus; the chord crosses the subject.
Before writing custom camera input, inspect the installed controller script and its matching Engine example. Preserve their gesture mapping and damping unless the product explicitly asks for different behavior; do not derive signs from memory.
Define the input contract in screen space, then verify positive and negative movement on both axes with real input after a rendered frame. Judge the camera basis or a projected fixed landmark, not world-space camera coordinates or internal angle signs; both can approve inverted behavior.
Materials cull back faces by default; counter-clockwise winding defines the front face.
Clone a material before per-instance tinting or edits, and assign the clone; never mutate one shared by other instances, including default and asset-imported materials.
Entities do not have an
```
aabb
```
. Union descendant
```
meshInstance.aabb
```
values after transforms have synchronized.
Let
```
Mesh.update()
```
calculate local bounds. If passing
```
false
```
for
```
updateBoundingBox
```
, assign an explicit
```
mesh.aabb
```
before the mesh can be culled.
Expand custom-mesh bounds by the maximum vertex-shader displacement; CPU bounds do not observe shader deformation.
Treat offline skinned-mesh bounds as bind-pose estimates and confirm animated poses at runtime.

透视相机的视野（FOV）为垂直方向，默认值为45度。
对轨道相机的焦点、偏航角、俯仰角和距离进行平滑处理，然后推导其位置。不要在焦点两侧的轨道位置之间使用
```
Vec3.lerp()
```
；这样的插值路径会穿过目标对象。
在编写自定义相机输入逻辑之前，请检查已安装的控制器脚本及其对应的引擎示例。除非产品明确要求不同行为，否则保留它们的手势映射和阻尼效果；不要凭记忆推导符号。
在屏幕空间中定义输入协议，然后在渲染帧后通过实际输入验证两个轴上的正负移动。判断相机基准或投影的固定地标，而非世界空间中的相机坐标或内部角度符号；这两者都可能认可反向行为。
材质默认剔除背面；逆时针缠绕顺序定义正面。
在进行逐实例着色或编辑之前克隆材质，并分配克隆后的材质；永远不要修改其他实例共享的材质，包括默认材质和导入的资源材质。
实体没有
```
aabb
```
属性。在变换同步后，合并子实体的
```
meshInstance.aabb
```
值。
让
```
Mesh.update()
```
计算局部边界。如果在调用时传入
```
false
```
作为
```
updateBoundingBox
```
参数，请在网格可能被剔除前显式分配
```
mesh.aabb
```
。
将自定义网格的边界扩展至顶点着色器的最大位移量；CPU端的边界不会考虑着色器变形。
将离线蒙皮网格的边界视为绑定姿势的估计值，并在运行时确认动画姿势。

Imports

导入

Use named ESM imports from

playcanvas

. Import production scripts only from

playcanvas/scripts/esm/**

; legacy sibling script directories depend on a global Engine namespace.

使用来自

playcanvas

的命名ESM导入。仅从

playcanvas/scripts/esm/**

导入生产脚本；旧的同级脚本目录依赖全局引擎命名空间。

Runtime confirmation

运行时确认

Offline measurements cannot prove facing, animated poses, or final placement. Confirm each one in the running application:

Start the project's own dev server or build; do not construct a separate harness.
Log the value from inside the Engine, using
```
getPosition()
```
,
```
getEulerAngles()
```
, a
```
meshInstance.aabb
```
, or an anim component's active state, from a
```
Script
```
or an update callback.
For large or vertex-displaced meshes, inspect their runtime AABB and
```
visibleThisFrame
```
after a rendered frame from at least two representative camera angles.
Confirm a directional model's visible front aligns with its semantic root's
```
forward
```
; a stored yaw or runtime transform alone cannot prove mesh facing.
Read that logged value from the browser console. Screenshots judge composition and orientation; numeric claims require logged values.
Record the confirmed value in application state or an asset tuning record, then remove the logging.

离线测量无法验证朝向、动画姿势或最终位置。请在运行中的应用程序中逐一确认：

启动项目自身的开发服务器或构建版本；不要构建单独的测试环境。
在引擎内部记录值，例如从
```
Script
```
或更新回调中调用
```
getPosition()
```
、
```
getEulerAngles()
```
、
```
meshInstance.aabb
```
或动画组件的活动状态。
对于大型或顶点位移的网格，在渲染帧后从至少两个代表性相机角度检查其运行时AABB和
```
visibleThisFrame
```
属性。
确认定向模型的可见正面与其语义根实体的
```
forward
```
方向对齐；仅存储的偏航角或运行时变换无法证明网格朝向正确。
从浏览器控制台读取记录的值。截图用于判断构图和方向；数值结论需要记录的数值支持。
将确认的值记录到应用状态或资源调优记录中，然后移除日志代码。