Particlize

Particlize takes an entity’s rendered model and either scatters it into shards or assembles it from them. A profile decides how that looks: how long it runs, what the dissolve edge is tinted, how many shards fly off, and how much of it survives at distance. Profiles are resource-pack JSON, so an effect can be retuned without touching code. What plays at which moment is Entity FX.

Where the files live

assets/<namespace>/particlize_fx/<name>.json

One file is one profile, and its identifier is <namespace>:<name>. The bundled set lives under assets/isekaiexpansion/particlize_fx/ — twelve files, with base.json as the one every other profile inherits from.

Because these are assets rather than data, a resource pack overrides a profile the same way it overrides a texture: the pack highest in the list wins the whole file. There is no per-field merging between packs. Inheritance inside a profile is a different mechanism, described below.

Minimal example

Every field falls back to a built-in default, so the smallest accepted file is {}. The smallest useful one inherits and changes one thing:

{
  "extends": "isekaiexpansion:base",
  "surface": {
    "tint": "#7FE6FFFF"
  }
}

extends names another profile by identifier. The parent’s JSON is deep-merged with this file’s before anything is parsed: nested objects merge key by key, and any key present here replaces the parent’s. That is why the example above keeps every other surface setting from base.

Inheritance chains as far as you like, and a cycle is detected and reported rather than hanging.

Fields

The four objects are independent. Omit one and it takes its defaults whole; include it and only the keys you write are changed, the rest keeping their defaults or the parent’s values.

timeline

surface

The dissolve itself — the shader pass over the entity’s own geometry.

shards

The loose particles thrown off during the dissolve.

lod

Distance and complexity budget. These are the fields that decide whether a crowded fight stays playable.

The three distances and the three subdivision levels are each clamped in order, so a profile cannot describe a far distance nearer than its near distance, or a low level richer than its high one. Write them in a sensible order and the clamps never fire.

Validation

Nothing here throws at the player.

• A malformed or unparseable profile is logged as a warning naming the resource, and that one profile is dropped. Every other profile still loads.
• extends pointing at a profile that does not exist fails that profile the same way, with Unknown inherited profile in the log.
• A cycle in extends is detected while resolving and logged with the full path, rather than recursing until the client dies.
• An out-of-range number is clamped, not rejected. A count of 9999 becomes 512 and nothing tells you in game — check the log only for load failures, not for clamping.
• A non-finite number falls back to the low end of its range.
• An unknown enum name falls back: plane for shape, smoother_step for easing. Case and surrounding whitespace do not matter.
• If no profile loads at all, the registry keeps one entry — arcane_pulse mapped to the built-in default — so the renderer always has something rather than crashing on an empty map.

Asking the registry for an identifier it does not have returns nothing. That is a caller’s problem to handle, not a silent substitution.

Reloading

ParticlizeProfileRegistry is a client resource reload listener, so profiles reload with F3+T and with any resource pack change. Parsing happens off-thread and the parsed map is swapped in atomically, so an effect mid-play finishes with the profile it started with.

Nothing about profiles crosses the network. The server sends which profile id to play; the client resolves it from its own resource packs. Two players with different packs will correctly see different effects.

Playing a profile

Server-side, ParticlizeFxBroadcaster decides who sees the effect:

The seed argument makes a scatter reproducible: the same seed produces the same shard pattern on every client, which matters when two players compare a recording and not at all otherwise.

ParticlizeMode is DECOMPOSE, COMPOSE or PULSE. ParticlizePriority is AMBIENT, NORMAL, IMPORTANT or CRITICAL, and decides what survives when the client is over budget.

Client-side, ParticlizeFx starts an effect locally and returns a ParticlizeHandle for cancelling it. Use it only for something purely cosmetic and purely local; anything another player should see goes through the broadcaster.

Client config

Under particlize_fx in config/isekaiexpansion.json. All client-side: the server never enforces these.

Related

• Entity FX — which profile plays on death, teleport and respawn.
• Effekseer Particles — the other effect system, for authored emitters rather than entity dissolves.