ParticleDrawing

English | 简体中文

A server-authoritative particle effects library for NeoForge. It plays the animations exported by the ParticleDrawing editor and exposes a Kotlin/Java API for drawing and animating particles directly from code.

Particles are created and owned by the server, while clients evaluate and render them locally. Declarative features such as choreographed groups, life curves and runtime emitters are sent once and evaluated on the client, so a running effect costs little to no per-tick bandwidth.

Features

• Play .pdrawc files from <gameDir>/animations/ with a command, or from code through ServerAnimationManager, including runtime variable updates.
• Draw lines, circles, discs, curves, polylines, triangles, hexagrams, rectangles, spheres and cuboids from code with Draw, with gradient coloring and per-particle entrance delays.
• Record a timeline of moves, rotations, scaling, pulses, color fades and expression- or entity-driven motion on a ParticleGroup; the client plays it back at render-frame rate.
• Declare a trail or an aura once as a runtime emitter and let each client emit along the anchor, per distance travelled or per interval, with deterministic per-particle jitter.
• Spawn up to 256 particle specs per packet, with automatic chunking for the bulk position, velocity, force and track operations.
• Use per-particle textures, sub-rectangle UVs, anisotropic sizes, fixed orientation, additive blending, built-in soft-dot/line shapes and PNG registration that syncs itself to clients, without a resource pack.
• Register effects with movable anchors, control their playback clock, play OGG/WAV audio and light particles dynamically.

Requirements

Installation

Players

1. Install NeoForge for Minecraft 26.2.
2. Put the mod jar into the mods/ folder, or install it from Modrinth.
3. Export an animation from the editor and place the .pdrawc file into <gameDir>/animations/.
4. Use the /pdraw command in game. Animations are loaded on demand, so the game does not have to be restarted after adding or replacing one.

Developers

The library is published to Maven Central:

// build.gradle.kts
dependencies {
    compileOnly("work.nekow:particledrawing:<version>")
    localRuntime("work.nekow:particledrawing:<version>")
}

Replace <version> with the newest release, shown by the Maven Central badge above or on Maven Central. To ship the library inside your own jar instead of requiring players to install it, use jarJar(implementation("work.nekow:particledrawing:<version>")).

Declare the dependency in META-INF/neoforge.mods.toml as well:

[[dependencies.${mod_id}]]
modId = "particledrawing"
type = "required"
ordering = "AFTER"

A minimal effect:

import net.minecraft.world.phys.Vec3
import work.nekow.particledrawing.api.Draw
import work.nekow.particledrawing.api.ParticleManager

val manager = ParticleManager.of(level)

Draw.circle(manager, Vec3(0.0, 70.0, 0.0), radius = 3.0, count = 80)
    .fadeIn(15)
    .spin(Vec3(0.0, 1.0, 0.0), Math.PI / 40)
    .delay(100)
    .stopContinuous()
    .fadeOut(20)

More in the getting started guide.

Commands

Documentation

Building from source

git clone https://github.com/NekoWs/ParticleDrawing.git
cd ParticleDrawing
./gradlew build          # compile and run the test suite
./gradlew runClient      # start a development client
./gradlew runServer      # start a development server

The build requires JDK 25. Runtime artifacts are written to build/libs/.

Releasing

mod_version in gradle.properties is the single source of truth. Whenever it changes, the same commit gets a matching tag (v<mod_version>). Pushing such a tag publishes the artifact to Maven Central through publish.yml and the version to Modrinth through modrinth.yml, which also syncs this README into the project body. Both workflows fail if the tag name does not match mod_version; there is no release without a tag.

License

Licensed under the Apache License 2.0.