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 and reassign a shared material before editing it for only some meshes, including default

and asset-imported materials. Per-mesh uniforms use meshInstance.setParameter() without cloning.

• 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.

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.

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.