AsyncParticles Guide: GPU Acceleration, Compute Stage, and Compatibility Fixes

AsyncParticles is configured entirely through its settings interface and hotkeys, and this guide covers the GPU acceleration path, the compute stage, renderer threading, the light cache, and the compatibility toggles that address mod conflicts, contraption behaviour, and crashes.

Getting Started and Profiles

Open the configuration menu to reach every option described here. If the menu cannot open, the mod reports that the Cloth Config API is missing; in that case you can edit settings by hand and then use Reload Config. Hold SHIFT while in the interface to reveal the reset button. Resetting asks for confirmation first, as does reloading.

Several ready-made profiles exist:

• Compatibility Try It! — the defaults, which the mod describes as already broadly compatible and suitable for most setups.
• Particle Async Only — asynchronous handling for particles alone.
• Particle Async Only & Thread Safe — the same, plus every thread-safety mixin applied; a restart is required, coverage is not complete, and other parts of the game may lose performance.
• Main Thread Everything — everything runs on the main thread.

GPU Acceleration and the Compute Stage

GPU Particle Acceleration renders particles on the graphics card, raising framerate and lowering CPU usage. It only applies while Async Particle Tick is active.

Append New Particles to GPU Renderer controls whether freshly created particles join the GPU renderer immediately. Turning it off helps tick performance, at the cost of new particles not appearing during their first tick.

Compute Execution Stage decides the point in each frame at which the compute pass executes. It matters only with GPU acceleration on, and it resolves certain rendering problems seen on older graphics drivers.

Tick Renderer On Main Thread moves GPU renderer ticking to the main thread. It applies when Async Particle Tick is off.

Async Ticking and Renderer Threading

Async Particle Tick selects the asynchronous ticking method. Sequenced processes the whole queue asynchronously without dividing it. Split divides the queue into parts ticked in parallel, which can clash with other mods.

GPU Only Async Particle Tick restricts asynchronous ticking to GPU particles, and only functions when Async Particle Tick is enabled. Async Animation Tick chooses the animation ticking method, where Synchronously means no optimisation. Split Vanilla Particle Ticking distributes supported tick work more evenly rather than grouping by ParticleRenderType. Async Weather Tick enables asynchronous weather ticking, and Deferred Texture Tick delays texture ticking by one frame to reduce lag.

Light Cache and Culling

Particle Light Cache caches particle lighting for performance. Particles Light Cache Blacklist excludes chosen particles from it.

Culling removes particles outside the camera view. Sphere is the recommended mode but may conflict with some mods; Box is the older, slower, more accurate approach; Disable turns culling off. Weather can be culled separately, and Particle Culling Blacklist exempts particles from removal. Cull 'UNDERWATER' Particle Type makes underwater particles appear only while you are genuinely submerged, on non-Fabulous graphics.

Cleanup, Limits, and Failure Handling

Particle Cleanup Strategy sets how dead particles are cleared, and only applies with Async Particle Tick on. Parallel Particle Cleanup uses several threads to clear them faster, and Parallel Particle Eviction speeds up removal of excess particles when parallel cleanup is on. Remove If Missed Tick deletes a particle whose async task is interrupted before ticking. A per-render-type particle cap is also available.

Failures Per Second Threshold caps tick failures per particle class or end-tick operation per second; passing it triggers the failure behaviour rule. A related option ignores ConcurrentModificationException while under that limit.

Compatibility Fixes

Make 'ClassInstanceMultiMap' Thread-Safe and Make 'LevelChunk#blockEntities' Thread-Safe should be enabled if mods with non-standard particle implementations that reach entities or block entities cause crashes. Make 'LegacyRandomSource' Thread-Safe addresses crashes tied to that source, and Replace RandomSource suppresses concurrency crashes. Multi-Draw Workaround helps when crashes occur or particles fail to render.

For contraptions: Contraptions No Particle Collision disables particle collisions on certain contraption classes, rain effect timing on Create contraptions and on Valkyrien Skies ships can each be controlled, and Range of Rain Blocking Calculation sends blocking checks beyond the given X/Z distance through a slower fallback. Fix Particle Lights repairs ship particle lighting, while Fancy Particle Lights extends how far particles on sublevels receive light from them.

Synchronous tick lists let you name animation classes (subclasses of Block or Fluid) and particle classes to tick normally. Blacklists and group lists use their own entries; default entries cannot be deleted, and clearing every entry restores the defaults. A class that is missing or not a subclass is rejected.

When a block entity or entity is touched off the main thread, the mod warns you and points to the log. Errors during async particle ticking, async GPU particle ticking, or an incompatible injection each temporarily toggle a relevant setting internally and recommend enabling or disabling it manually, since otherwise the problem returns after a restart.