Difference between revisions of "Particle Script"

From Retro Modding Wiki
Jump to: navigation, search
(ITRL and GTCP corrections)
m (Jackoalan moved page Effect Script to Particle Script: "Particle" is the canonical encompassing term (CParticleGen being the relevant superclass))
(No difference)

Revision as of 14:39, 27 February 2016

Morphball render.png 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(int a, float b) – – –
int GTCP() – – –
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
Retrieved from "http://www.metroid2002.com/retromodding/index.php?title=Particle_Script&oldid=1288"