Effects and particles

Effects are package data. An entity carries particle nodes inside a sequence. The sequence decides when each node plays, and each node names particle systems. A system names an emitter. The emitter runs a small bytecode program that spawns and moves particles. Lens flares are a separate, simpler route.

Class ids like 0x80806E28 are package classes. Function and field names are descriptive. Channel names such as particle_age and flow-node class names are the game’s own. Sunrise Studio draws this data. Its particle drawing is an approximation, and visual parity is unverified.

What places an effect

A map places effects in two ways. Both go through the map’s placement rows.

Every particle node in Leviathan and the EDZ sits in an entity component whose primary class is 0x808084D7, the sequence player.

Sequences

A sequence is a tree of two kinds of node: flow nodes, which decide order, and work nodes, which do something. A particle node is a work node of type 4.

The sequence player reads a sequence resource, class 0x808084E9:

A channel is an object variable. That an unset channel reads 0 is assumed.

The node header

A work node runs its delay, then its duration, or no timer at all. On timeout it ends and tells its parent. Work nodes have no start condition. There are 72 work node types. Type 4 is the particle node.

Particle nodes

A particle node is an inline struct inside an entity config, class 0x80806CC6, 296 bytes. Its body is the shared node header above. It adds:

No node field holds a position, rotation, scale or bone. The rows place the node; see “Particle locations”. A row can hold 0xFFFFFFFF instead of a system tag. Its config then lists several systems as variants, in the shape entity models use for material variants. How the runtime picks a variant is unverified.

Flow nodes

The type byte picks the class. Counts are over all 81,212 installed flow nodes.

A channel gate re-arms when its loop flag is set.

A condition is {u8 kind, f32 min, f32 max, i32 channel}:

Every installed flow start condition is kind 0. It is sampled when the node starts or restarts.

What starts a sequence

A node plays when its sequence plays and every flow node above it lets it through. A node under a loop flag restarts. A node with no timer runs until stopped. A node with neither plays once.

Of 15,786 installed sequences, 13,419 start on spawn. The channels most often gating a node closed at zero are alive, vehicle_power, device_position, emote_active, power_anim, damage_type, treasure_chest_looted and weapon_firing. An animation clip lists channel names. That a playing clip writes them is assumed.

Particle locations

A particle node places its systems through the sequence’s location table. Each node row holds a byte array of location indices and a particle-system tag. Row byte k gives the frames for emitter transform slot k.

Kinds 5 and 9 are not decoded. The empty-name hash 0x811C9DC5 gives the object transform. Source flag 0x80 rebuilds a frame upright while keeping its position.

Each source kind uses one flags value at source +4, with or without the 0x80 bit. The location’s own flag byte holds the same value. What each bit selects is not decoded.

Attachment points

An attachment point set belongs to the placed entity, not to the sequence. It holds 64-byte rows sorted by name hash, so several rows can share a name:

A name that repeats gives one frame per row. That is how an effect sits on both sides of an entity: two rows of one name, never a mirrored frame. A Hydra’s two primary_trigger rows put one muzzle effect on each gun.

Frames and instances

A location joins the frames of its sources up to its count. A point source gives one frame per row of its name, and skips a row whose enable bit is clear. A lookup that finds no row gives no valid frame.

A system runs one instance per valid spawn frame. Instance k takes spawn frame k, and simulation frame k while there are enough simulation frames, else the first one. A spawn location whose point is missing therefore emits nothing. Each instance emits at the full rate. That the count is not split is assumed.

CPU particles are stored in the simulation frame. So a system that spawns and simulates in one moving location keeps its particles with it. One that simulates in world_space leaves them where they spawned. This storage rule is unverified. The inherit_parent_velocity channel adds the parent’s velocity at spawn. A burst on a moving weapon point follows the gun in game when that channel is 0.

Particle systems

Class 0x80806E28 is the particle system. All 29,785 installed tags are 52 bytes.

About a quarter of systems simulate on the GPU with cs_5_0 compute shaders. The raster vertex shader reads per-particle data from vertex streams whose layout is not decoded.

Emitters

