add-effects

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

将瞬态效果设计为由应用事件触发的短期、自管理实体，而非永久的场景固定元素。

优先复用而非重新创作。使用

find-examples

工具找到最接近的官方粒子示例并进行适配，优先选择引擎内置的粒子组件而非手写系统，同时通过

reuse-scripts

工具查找已有的轨迹或效果脚本。

严格复制已安装示例中的粒子曲线构造方式。

CurveSet

为每个通道接收一个关键帧数组，例如

new CurveSet([0, x0, 1, x1], [0, y0, 1, y1], [0, z0, 1, z1])

；请勿将三个通道的数组合并为一个数组。格式错误的曲线可能通过类型检查，但会在粒子纹理上传时失败。创建一个发射器，渲染一帧画面，确保运行时无报错且控制台无诊断信息后，再将该工具复用在烟雾、喷射或飞溅效果中。

若需求是实现精致的尾迹、烟雾或喷射效果，不要停留在缩放平面、交叉广告牌或通用图元渲染阶段。使用内置粒子组件实现烟雾和喷射效果；为持续采样的尾迹丝带保留自定义网格和材质。对照实际场景的光照和表面验证色调与混合效果。

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.

在发射器的世界挂载点生成效果，可将其设为发射器的子实体，或复制一次世界变换，让效果在结束时自行销毁。绝对不能遗漏发射器（造成内存泄漏）。
将叠加或透明效果置于其所在表面之上，并偏向相机方向，避免出现Z轴冲突。检查掠射角度下的软透明效果是否存在硬边、黑色四边形或缺失情况。
根据发射器的校准边界调整效果的大小和朝向，而非使用猜测的常量值。

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.

将内置渲染图元视为软效果的遮挡几何体。参照最接近的官方示例，为预期的视觉行为选择粒子、自定义网格、纹理、材质和混合模式。
确保每个自定义网格的顶点流与其材质匹配。受光照的
```
StandardMaterial
```
需要法线；在调用
```
mesh.update()
```
前计算并设置法线，或刻意使用无光照材质。即使部分画面仍能显示，也要将缺失顶点属性的诊断信息视为渲染失败。对于使用
```
setVertexStream
```
创建的动态水平丝带，需在位置数组旁分配法线数组，为每个顶点填充
```
(0, 1, 0)
```
，并在首次调用
```
update()
```
前将其作为
```
SEMANTIC_NORMAL
```
上传。每次更改丝带的材质类型时，都需重新检查这一点。
切勿将空的动态网格附加到启用的渲染组件上。在创建
```
MeshInstance
```
前，上传有效的初始顶点和索引集，或在首次完成更新前保持渲染实体禁用状态。重置时，禁用实体或恢复有效的初始几何体；当启用的渲染器仍引用该网格时，请勿调用
```
mesh.clear()
```
。反射和折射相机会渲染同一网格，可能在游戏相机发现之前就暴露此生命周期漏洞。
从预期的相机视角判断轨迹效果。如果轨迹看起来像平面贴花，参照示例添加所需的最小深度提示，而非堆叠任意几何体。
持续采样轨迹。以较小的时间或距离步长添加线段，并在它们之间进行插值；粗糙的按距离分段会导致轨迹在物体加速时出现卡顿，断裂成可见的小段。
将轨迹锚定到移动物体的接触点或排气点，根据速度调整发射速率和长度，并让轨迹尾部渐隐，使其自然消散而非突然生硬截断。

Camera shake and hit feedback

相机震动与命中反馈

Drive camera shake as a decaying offset on a camera parent or an additive layer; never write it into the smoothed chase position, or it fights the follow. Keep shake and follow separate, as the orbit-camera rule in
```
apply-conventions
```
requires.
Stagger the parts of a compound effect over a few frames — flash, then smoke, then splash — so an event reads as a sequence rather than a single pop.
Keep the readable peak long enough for the gameplay camera to see the layers together. A flash can be brief, but the longer-lived layers should overlap for several frames rather than leaving the primary action frame visually identical to the idle state.
For side-mounted emitters, derive every spawn point and direction from calibrated world-space mounts on the mover. Confirm the effect starts outside the source geometry from both sides; an active cooldown with only a tiny flash elsewhere in the frame is failed feedback.

通过相机父物体的衰减偏移或叠加层实现相机震动；切勿将震动写入平滑的追踪位置，否则会与追踪逻辑冲突。按照
```
apply-conventions
```
中的轨道相机规则，将震动与追踪逻辑分开处理。
将复合效果的各个部分在几帧内错开触发——先闪光，再烟雾，最后飞溅——让事件呈现为一个序列而非一次性弹出。
确保可识别的效果峰值持续足够长的时间，让游戏相机能看到所有叠加层。闪光可以很短暂，但持续时间较长的图层应重叠数帧，避免主动作帧与空闲状态的视觉效果完全一致。
对于侧面安装的发射器，每个生成点和方向都应从移动物体上校准后的世界空间挂载点获取。从两侧确认效果起始于源几何体之外；如果仅在帧内其他位置出现微小闪光，而处于激活冷却状态，则属于失败的反馈效果。

Prove it fires

验证效果触发

Trigger each effect through real gameplay input and confirm with a screenshot captured at its peak, not a saved filepath. Confirm the effect is visible from the gameplay camera and from a grazing angle, that emitters are gone after their lifetime (query the entity count), and that nothing leaves a black quad or a hard edge over the surface.

Choose the authoring surface with the

build-app

skill; create effects through its entity and component primitives and own their lifecycle in the surface that spawned them.

通过真实的游戏输入触发每个效果，并在效果峰值时截图确认，而非仅保存文件路径。确认效果在游戏相机视角和掠射角度下均可见，发射器在生命周期结束后已消失（查询实体数量），且表面没有留下黑色四边形或硬边。

使用

build-app

技能选择创作界面；通过其实体和组件图元创建效果，并在生成效果的界面中管理其生命周期。