Particle Script
|
This file format is almost completely documented Details are subject to corrections |
Retro games feature a uniform, fixed-function Effect Script system for describing various geometrical effects and weapon systems. The PAK archives contain binary resources using FourCCs to build a key-value dictionary. These codes correspond to application-specific parameters controlling the effect system in question.
The binary script format uses a grammar that supports bool, int, float, float3, and float4
parameters to be evaluated and assigned to the dictionary. In addition, the various effect systems provide dynamic node classes that are evaluated as part of the effect runtime.
Ultimately, the systems use a recursive, node-based approach of generating animated scalar and vector values to control the effect.
File Layout
All effect script file formats use a context-sensitive, free-form layout to build the key-value dictionary.
- Script Magic FourCC (see table below)
- Entries
- Key FourCC (see script-format articles)
- Value Parameter(s) (one of:)
CNST: Bool/Scalar/Vector literal- bool/int/float/float3/float4 value
NONE: Dummy value (equivalent to not specifying the key at all)- Node Key (see below)
- Node Parameters
_END
Script Types
| Type | Magic | Purpose |
|---|---|---|
| PART | GPSM
|
Particle effect |
| SWHC | SWSH
|
Swoosh effect |
| ELSC | ELSM
|
Electric effect |
| DPSC | DPSM
|
Decal effect |
| WPSC | WPSM
|
Projectile weapon configuration |
| CRSC | CRSM
|
Projectile collision response configuration |
Script Nodes
Many of the animated qualities in effect scripts are achieved with dynamic script nodes. These nodes provide parameter I/O interfaces and internally process numeric data that passes through. They may also gather data from other sources within the effect system.
Scope is one of (Constant, System, Particle, Auto)
- Constant parameters are evaluated once initially and retained within the system.
- System parameters are evaluated per-system, per-frame.
- Particle parameters are evaluated per-system, per-frame, per-particle-instance.
- Auto parameters select their scope based on the node's parent context.
| Signature | Scope | Description | Notes |
|---|---|---|---|
SETR(ILOC=float3 location_vector, IVEC=float3 velocity_vector)
|
System | Point emitter | Used with EMTR attachment to produce particle instances
|
SEMR(float3 location_vector, float3 velocity_vector)
|
System | Point emitter | Seems to be similar to SETR
|
SPHE(float3 local_sphere_origin, float radius, float radial_velocity)
|
System | Sphere emitter | Emits particles from a sphere-surface |
ASPH(float3 local_sphere_origin, float x_ang_bias, float y_ang_bias, float x_ang_range, float y_ang_range, float radius, float radial_velocity)
|
System | Partial sphere emitter | Emits particles from a sphere-surface section |
float SCAL(float value)
|
Particle | Linear-lifetime interpolator | Interpolates from 0.0 to value over particle's lifetime
|
int/float/float3/float4 ADD(int/float/float3/float4 a, int/float/float3/float4 b)
|
Auto | Value adder | Dynamically adds two parameters |
int/float/float3/float4 SUB(int/float/float3/float4 a, int/float/float3/float4 b)
|
Auto | Value subtractor | Dynamically subtracts two parameters |
int/float/float3/float4 MULT(int/float/float3/float4 a, int/float/float3/float4 b)
|
Auto | Value multiplier | Dynamically multiplies two parameters |
float CLMP(float low, float high, float val)
|
Auto | Value clamp | Dynamically clamps val between low and high
|
int RLPT(float lifetime_percent)
|
Particle | Resolve frame-index from lifetime percentage | Computes the frame on which the particle will reach a specified lifetime-percent (0-100) |
float ISWT(float c, float v)
|
Auto | Linear equation evaluator | Evaluates v * frame_index + c
|
int/float RAND(int/float low, int/float high)
|
System | Pseudo-random number generator | Generates a random number between low and high
|
int/float IRND(int/float low, int/float high)
|
Particle | Instance-cached pseudo-random number generator | Generates a random number between low and high and retains the value for each particle instance
|
float LFTW(float a, float b)
|
Particle | Triangle-wave generator | Generates a triangle-wave cycle over the particle instance's lifetime. Evaluates a at 0% lifetime, b at 50% lifetime, then back to a at 100% lifetime
|
int/float/float3/float4 CHAN(int/float/float3/float4 a, int/float/float3/float4 b, int f)
|
Particle | Time-based parameter switch | Evaluates a before particle instance reaches frame index f; evaluates b afterwards
|
float3 RTOV(float val)
|
Auto | Scalar to vector (vector splat) | Constructs a 3-component vector using val for each component
|
int/float/float3/float4 PULS(int pulse_start_frame, int pulse_frame_count, int/float/float3/float4 a, int/float/float3/float4 b)
|
Particle | Pulsing duty-cycle switch (periodic CHAN)
|
Evaluates a until pulse_start_frame is reached, then evaluates b for pulse_frame_count frames. This cycle repeats indefinitely
|
float SINE(float magnitude, float v, float c)
|
Auto | Animated sine function | v and c are in degrees. Evaluates sin(v * frame_index + c) * magnitude
|
int/float/float3/float4 KEYE(<key-array>)
|
System | Emitter-based key array | Stores an array of values; one for each frame of the emitter's lifetime; with clamped-extrapolation |
int/float/float3/float4 KEYP(<key-array>)
|
Particle | Particle-based key array | Stores an array of 100 values; one for each percentage point of the particle instance's lifetime |
float PAPn()
|
Auto | ADVn access token (1-8)
|
Access the value evaluated for one of the ADVn keys in the particle system
|
float PSLL()
|
– | – | – |
float PRLW()
|
– | – | – |
float PSOF()
|
– | – | – |
float VMAG(float3 v)
|
Auto | Vector magnitude calculator | Evaluates sqrt(v.x^2 + v.y^2, v.z^2)
|
float CLTN(float ca, float cb, float a, float b)
|
Auto | Less-than evaluator switch | If ca < cb then evaluates a, else b
|
float CEQL(float ca, float cb, float a, float b)
|
Auto | Equal evaluator switch | If ca == cb then evaluates a, else b
|
float VXTR(float3 vec)
|
Auto | X component of vector | Extracts X component of vector |
float VYTR(float3 vec)
|
Auto | Y component of vector | Extracts Y component of vector |
float VZTR(float3 vec)
|
Auto | Z component of vector | Extracts Z component of vector |
float CEXT(int val)
|
– | – | – |
float ITRL(float val)
|
– | – | – |
float GTCP(int val)
|
– | – | – |
float MODU(float numerator, float denominator)
|
Auto | Floating-point modulo | Dynamically evaluates remainder-division as numerator % denominator
|
int ILPT(int val)
|
Particle | Clamp to particle frame-count | Clamps val to count of frames in particle instance
|
float4 FADE(float4 a, float4 b, float t)
|
Particle | Time-based (0-end) linear interpolator | Interpolates from a to b over particle instance's first t frames
|
float4 CFDE(float4 a, float4 b, float s, float e)
|
Particle | Time-based (start-end) linear interpolator | Interpolates from a to b between particle instance's s and e frames
|
float3 ANGC(float x_bias, float z_bias, float x_ang, float z_ang, float magnitude)
|
Auto | Spherical-section random vector generator | Generates a vector of magnitude adhering to the XZ-angular constraints provided
|
float3 CIRC(float3 circle_offset, float3 circle_normal, float angle_bias, float angle_range, float magnitude)
|
Auto | Circular-section random vector generator | Generates a vector of magnitude adhering to the circular constraints provided
|
float3 CONE(float3 cone_vector, float base_radius)
|
Auto | Cone random vector generator | Generates a random vector from the cone's tip to somewhere within its base |
WIND(float3 wind_vector, float drift_magnitude)
|
Particle | Wind velocity source | Integrates a non-accelerated force simulating directional wind with a randomized drift |
GRAV(float3 grav_vector)
|
Particle | Gravity velocity source | Integrates a continuously-accelerated force simulating gravitational pull |
SWRL(float3 helix_start, float3 helix_end, float angular_vel, float linear_vel)
|
Particle | Swirl velocity source | Integrates a helically-shaped force simulating a 'swirling' motion |
BNCE(float3 plane_point, float3 plane_normal, float ?, float ?, bool ?)
|
Particle | Bounce velocity source | Establishes a local plane in the system for particles to bounce off |
EXPL(float initial_velocity, float velocity_damping)
|
Particle | Explosion velocity source | Moves particle away from emitted position at initial_velocity while continuously applying velocity_damping
|
IMPL(float3 implosion_point, float force, float ?, float ?, bool ?)
|
Particle | Implosion velocity source? | – |
EMPL(float3 point, float force, float ?, float ?, bool ?)
|
Particle | – | – |
LMPL(float3 point, float force, float ?, float ?, bool ?)
|
Particle | – | – |
float3 SPOS(float3 vec)
|
Particle | Position delta | Subtract from current particle instance position |
float3 PLCO()
|
Particle | World Position | Evaluate particle world position |
float3 PLOC()
|
Particle | Local Position | Evaluate particle local (emitter-space) position |
ATEX(int seg_w, int seg_h, int ?, int ?, int frame_rate, bool loop)
|
Particle | Animated texture attachment | Used in particle script's TEXR key to apply a UV-scanned animated texture
|