apply-conventions

Engine conventions

Read package.json and the installed playcanvas source before relying on version-sensitive API details. Apply these stable conventions throughout the project.

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.

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.

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.
• setParameter uploads raw values; author colours in sRGB and convert with Color#linear() before upload — do not hand-roll gamma.
• 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.