Adding Particles

Basics

Particle effects use a two-file system: ParticleSystem (.particlesystem) defines the overall effect by referencing one or more ParticleSpawner (.particlespawner) assets that control individual particle behavior.

Pack location: Server/Particles/
Base game reference: Assets.zip/Server/Particles/

Server/Particles/
├── My_Effect.particlesystem     # groups spawners into an effect
├── My_Smoke.particlespawner     # defines how particles look and move
└── textures/
    └── smoke.png                # particle texture

ParticleSystem

The top-level asset that groups spawners into a complete effect.

{
  "Spawners": [
    {
      "SpawnerId": "MyMod/Smoke_Spawner",
      "PositionOffset": { "x": 0, "y": 0.5, "z": 0 },
      "RotationOffset": { "yaw": 0, "pitch": 0, "roll": 0 },
      "StartDelay": 0.0,
      "TotalSpawners": 1,
      "MaxConcurrent": 0
    }
  ],
  "LifeSpan": 3.0,
  "CullDistance": 100.0,
  "BoundingRadius": 2.0,
  "IsImportant": false
}

Field	Type	Default	Description
`Spawners`	array	—	Array of spawner group references
`LifeSpan`	float	—	Total system lifetime (seconds)
`CullDistance`	float	`100.0`	Distance beyond which the effect is culled
`BoundingRadius`	float	`2.0`	Bounding sphere radius for culling
`IsImportant`	boolean	`false`	Prevents culling when true

Spawner Group

Each entry in Spawners references a ParticleSpawner and adds positioning:

Field	Type	Default	Description
`SpawnerId`	string	—	ParticleSpawner asset ID
`PositionOffset`	Vector3	`0, 0, 0`	Position offset from system origin
`RotationOffset`	Vector3	`0, 0, 0`	Rotation offset (yaw, pitch, roll)
`FixedRotation`	boolean	`false`	Ignore system rotation
`StartDelay`	float	`0.0`	Delay before this spawner starts (seconds)
`TotalSpawners`	int	`1`	Number of spawner instances
`MaxConcurrent`	int	`0`	Max concurrent instances (0 = unlimited)

Combining Spawners

A single system can use multiple spawners for layered effects:

{
  "Spawners": [
    {
      "SpawnerId": "MyMod/Fire_Core",
      "TotalSpawners": 1
    },
    {
      "SpawnerId": "MyMod/Fire_Sparks",
      "PositionOffset": { "x": 0, "y": 0.3, "z": 0 },
      "StartDelay": 0.1,
      "TotalSpawners": 3
    },
    {
      "SpawnerId": "MyMod/Fire_Smoke",
      "PositionOffset": { "x": 0, "y": 1.0, "z": 0 },
      "StartDelay": 0.5
    }
  ],
  "LifeSpan": 5.0
}

ParticleSpawner

Controls how individual particles look, move, and behave.

Emission

{
  "Shape": "Sphere",
  "EmitOffset": {
    "Min": { "x": -0.5, "y": 0, "z": -0.5 },
    "Max": { "x": 0.5, "y": 0, "z": 0.5 }
  },
  "TotalParticles": { "min": 10, "max": 20 },
  "SpawnRate": { "min": 5.0, "max": 10.0 },
  "SpawnBurst": false,
  "LifeSpan": 3.0,
  "ParticleLifeSpan": { "min": 1.0, "max": 2.0 },
  "MaxConcurrentParticles": 50
}

Field	Type	Description
`Shape`	enum	Emit shape: `Sphere` or `Cube`
`EmitOffset`	RangeVector3	Random spawn offset range
`UseEmitDirection`	boolean	Emit in the direction of the emit offset
`TotalParticles`	Range	Min/max total particles to emit
`SpawnRate`	Rangef	Particles per second
`SpawnBurst`	boolean	Emit all particles at once
`LifeSpan`	float	Spawner lifetime (seconds)
`ParticleLifeSpan`	Rangef	Individual particle lifetime (seconds)
`MaxConcurrentParticles`	int	Max alive particles at once

Movement

{
  "InitialVelocity": {
    "Min": { "x": -1, "y": 2, "z": -1 },
    "Max": { "x": 1, "y": 5, "z": 1 }
  },
  "VelocityStretchMultiplier": 0.5
}

Rendering

Field	Type	Description
`RenderMode`	enum	`BlendLinear`, `BlendAdd`, `Erosion`, `Distortion`
`ParticleRotationInfluence`	enum	`None`, `Billboard`, `BillboardY`, `BillboardVelocity`, `Velocity`
`ParticleRotateWithSpawner`	boolean	Rotate particles with the spawner
`LightInfluence`	float	How much world lighting affects particles (0-1)
`VelocityStretchMultiplier`	float	Stretches particles along velocity
`CameraOffset`	float	Offset toward camera (prevents z-fighting)

Collision

{
  "ParticleCollision": {
    "BlockType": "Solid",
    "Action": "Expire",
    "ParticleRotationInfluence": "None"
  }
}

Field	Values	Description
`BlockType`	`None`, `Air`, `Solid`, `All`	What blocks trigger collision
`Action`	`Expire`, `LastFrame`, `Linger`	What happens on collision
`ParticleRotationInfluence`	`None`, `Billboard`, etc.	Rotation after collision

Attractors

Pull or push particles toward a point:

{
  "Attractors": [
    {
      "Position": { "x": 0, "y": 2, "z": 0 },
      "Radius": 3.0,
      "RadialAcceleration": 5.0,
      "Damping": 0.1
    }
  ]
}

