add-effects

Effects and game feel

Add transient effects as short-lived, self-owning entities triggered by application events, not as permanent scene fixtures.

Reuse before authoring. Adapt the closest official particle example with find-examples, prefer the Engine's built-in particle component over a hand-written system, and discover any shipped trail or effect script with reuse-scripts.

Copy particle curve construction from the installed example exactly. CurveSet takes one key array per channel, such as new CurveSet([0, x0, 1, x1], [0, y0, 1, y1], [0, z0, 1, z1]); do not flatten three channels into one array. A malformed curve can type-check and then fail inside the particle texture upload. Create one emitter, render a frame, and require empty runtime and console diagnostics before reusing the helper for smoke, spray, or splashes.

For a polished wake, smoke, or spray requirement, do not stop at scaled planes, crossed billboards, or generic render primitives. Use the built-in particle component for smoke and spray; reserve a custom mesh and material for a continuously sampled wake ribbon. Verify tint and blending against the actual scene lighting and surface.

Place and layer

• Spawn an effect at the emitter's world mount point, either parent it there or copy the world transform once, and let it destroy itself when finished. Never leak emitters.
• Keep additive or transparent effects above the surface they sit on and biased toward the camera so they do not z-fight. Inspect soft transparency at grazing angles for hard edges, black quads, or dropout.
• Size and orient effects from the emitter's calibrated bounds, not a guessed constant.

Moving trails

• Treat built-in render primitives as blocking geometry for soft effects. Follow the closest official example to choose particles, a custom mesh, textures, materials, and blending for the intended visual behavior.
• Match every custom mesh's vertex streams to its material. A lit StandardMaterial needs normals; calculate and set them before mesh.update(), or deliberately use an unlit material. Treat a missing vertex-attribute diagnostic as a rendering failure even when some frames still appear. For a dynamic horizontal ribbon created with setVertexStream, allocate a normal array alongside positions, fill every vertex with (0, 1, 0), and upload it as SEMANTIC_NORMAL before the first update(). Recheck this whenever changing the ribbon's material type.
• Never attach an empty dynamic mesh to an enabled render component. Upload a valid initial vertex and index set before creating its MeshInstance, or keep the render entity disabled until the first complete update. On reset, disable it or restore valid seed geometry; do not call mesh.clear() while an enabled renderer still references it. Reflection and refraction cameras render the same mesh and can expose this lifecycle bug before the gameplay camera does.
• Judge a trail from its intended cameras. If it reads as a flat decal, use the reference example to add the minimum depth cue needed rather than stacking arbitrary geometry.
• Sample the trail continuously. Append segments on a small time- or distance-step and interpolate between them; coarse per-distance chunks make the trail stutter and break into visible dashes as the object speeds up.
• Anchor it to the mover's contact or exhaust point, scale emission rate and length with speed, and fade the tail so it dissolves instead of cutting off with a hard edge.