GPU particle collision

GPU particle collision is a separate rendering/simulation path. An ordinary StaticBody3D and CollisionShape3D do not automatically become a GPU particle collider. If a wall must block both a player and GPU particles, provide and maintain the appropriate representation for each system.

Connect all three parts

1. Assign ParticleProcessMaterial to the emitter and select Collision → Mode → Rigid or Hide On Contact. Disabled means no collision response, even if collider Entities exist.
2. Set the emitter's CollisionBaseSize to an appropriate collision size for the effect. This is separate from mesh scale and VisibilityAabb. CollisionUseScale controls whether particle scale participates.
3. Add a GPUParticlesCollisionBox3D or another suitable particle collider to the same effective World3D as the emitter.
4. Make the collider CullMask overlap the emitter's render Layers. These are not gameplay physics layers/masks. Keep the emitter visible to its camera too.
5. Check a controlled trajectory against a sufficiently thick collider before adding complex materials, turbulence or high speed.

In C#, GpuParticlesCollisionBox3D.Size contains full local dimensions, not half extents. Size (4, 0.2, 4) creates that-sized box at unit transform scale. Old examples using an Extents property should not be copied into the current SDK.

Create a particle floor

The helper contains independent floor and attractor constructors; this section uses CreateFloor only.

using Reckfell;

public static class ParticleForces
{
    // GPU-particle collision only; no visible geometry or gameplay collider.
    public static GpuParticlesCollisionBox3D CreateFloor()
    {
        return new GpuParticlesCollisionBox3D
        {
            Size = new Vector3(4f, 0.2f, 4f), // Full dimensions, not half extents.
            Position = new Vector3(0, -0.5f, 0),
            CullMask = 1,
        };
    }

    public static GpuParticlesAttractorSphere3D CreatePull()
    {
        return new GpuParticlesAttractorSphere3D
        {
            Position = Vector3.Right,
            Radius = 3f,
            Strength = 8f,
            Attenuation = 1f,
            Directionality = 0f,
            CullMask = 1,
        };
    }
}

Call var floor = ParticleForces.CreateFloor(); and add it to the same world as the emitter. For the reference case, use emitter Layers 1, a ParticleProcessMaterial with CollisionMode Rigid, gravity downward and a nonzero CollisionBaseSize. The helper does not create a visible floor mesh or gameplay collider. Create those separately if the scene requires them.

The native test confirms that the particle box stops a falling effect with a matching mask. A mismatched mask or Disabled collision mode lets it fall through. HideOnContact removes the visible particles on contact. Replacing the particle box with only an ordinary StaticBody does not provide the GPU response.

Choose the representation

A collider is not the visible material. A beautiful floor texture does not establish matching particle geometry, and a collider with no corresponding mesh can appear to make particles float or stop in empty space.

Do not mix up masks

• CullMask on a particle collider chooses affected particle emitters by their render Layers.
• HeightfieldMask chooses mesh render layers used to build a height field. It does not replace the collider's emitter-selection CullMask.
• BakeMask on SDF chooses geometry for its baking workflow. Recheck/rebake when source geometry or this selection changes.
• Gameplay CollisionLayer/CollisionMask and camera CullMask serve different systems. Equal bit numbers do not connect those systems automatically.

For height fields, WhenMoved refers to movement of the height-field component; moving a source mesh alone does not establish an automatic refresh in that mode. Always refreshes at a higher cost. FollowCameraEnabled moves the capture region in steps and can trigger updates when it moves; do not assume every tiny camera movement produces a new complete field.

For an SDF, inspect its Size, resolution, generated Texture and source selection. A field that is too coarse can miss thin features. Transforming or replacing a resource is different from rebaking changed level geometry.

Treat fast collisions as a quality/performance problem

Thin obstacles and fast particles can tunnel with insufficient simulation steps or an unsuitable collision size. Increase the relevant simulation fidelity, collider thickness or particle collision size only after identifying the cause. FixedFps changes the particle simulation step, not the entire game FPS; interpolation does not add collision steps.

Bounce and friction in ParticleProcessMaterial control its collision response; this is not a full rigid-body solver for each particle. Do not expect ordinary physics-body contact signals, gameplay hit ownership or a CPU query result for every GPU collision. Use an explicit gameplay collision design where those are required.

Diagnose missing or incorrect contact

The executed example is Windows Forward+/Vulkan with an analytic box and controlled masks/modes, including a gameplay-body negative case. SDF/height-field baking, moving/scaled colliders, tunneling limits, all renderers/platforms, exports and performance budgets are not claimed validated here. For forces without contact, see attractors.