Particle Visual

Each spawner contains a Particle definition for the visual appearance:

{
  "Particle": {
    "Texture": "Particles/textures/smoke.png",
    "FrameSize": { "width": 64, "height": 64 },
    "SoftParticles": "Enable",
    "SoftParticlesFadeFactor": 1.0,
    "ScaleRatioConstraint": "OneToOne",
    "Animation": {
      "0": {
        "Scale": {
          "Min": { "x": 0.5, "y": 0.5 },
          "Max": { "x": 1.0, "y": 1.0 }
        },
        "Color": { "red": 255, "green": 200, "blue": 100 },
        "Opacity": 1.0
      },
      "50": {
        "Scale": {
          "Min": { "x": 1.5, "y": 1.5 },
          "Max": { "x": 2.0, "y": 2.0 }
        },
        "Opacity": 0.5
      },
      "100": {
        "Opacity": 0.0
      }
    }
  }
}

Animation keyframes are keyed by percentage (0-100) of the particle’s lifetime. Each keyframe can set:

Field	Type	Description
`FrameIndex`	Range	Texture frame index (for sprite sheets)
`Scale`	RangeVector2	Particle size
`Rotation`	RangeVector3	Particle rotation
`Color`	RGB	Particle color
`Opacity`	float	Particle opacity (0.0-1.0)

Particle Property	Values	Description
`SoftParticles`	`Enable`, `Disable`, `Require`	Soft edge rendering against geometry
`ScaleRatioConstraint`	`OneToOne`, `Preserved`, `None`	Scale aspect ratio lock
`UVOption`	`None`, `RandomFlipU`, `RandomFlipV`, `RandomFlipUV`, `FlipU`, `FlipV`, `FlipUV`	UV randomization
`UseSpriteBlending`	boolean	Blend between sprite frames

Block Particle Sets

Map block events to particle system IDs. Each block type can reference a BlockParticleSet.

Pack location: Server/Item/Block/Particles/

{
  "Color": { "red": 200, "green": 180, "blue": 140 },
  "Scale": 1.0,
  "PositionOffset": { "x": 0, "y": 0, "z": 0 },
  "RotationOffset": { "yaw": 0, "pitch": 0, "roll": 0 },
  "Particles": {
    "Walk": "Hytale/Dirt_Walk",
    "Run": "Hytale/Dirt_Run",
    "Sprint": "Hytale/Dirt_Sprint",
    "SoftLand": "Hytale/Dirt_SoftLand",
    "HardLand": "Hytale/Dirt_HardLand",
    "MoveOut": "Hytale/Dirt_MoveOut",
    "Hit": "Hytale/Dirt_Hit",
    "Break": "Hytale/Dirt_Break",
    "Build": "Hytale/Dirt_Build",
    "Physics": "Hytale/Dirt_Physics"
  }
}

Block particle events:

Event	When it plays
`Walk`	Player walks on the block
`Run`	Player runs on the block
`Sprint`	Player sprints on the block
`SoftLand`	Player lands softly on the block
`HardLand`	Player lands hard on the block
`MoveOut`	Entity leaves the block’s space
`Hit`	Block is hit (mining)
`Break`	Block is broken
`Build`	Block is placed
`Physics`	Block physics event

Model Particles

Particles attached to entity models. Defined in model configs and follow the entity’s skeleton:

{
  "SystemId": "MyMod/Aura_Effect",
  "TargetEntityPart": "Self",
  "TargetNodeName": "chest",
  "Color": { "red": 200, "green": 255, "blue": 200 },
  "Scale": 1.0,
  "PositionOffset": { "x": 0, "y": 0, "z": 0 },
  "RotationOffset": { "yaw": 0, "pitch": 0, "roll": 0 },
  "DetachedFromModel": false
}

Field	Type	Description
`SystemId`	string	ParticleSystem asset ID
`TargetEntityPart`	enum	`Self`, `Entity`, `PrimaryItem`, `SecondaryItem`
`TargetNodeName`	string	Skeleton bone/node to attach to
`DetachedFromModel`	boolean	If true, spawns at position but doesn’t follow

WorldParticle

A reusable config object that bundles a particle system ID with overrides. Used in GameplayConfig for spawn effects, damage effects, and gathering effects.

{
  "SystemId": "MyMod/Spawn_Effect",
  "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 }
}

See Spawning config for FirstSpawnParticles and SpawnParticles.

Using Particles in Other Assets

In Projectiles

{
  "DeathParticles": { "SystemId": "MyMod/Impact_Fire" }
}

In Interactions

{
  "Effects": {
    "ParticleSystemId": "MyMod/Slash_Effect"
  }
}

In NPC Behaviors

{
  "Type": "SpawnParticles",
  "ParticleSystem": "MyMod/NPC_Spawn_Effect",
  "Range": 75.0,
  "Offset": { "x": 0, "y": 1, "z": 0 }
}

File Locations

What	Your Pack	Base Game Reference
Particle systems (.particlesystem)	`Server/Particles/`	`Assets.zip/Server/Particles/`
Particle spawners (.particlespawner)	`Server/Particles/`	`Assets.zip/Server/Particles/`
Particle textures	`Server/Particles/textures/`	`Assets.zip/Server/Particles/textures/`
Block particle sets	`Server/Item/Block/Particles/`	`Assets.zip/Server/Item/Block/Particles/`