perf(particlesys): Batch same type particles to reduce cost of particle rendering by 15 to 30%

[Mauller]

This can be squash merged

This PR is separated into two commits to aid reviewing.
The initial commit is a small refactor to make the diff slightly cleaner on the second commit.
The second commit implements the particle batching created by Ronin and cleaned up by myself.

When testing we see a 15-20% performance improvement on average. But this may be higher in some scenarios.
EDIT: An early particle visibility test has added 2 - 5% more performance on top of the original.

The batching works by creating a common texture that the particle effects are drawn to before being sent to the GPU. This reduces the number of draw calls, thus improving rendering performance.

Only particles with the same material and shader type can be batched to the texture, so once particles of a different type are observed. The system will flush the prior batch and start a new one based on the new particle type.

As draw order is preserved, particles adhere to their original layering.

---

Some performance comparison images

Using the chemical spray as the source of particles, all tractors are using their AoE spray ability when these images were taken.

Before:

After:

Using the firewall and flamethrower effect of the flame tank, a circle of flame tanks are creating firewalls in the centre while extra flamers spray fire into the centre of the inferno.

Before:

After:

[qodo-free-for-open-source-projects]

PR Summary by Qodo

perf(particlesys): Batch same-type particles to reduce draw calls

✨ Enhancement 🕐 40+ Minutes

AI Description

• Add same-texture/shader/billboard batching to reduce particle draw calls while preserving order.
• Add early per-system visibility culling to skip texture lookups and rendering work.
• Refine particle system getters to return const references and be const-correct.

Diagram

graph TD
  A["W3DParticleSystemManager::doParticles"] --> B["Cull & mark particles"] --> C{Any visible?}
  C -->|No| A
  C -->|Yes| D{Batch key matches?}
  D -->|No| F["Flush current batch"] --> D
  D -->|Yes| E["Append to buffers"] --> G["Direct render (streak/volume) or defer"] --> A
  A -. "end frame" .-> H["Flush pending batch"]

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. GPU instancing / dynamic vertex buffer per material

• ➕ Potentially larger win than texture-based batching by minimizing CPU-side state changes
• ➕ Keeps a clearer separation between batching and per-system logic
• ➖ Higher implementation complexity in this engine path (shader/vertex format changes)
• ➖ May require broader renderer changes and more testing across particle types

2. Pre-bucket systems by render key (texture/shader/billboard)

• ➕ Maximizes batching opportunities beyond adjacent systems
• ➕ Simplifies flush frequency
• ➖ Likely breaks strict draw order/layering unless additional depth-sorting logic is added
• ➖ Can introduce visual regressions for effects relying on deterministic ordering

3. Cache texture handle on ParticleSystem / template

• ➕ Avoid per-frame asset manager lookups and reduces batch-key churn
• ➕ Lower risk incremental optimization that composes with current batching
• ➖ Requires careful lifetime/ref-count management and invalidation rules
• ➖ Smaller win than batching alone if lookups are already cheap

Recommendation: The PR’s approach is a good tradeoff: it improves performance while preserving existing draw order by only batching adjacent compatible systems and flushing on key changes/full buffers. Consider a follow-up to cache resolved particle textures (or a stable render key) on the system/template to further reduce asset lookups and reduce unnecessary flush triggers.

Files changed (3) +185 / -89

Enhancement (2) +183 / -87

W3DParticleSys.hAdd batching helpers and batch state to W3D particle manager +7/-0

Add batching helpers and batch state to W3D particle manager

• Introduces initializeBatch/flushParticleBatch helpers and stores batch key state (texture, shader type, billboard flag). This enables batched sprite rendering across compatible particle systems.

Core/GameEngineDevice/Include/W3DDevice/GameClient/W3DParticleSys.h

W3DParticleSys.cppImplement early particle visibility culling and batched sprite flushing +176/-87

Implement early particle visibility culling and batched sprite flushing

• Adds an early per-system visibility pass that marks particles culled to avoid unnecessary work. Implements batching for compatible sprite particles (same texture/shader/billboard), flushing on key changes, buffer-full mid-system, and end-of-frame; streak and volumetric systems continue to render via their dedicated paths.

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp

Refactor (1) +2 / -2

ParticleSys.hMake particle template/system name getters const-ref and const +2/-2

Make particle template/system name getters const-ref and const

• Updates ParticleSystemTemplate::getName and ParticleSystem::getParticleTypeName to return const references and be const-qualified. This reduces string copies and improves const-correctness for rendering and lookup call sites.

Core/GameEngine/Include/GameClient/ParticleSys.h

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. canBatch always true 🐞 Bug ≡ Correctness

Description