Class 0x80806E2C is the emitter: 26,250 installed tags, struct size 336.

The 55 channels follow a fixed name list in the executable, from particle_age to emitter_grid_count. The first ones are particle_age, particle_random, particle_system_age, particle_system_random, particle_emit_time, particle_lifetime, particle_position, particle_velocity, initial_particle_position, initial_particle_velocity, emission_rate, emitter_shape_scale, emitter_angle, emitter_radius, emitter_length, initial_speed, initial_particle_count and particle_max_count.

A channel record names a stream group and a float index into it. Group 0xFF marks an unused channel.

A transform slot below the node row’s byte count takes that row byte’s frames. A slot at or above it is a program slot: only the emitter program writes it. Program slots are common, most of all on GPU-simulated systems.

Emitter programs

The emitter program is the same kind of stack machine as the TFX interpreter on Rendering, over 32 vec4s. Opcodes 0x01 to 0x3B run the same math as TFX. The program is split into eight stages:

The emitter’s own opcodes include:

Byte 0x00, byte 0x3C and bytes above 0x52 end the stage. A transform is two vec4s: a rotation quaternion, then a position with uniform scale in W. On the stack the position sits under the rotation.

Load lane forms are xyzw, xyzz, xyxy, zwzw, xxxx, yyyy, zzzz and wwww. Store lane forms write all lanes, xyz, xy, the source XY into ZW, or the source X into one of X, Y, Z or W.

Random values come from s = 1664525 s + 1013904223, taking the high 16 bits over 65,535. The spawn samplers use the same generator. Extern float 0 is the wrapped simulation time, floats 1 to 4 are the other frame clock values, float 5 is 1/30 and float 6 is 1/60.

Spawn and update

Each frame adds emission_rate times the frame time to a carried fraction and spawns the whole part. initial_particle_count spawns once. particle_max_count caps the live total; zero means no cap. The system frame advances particle_system_age by the frame time over the system’s duration, clamped to 1.

A spawn runs in this order:

1. Set the particle’s age to 0 and write its emit time and spawn id.
2. Run stages 6 and 2.
3. Pick a point by the spawn shape and a direction by the spawn direction, scaled by initial_speed. Write them to initial_particle_position and initial_particle_velocity.
4. Run stage 3. Spawn programs usually copy the initial values into particle_position and particle_velocity.
5. Move position and velocity into the simulation space by the spawn frame. Add the parent’s velocity through inherit_parent_velocity.
6. Set the camera distances, a zero angular_position, and angular_velocity from initial_rotation_rate.

Each update advances the particle’s age by the frame time over particle_lifetime, clamped to 1, and runs stage 4. Then the native code integrates:

• gravity_strength times a system scale pulls along world -Z.
• Two accelerations add direction times strength times the frame time. A direction is in world space unless the emitter marks it as emitter-frame.
• air_friction times the frame time, clamped to 0 to 1, removes that share of the velocity.
• The position moves by the new velocity times the frame time.
• angular_velocity gains rotational_acceleration and loses its rotational_friction share. angular_position gains the velocity times 2 pi times the frame time, so the velocity is in turns.

The simulation space is the frame of slot +0x41. World directions and gravity are turned into it by the inverse of that slot.

Lens flares

A lens flare, class 0x80806F68, holds 12-byte rows: a material, a parameter block and a flag. The flare vertex shader builds a screen-space quad at a fixed clip depth of 0.99. The lens-flare role is assumed from that shader.

Counts

Open questions

• The helpers of opcodes 0x2B, 0x2D and 0x50, the gravity scale, and the writer of particle_random.
• The particle stream layout the raster shader reads, and the GPU path’s constant buffers.
• The runtime choice between particle-system variants.
• Which gameplay code plays the sequences that do not start on spawn.
• Who writes the gate channels, and condition kinds 1 and 3.
• Location kinds 5, 9 and 13 to 25, and the meaning of the location and source flag bits.
• Which skeleton a point’s node index counts in.
• Where missing point hashes such as 0x60FECDD4 live at run time.

Related pages

• Rendering – TFX, materials and object channels.
• Weapons and perks – muzzle flashes and clip events.