GPU particle attractors — documentation

An attractor contributes force to GPU particles inside its influence region. It does not teleport them to a path, set every particle's velocity directly or alter gameplay-body gravity. Existing velocity and other material forces still matter.

Enable the interaction

Enable Attractor Interaction on the emitter's ParticleProcessMaterial (AttractorInteractionEnabled).
Add an appropriate particle attractor to the same effective World3D.
Match its CullMask with the emitter's render Layers, not physics CollisionLayer/CollisionMask.
Set its influence region and strength; initially disable unrelated movement contributors so the result is readable.
Check a particle born inside the region with a suitable camera and VisibilityAabb. A correctly configured force is not proof that an offscreen effect is being drawn.

The ParticleForces.CreatePull() helper in particle collision setup creates a sphere at (1, 0, 0), Radius 3, Strength 8, Attenuation 1 and Directionality 0. Add the returned Entity to the world and enable interaction on the process material. It is an example coefficient, not a calibrated gravity preset.

The GPU test confirms central attraction, negative-strength repulsion, exclusion outside the radius and mask filtering. Turning off the material flag leaves the zero-velocity reference particles at their origin.

Interpret the controls

Control	Meaning
Strength	Positive pulls toward the chosen force direction; negative reverses it. In an ordinary nondirectional sphere/box, this means toward/away from the center.
Attenuation	Exponent shaping influence falloff inside the region; use a sensible nonnegative value. It is not a distance in meters or a particle speed.
Directionality	0 uses the center-oriented force for sphere/box; 1 uses the attractor's local `-Z` direction at positive Strength. Intermediate values blend directions.
CullMask	Select emitters by render Layers. It does not hide the attractor's effect by camera visibility layers.
Radius / Size	Influence region of the corresponding shape. Box Size is full local dimensions, not half extents.

Rotating a fully directional attractor changes the force axis. The native test rotates it so local -Z points sideways and confirms sideways acceleration. Negative Strength reverses that direction. Position still matters for whether the particles are inside the region and its falloff.

Particles can cross the center or overshoot because a force accelerates them instead of pinning them. Use lifetime, damping, initial velocity and simulation fidelity deliberately rather than increasing Strength until the motion appears correct in one frame.

Choose a shape

Sphere and box define simple influence regions. Prefer their explicit Radius/Size for a controlled test; do not assume every nonuniform transform or moving-volume case has the same validated behavior.

A vector-field attractor reads a Texture3D over its box region. The shader linearly samples the field, decodes signed direction/strength around neutral (0.5, 0.5, 0.5), and adds a force with the configured strength, falloff and directionality. It is not a nearest-vector snap or a direct assignment to particle velocity.

For the default nondirectional field interpretation, RGB components above/below 0.5 represent positive/negative components after decoding. Test a known constant field before complex noise, including the imported texture's axis/encoding conventions. Do not infer a universal Y-flip from how a 2D image viewer displays slices. The current pass reviews field sampling in source; it does not claim an executed vector-texture example.

Keep the force and render bound consistent

A particle's path can leave its original spawn region. VisibilityAabb must cover the intended trajectory and mesh size; an attractor does not enlarge it automatically. A disappearing effect may be a culling problem rather than a missing force.

Shared ParticleProcessMaterial resources share AttractorInteractionEnabled and other settings. Create separate resources when emitters must react differently, or use render layers/masks intentionally. An ordinary Area3D or physics gravity override is not automatically a GPU particle attractor.

Diagnose a force that looks wrong

Symptom	Check
No visible response	Material interaction flag, same World3D, region, masks and whether the effect is visible.
Everything accelerates the wrong way	Strength sign, Directionality, rotation and the texture encoding for a field.
Force stops abruptly	Region boundary, lifetime and render culling.
Particles oscillate through the center	Existing velocity and acceleration; attraction is not position locking.
Changing one emitter changes another	Shared process material.
Vector field gives unexpected slice directions	Texture3D layout, signed encoding and transform; start with a simple known vector.

The native checks use a sphere on Windows Forward+/Vulkan. Vector textures, nonuniform scaling, moving attractors, combined fields, all hardware/export paths and performance are separate validation. These forces are visual particle simulation, not a substitute for authoritative gameplay physics.