doParticles() computes canBatch with `!isUsingStreak() ||
getVolumeParticleDepth()==DEFAULT_VOLUME_PARTICLE_DEPTH`, but DEFAULT_VOLUME_PARTICLE_DEPTH is 0 and
getVolumeParticleDepth() returns 0 for all non-volume systems (including STREAK), making canBatch
effectively always true. This allows streak/volumetric systems to share the global batched buffer
and then render using pointCount from index 0, which can include particles from previous systems,
producing incorrect rendering and potential duplicate draws.

Code

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[R224-230]

+		const Bool canBatch = !sys->isUsingStreak() || sys->getVolumeParticleDepth() == DEFAULT_VOLUME_PARTICLE_DEPTH;
+		if (!canBatch ||
+			texture.Peek() != m_batchTexture.Peek() ||
+			sys->getShaderType() != m_batchShaderType ||
+			sys->shouldBillboard() != m_batchBillboard)
+		{
+			flushParticleBatch(rinfo, pointCount);

Evidence

DEFAULT_VOLUME_PARTICLE_DEPTH is defined as 0, while ParticleSystem::getVolumeParticleDepth()
returns 0 for all non-volume particle types; this makes the OR-based canBatch expression true even
for STREAK systems. The STREAK and volumetric render paths then render using pointCount and raw
arrays from index 0, which will include any prior batched particle data when a batch is pending.

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[218-239]
Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[301-345]
Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[347-378]
Core/GameEngine/Include/GameClient/ParticleSys.h[60-62]
Core/GameEngine/Include/GameClient/ParticleSys.h[605-610]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`canBatch` is computed in a way that makes it effectively always `true` (because DEFAULT_VOLUME_PARTICLE_DEPTH is 0 and `getVolumeParticleDepth()` returns 0 for non-volume systems). This allows non-batchable systems (notably STREAK and volumetric particle draws) to be processed as if they were batchable, contaminating the shared particle buffers and leading to incorrect rendering.
### Issue Context
Batching relies on `pointCount` being a global “batch” count, but STREAK and volumetric rendering paths call render functions using `pointCount` and buffer pointers starting at index 0. If a pending batch exists, these paths will read/render prior systems’ particle data.
### Fix Focus Areas
- Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[218-239]
- Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[301-378]
- Core/GameEngine/Include/GameClient/ParticleSys.h[60-62]
- Core/GameEngine/Include/GameClient/ParticleSys.h[605-610]
### Expected change
Update the eligibility logic so batching is only enabled for the intended particle types (e.g., sprite/non-streak and non-volumetric). For example:
- Use `&&` instead of `||` and ensure the volumetric depth check actually excludes volumetric systems.
- Ensure streak/volumetric paths force a flush before populating their local buffers (or otherwise guarantee they start from index 0 without pending batched content).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. RefCountPtr double release 🐞 Bug ☼ Reliability

Description

The destructor calls REF_PTR_RELEASE(m_batchTexture) even though m_batchTexture is a
RefCountPtr, causing Release_Ref() to be invoked twice (once via x->Release_Ref() and once via
x = nullptr which releases the current referent). This can delete the texture early and then
release a freed object (use-after-free) during shutdown/teardown.

Code

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[R84-87]

+	if (m_batchTexture)
+	{
+		REF_PTR_RELEASE(m_batchTexture);
+	}

Evidence

The PR calls REF_PTR_RELEASE on a RefCountPtr member in the destructor. REF_PTR_RELEASE performs
both an explicit Release_Ref() and then assigns nullptr; RefCountPtr's nullptr assignment operator
also calls Release_Ref(), resulting in two releases of the same referent.

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[73-88]
Core/Libraries/Source/WWVegas/WWLib/refcount.h[63-65]
Core/Libraries/Source/WWVegas/WWLib/ref_ptr.h[291-300]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`REF_PTR_RELEASE` is a macro intended for raw ref-counted pointers. Applying it to `RefCountPtr<T>` can double-release the referent because the macro calls `x->Release_Ref()` and then `x = nullptr`, and `RefCountPtr::operator=(nullptr)` also releases the current referent.
### Issue Context
`W3DParticleSystemManager::m_batchTexture` is declared as `RefCountPtr<TextureClass>`. It already releases in its destructor and also provides `Clear()` for explicit release.
### Fix Focus Areas
- Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[73-88]
- Core/Libraries/Source/WWVegas/WWLib/refcount.h[63-65]
- Core/Libraries/Source/WWVegas/WWLib/ref_ptr.h[291-300]
### Expected change
Replace `REF_PTR_RELEASE(m_batchTexture)` with `m_batchTexture.Clear()` (or remove the explicit release entirely and rely on `RefCountPtr` destruction). Do not use `REF_PTR_RELEASE` on `RefCountPtr` variables.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

3. Batch texture ref leak ✓ Resolved 🐞 Bug ☼ Reliability

Description

W3DParticleSystemManager retains an extra reference to m_batchTexture via Add_Ref() during batching,
but the destructor never releases it, so destroying the manager with a pending batch can leak a
TextureClass ref and prevent proper cleanup. Normal end-of-frame flushing usually releases it, but
lifecycle paths that skip the final flush (shutdown/teardown) can still leak.

Code

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[R210-213]

+		if (canBatch && m_batchTexture == nullptr)
+		{
+			m_batchTexture = texture;
+			m_batchTexture->Add_Ref();

Evidence

The batching code explicitly increments the texture refcount for m_batchTexture, and
flushParticleBatch() decrements it, but the class destructor does not release m_batchTexture at
all, violating the refcount ownership rules for stored pointers.

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[195-216]
Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[256-282]
Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[441-478]
Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[75-90]
Core/Libraries/Source/WWVegas/WWLib/refcount.h[67-83]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`W3DParticleSystemManager` now owns a ref-counted `m_batchTexture` (via `Add_Ref()`), but its destructor doesn’t release that ownership. If the manager is destroyed while a batch is pending, the texture ref can leak.
### Issue Context
- `Get_Texture()` returns an add-ref’d `TextureClass*`, and any retained pointer must be released per `refcount.h` rules.
- `flushParticleBatch()` releases `m_batchTexture`, but destructor cleanup should not rely on a render-path being invoked.
### Fix Focus Areas
- Add destructor cleanup for the new owned member (`m_batchTexture`) and reset batch state.
- file/path[start_line-end_line]
- Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[47-90]
- Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[209-216]
- Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[441-478]
### Suggested change
In `~W3DParticleSystemManager()`, add e.g.:
- `REF_PTR_RELEASE(m_batchTexture);`
- `m_pointCount = 0;`
(Optionally do this before/after deleting `m_pointGroup`; either is fine since both are ref-counted owners.)

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

4. Unconditional texture lookup ✓ Resolved 🐞 Bug ➹ Performance

Description

doParticles now calls Get_Texture() before it knows whether any particles survive culling
(m_pointCount==startCount), causing unnecessary texture-hash lookup and refcount inc/dec work for
systems that render nothing. This adds avoidable per-system overhead on the empty/fully-culled path.

Code

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[R195-199]

+		// TheSuperHackers @perf 09/08/2026 Ronin/Mauller Implement batched rendering for similar particles
+		// Particles with the same blending will now be batched onto a single texture surface before being drawn
+		// If a different particle type appears before the batch is filled, the previous batch will be drawn first
+		TextureClass *texture = W3DDisplay::m_assetManager->Get_Texture( sys->getParticleTypeName().str() );
+		const Bool canBatch = !( m_streakLine && sys->isUsingStreak() ) && ( sys->getVolumeParticleDepth() <= 1 );

Evidence

The code fetches the texture (which includes an Add_Ref) before particle culling, and then
immediately releases it in the no-particles path, proving the extra work occurs even when nothing is
rendered.

Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[195-206]
Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[285-289]
Generals/Code/GameEngineDevice/Source/W3DDevice/GameClient/W3DAssetManager.cpp[157-181]
Generals/Code/GameEngineDevice/Source/W3DDevice/GameClient/W3DAssetManager.cpp[221-229]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`Get_Texture()` is invoked for every non-smudge particle system before culling determines whether the system contributes any renderable particles. For fully-culled/empty systems this work is wasted.
### Issue Context
`W3DAssetManager::Get_Texture()` performs a hash lookup and `Add_Ref()` before returning, so calling it for systems that end up not rendering does extra work and refcount churn.
### Fix Focus Areas
- Lazily acquire the texture only after the first particle passes culling (before writing into the batch buffers), so fully-culled systems never call `Get_Texture()`.
- Ensure batching flush/setup still happens before appending any particles into the shared buffers.
- file/path[start_line-end_line]
- Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[195-218]
- Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp[231-290]
- Generals/Code/GameEngineDevice/Source/W3DDevice/GameClient/W3DAssetManager.cpp[157-229]
### Suggested approach
- Initialize `TextureClass* texture = nullptr;` and postpone `Get_Texture()` until you encounter the first particle that passes the cull checks.
- At that moment, run the current batch-compatibility checks and potentially `flushParticleBatch(rinfo)` **before** writing that first particle into the buffers.
- If no particles pass culling, skip texture acquisition entirely.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Tip of the day

💡 Did you know, you can route each action level your way: inline, summary, both, or drop

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[stephanmeesters]

I think W3DParticleSys.h was supposed to have been moved to core in #3014 but wasn't...

[Mauller]

I think W3DParticleSys.h was supposed to have been moved to core in #3014 but wasn't...

Outside the scope of this change, but i noticed that too.

[Mauller]

Made another modification to perform an earlier visibility check, it can help prevent non visible particle systems from causing a batch flush. It also saves a bit of overhead later on.

It can give a bit of extra perf due to this, around 2 - 5% more.

[Mauller]

Ah stupid VC6 loop handling, will just fixing now

[Mauller]

Fixed VC6 build and issues mentioned by the bot

[stephanmeesters]

Would it make things simpler/more consistent if volume particles were batched as well?

[Mauller]

volume particles work in a different way as they have multiple surfaces.
The batching only really works with billboarded / flat particles

[stephanmeesters]

Are they really that different though, they appear to use the same input arrays. The only difference is that they call a different render function and render more surfaces

[Mauller]

Would need to find something that uses volume particles, all my current tests don't show any activity down that path

[Mauller]

Found that the microwave tank uses them.

[xezon]

First review pass. Reference counting needs simplification.

[Mauller]

Partially addressed review comments, things still appear to give a good 15 - 30% more performance with the tweaks.

[Mauller]

I am going to change this back to a draft for the moment as i have seen some other things to cleanup.

[greptile-apps]

Greptile Summary

The PR optimizes W3D particle rendering by grouping compatible point-particle systems into shared draw calls while preserving explicit handling for streak, volume, smudge, and drawable effects.

• Adds texture, shader, and billboard-aware batch state.
• Flushes batches at compatibility boundaries, capacity limits, and frame completion.
• Performs an early visibility pass and tracks culled particles.
• Returns particle-system names by const reference and adds particle-type helpers.

Confidence Score: 5/5

The PR appears safe to merge because no eligible blocking failure remains in the follow-up review scope.

No blocking failure remains.

Important Files Changed

Filename	Overview
Core/GameEngine/Include/GameClient/ParticleSys.h	Adds a point-particle type predicate, normalizes accessor return types, and avoids copying particle-system names.
Core/GameEngineDevice/Include/W3DDevice/GameClient/W3DParticleSys.h	Introduces the texture, shader, and billboard state and helper methods required to manage particle batches.
Core/GameEngineDevice/Source/W3DDevice/GameClient/W3DParticleSys.cpp	Implements visibility marking, compatible point-particle accumulation, subtype boundaries, capacity flushing, and final batch rendering.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    S[Visit particle system] --> C{Any visible particles?}
    C -- No --> N[Visit next system]
    C -- Yes --> T{Point particles?}
    T -- No --> F[Flush pending point batch]
    F --> D[Render subtype-specific effect]
    T -- Yes --> K{Texture, shader, and billboard match?}
    K -- No --> F2[Flush previous batch]
    F2 --> I[Initialize compatible batch]
    K -- Yes --> A[Append visible particles]
    I --> A
    A --> B{Buffer full?}
    B -- Yes --> F3[Flush and resume same system]
    B -- No --> N
    F3 --> N
    N --> E{End of list?}
    E -- No --> S
    E -- Yes --> L[Flush final batch]

Loading

_{Reviews (8): Last reviewed commit: "Review update" | Re-trigger Greptile}

[Mauller]

This should be functioning properly now after the changes to make sure only normal particles with additive shaders are batched.

Also after the volume particle PR changes i added an extra helper function in this PR to check for regular particle types since that makes the check for batching cleaner.

[tintinhamans]

@codex

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2d94e31d95

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Mauller]

I reverted the gate for additive only particles, after further investigation i believe the issue that was being seen was due to a problem with an earlier implementation of the code.

[Skyaero42]

I think we're good, tested some heavy scenes with up to 5K particles rendering, flipping back and forth on the same paused frame without any visual difference. Number of draw calls would drop up to several thousand, thanks to batching, in a dragon tank only scene, and up to several hundred in a regular scene.

I tested a replay with lots of suicidal toxic tractors and bomb trucks. Based on video material, both before and after look the same.

[Mauller]

Updated to allow the batching and rendering of untextured particles.

The retail games do not make use of these but the engine still supported them.

[Mauller]

This should be good again now.

[xezon]

The munkees will be ecstatic about this.

[Caball009]

Incomplete review, a few nitpicks.

[Mauller]

Updated based on most review comments, this PR can be squash merged.

[xezon]

Incomplete review

Waiting.

[Caball009]

I'll leave an update in a couple of hours.

[Caball009]

Nice performance improvement. I had hoped to see even more performance by combining the two loops that iterate through all particles (first general loop, and then for the smudge type particles), but it didn't seem to make a difference.

[Caball009]

const ParticleSystem& system
(that'll require making the two member functions const).

[Mauller]

I don't think this matters too much and requires a dereference on the pointer being passed to the function anyway.

The particle system list is a list of pointers.

[Caball009]

It's minor, but in general it's a good idea to pass by reference if you're going to dereference the pointer anyway.

[Mauller]

cleaned up the unnecessary const returns