Particles

Package: com.hypixel.hytale.server.core.universe.world.ParticleUtil

Defining custom particles?

To create particle assets in JSON packs (ParticleSystem/ParticleSpawner definitions, block particle sets), see Adding Particles.

Particles are spawned by sending packets to nearby players. The ParticleUtil utility class provides static methods for spawning particle systems at world positions with optional rotation, scale, and color overrides.

Spawning Particles

Particle systems are identified by string IDs (e.g., "Hytale/DirtBreak"). Unlike sounds, particles use string IDs directly rather than integer indices.

Broadcast to Nearby Players

The simplest overload auto-collects all players within 75 blocks and sends the packet:

Vector3d position = new Vector3d(x, y, z);
ParticleUtil.spawnParticleEffect("Hytale/DirtBreak", position, componentAccessor);

This is the only overload that auto-broadcasts. All other overloads require you to pass a player list explicitly.

To a Specific Player List

// collect players manually (e.g., custom range)
List<Ref<EntityStore>> players = new ArrayList<>();
SpatialResource<Ref<EntityStore>, EntityStore> spatial =
    componentAccessor.getResource(EntityModule.get().getPlayerSpatialResourceType());
spatial.getSpatialStructure().collect(position, 100.0, players);  // 100 block range

ParticleUtil.spawnParticleEffect("MyMod/LargeEffect", position, players, componentAccessor);

Excluding a Player

Exclude one player from receiving the particle (e.g., the attacker in a damage effect):

ParticleUtil.spawnParticleEffect("MyMod/HitEffect", position,
    sourceRef, playerRefsList, componentAccessor);

With Rotation, Scale, and Color

When you need rotation, scale, or color overrides, use the full overload. Rotation values are in radians.

ParticleUtil.spawnParticleEffect("MyMod/MagicBurst",
    x, y, z,
    yaw, pitch, roll,   // radians
    1.5f,                // scale (default: 1.0)
    new Color((byte) 255, (byte) 100, (byte) 50),  // color override (null = no override)
    sourceRef,           // player to exclude (null = no exclusion)
    playerRefsList,
    componentAccessor);

You can also pass rotation as a Vector3f:

Vector3f rotation = new Vector3f(yaw, pitch, roll);
ParticleUtil.spawnParticleEffect("MyMod/Effect", position, rotation, playerRefsList, componentAccessor);

WorldParticle

WorldParticle is a config object that bundles a particle system ID with overrides (color, scale, position/rotation offset). It’s used in gameplay configs like SpawnConfig and DamageEffects.

// spawn from a WorldParticle config
ParticleUtil.spawnParticleEffect(worldParticle, position, playerRefsList, componentAccessor);

// spawn multiple WorldParticles at once
ParticleUtil.spawnParticleEffects(worldParticleArray, position, sourceRef, playerRefsList, componentAccessor);

PositionOffset in WorldParticle is relative to the rotation — it gets rotated by the yaw/pitch/roll before being applied to the position. RotationOffset values in JSON are in degrees (converted to radians internally).

{
  "SystemId": "MyMod/SpawnEffect",
  "Color": { "red": 255, "green": 200, "blue": 100 },
  "Scale": 1.5,
  "PositionOffset": { "x": 0, "y": 0.5, "z": 0 },
  "RotationOffset": { "yaw": 0, "pitch": 0, "roll": 0 }
}

Block Particles

Block particles are handled separately through WorldNotificationHandler and use block-specific BlockParticleSet assets. These are sent to all players who have the chunk loaded (different targeting than ParticleUtil’s spatial query).

Block particle events: Walk, Run, Sprint, SoftLand, HardLand, MoveOut, Hit, Break, Build, Physics.

Model Particles

Particles can be attached to entity models via the SpawnModelParticles packet. These are defined in ModelParticle configs and follow the entity’s skeleton.

TargetEntityPart values: Self, Entity, PrimaryItem, SecondaryItem.

Particle System Assets

Particle effects are defined as two asset types: ParticleSystem (.particlesystem) groups spawners into an effect, and ParticleSpawner (.particlespawner) controls individual particle behavior. See Adding Particles for full JSON schemas and examples.

Packets

Particle spawning is packet-based (S->C). See packet reference for field details: SpawnParticleSystem, SpawnBlockParticleSystem, SpawnModelParticles.