Skip to content
Hytale Modding Manual

Particles

Overview

Hytale’s particle system uses two file types that work together: particle systems (.particlesystem) compose one or more spawner references into a complete effect, and particle spawners (.particlespawner) define the individual emitter behaviour — emission rate, velocity, lifetime, texture, colour animation, attractors, and collision. Particle system JSON files can also use the .json extension for complex multi-spawner effects. The engine loads these at runtime to produce visual effects for block interactions, combat hits, weather, NPC abilities, and deployable objects.

File Location

Assets/Server/Particles/
  Block/
    Block_Top_Glow.particlesystem
    Block_Top_Glow_Alpha.particlespawner
    Clay/
      Block_Break_Clay.particlesystem
      Block_Hit_Clay.particlesystem
    Crystal/
    Stone/
    Wood/
  Combat/
  Deployables/
    Healing_Totem/
      Totem_Heal_Simple_Test.json
    Slowness_Totem/
  Drop/
  Dust_Sparkles_Fine.particlesystem
  Dust_Sparkles_Fine.particlespawner
  Explosion/
  Item/
  Memories/
  NPC/
  Projectile/
  Spell/
  Status_Effect/
  Weapon/
  Weather/
  _Example/

Schema

Particle System (.particlesystem / .json)

FieldTypeRequiredDefaultDescription
SpawnersSpawnerRef[]Yes—Array of spawner references that make up this particle effect.
LifeSpannumberNo—Total duration in seconds before the entire system is destroyed. Omit for infinite-duration effects.
CullDistancenumberNo—Distance in blocks beyond which the particle system is not rendered.
BoundingRadiusnumberNo—Radius used for frustum culling.
IsImportantbooleanNofalseWhen true, the system is never culled by the particle budget.

SpawnerRef

FieldTypeRequiredDefaultDescription
SpawnerIdstringYes—ID of the particle spawner to use. Resolves to a .particlespawner file by name.
PositionOffsetVector3No{0,0,0}Position offset from the system origin. Only specified axes are overridden.
FixedRotationbooleanNotrueWhen false, particles rotate with the emitting entity.
StartDelaynumberNo0Seconds to wait before this spawner begins emitting.
WaveDelayMinMaxNo—Random delay range between emission waves.

Particle Spawner (.particlespawner)

FieldTypeRequiredDefaultDescription
RenderModestringNo—Rendering mode: "Erosion", "Additive", "AlphaBlend", etc.
EmitOffsetVector3MinMaxNo—Random offset range for particle spawn position on each axis.
ParticleRotationInfluencestringNo—How particle rotation is computed: "Billboard" (faces camera), "Velocity", etc.
LinearFilteringbooleanNofalseUse bilinear texture filtering instead of nearest-neighbour.
LightInfluencenumberNo1.0How much scene lighting affects particle colour (0 = unlit, 1 = fully lit).
MaxConcurrentParticlesnumberNo0Maximum number of live particles. 0 means unlimited.
ParticleLifeSpanMinMaxNo—Random range for individual particle lifetime in seconds.
ParticleRotateWithSpawnerbooleanNofalseWhether particles inherit the spawner’s rotation.
SpawnRateMinMaxNo—Milliseconds between particle emissions (randomized within range).
InitialVelocityVelocityConfigNo—Initial velocity in spherical coordinates.
AttractorsAttractor[]No[]Point attractors that pull particles.
ParticleParticleConfigYes—Texture, animation keyframes, and initial state.
ParticleCollisionobjectNo—Collision settings for particles hitting blocks.

VelocityConfig

FieldTypeRequiredDefaultDescription
YawMinMaxNo—Random yaw angle range in degrees.
PitchMinMaxNo—Random pitch angle range in degrees.
SpeedMinMaxNo—Random speed range in blocks per second.

Attractor

FieldTypeRequiredDefaultDescription
PositionVector3Yes—Attractor position relative to the spawner.
RadialAxisVector3No—Axis for radial acceleration.
RadiusnumberNo0Attractor influence radius.
RadialAccelerationnumberNo0Inward (negative) or outward (positive) radial force.
RadialTangentAccelerationnumberNo0Tangential force perpendicular to the radial direction.
LinearAccelerationVector3No—Constant linear acceleration (e.g. gravity).

ParticleConfig

FieldTypeRequiredDefaultDescription
TexturestringYes—Path to the particle texture image.
FrameSize{ Width, Height }No—Size of a single frame in a sprite sheet texture.
ScaleRatioConstraintstringNo—"OneToOne" locks X and Y scale together.
AnimationobjectNo—Keyframe map where keys are lifetime percentages ("0", "50", "100").
InitialAnimationFrameobjectNo—Starting values for rotation, scale, opacity, and frame index.

Animation Keyframe

Each key in the Animation object is a lifetime percentage (0–100). Values at each keyframe:

FieldTypeDescription
FrameIndexMinMaxSprite sheet frame index range.
Scale{ X: MinMax, Y: MinMax }Scale at this point in the particle’s life.
Rotation{ X: MinMax, Y: MinMax, Z: MinMax }Rotation in degrees.
OpacitynumberOpacity from 0 (invisible) to 1 (fully opaque).
ColorstringHex colour tint at this keyframe.

MinMax

FieldTypeDescription
MinnumberMinimum value of the random range.
MaxnumberMaximum value of the random range.

Examples

Simple particle system (Assets/Server/Particles/Dust_Sparkles_Fine.particlesystem):

{
  "Spawners": [
    {
      "SpawnerId": "Dust_Sparkles_Fine",
      "FixedRotation": true,
      "WaveDelay": { "Min": 4, "Max": 36 }
    },
    { "SpawnerId": "Dust_Sparkles_Fine" },
    { "SpawnerId": "Dust_Sparkles_Fine" }
  ],
  "CullDistance": 30
}

Multi-spawner effect with delays (Assets/Server/Particles/Deployables/Healing_Totem/Totem_Heal_Simple_Test.json):

{
  "Spawners": [
    { "SpawnerId": "Totem_Heal_Ground_Line",      "PositionOffset": { "Z": 0 }, "FixedRotation": false, "StartDelay": 1.2 },
    { "SpawnerId": "Totem_Heal_Uhr",              "PositionOffset": { "Y": 0.1 }, "StartDelay": 0.8 },
    { "SpawnerId": "Totem_Heal_Ground_Constant",   "PositionOffset": { "Z": 0 }, "FixedRotation": false, "StartDelay": 0.5 },
    { "SpawnerId": "Totem_Heal_Sparks_Constant",   "PositionOffset": { "Y": 0.5 }, "StartDelay": 0.5 }
  ],
  "LifeSpan": 9,
  "CullDistance": 100
}