User:Jackoalan/Particle Script

This file format is almost completely documented Details are subject to corrections

Retro games feature a uniform, fixed-function Particle 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 system in question.

The scripts use a dataflow paradigm built around value-generating element classes of the following types:

• Int
• Real (float)
• Vector (3-component float)
• Mod Vector (3-component float)
  • Velocity vector in/out
  • Position vector in/out
• Color (4-component float, internally converted to RGBA8)
• UV (TXTR reference and UV coordinate source)
• Emitter
  • Initial position vector (3-component float)
  • Initial velocity vector (3-component float)

The system features several subclasses that output generated values through GetValue as a function of the current frame index. These implementations may recursively accept input from other elements, permitting effect designs of scalable complexity.

File Layout

All effect script file formats are read linearly to populate a descriptor tree of element nodes:

• Script Magic FourCC (see table below)
• Parameters
  • Key FourCC
  • Value Parameter(s) (one of:)
    • NONE: null value (equivalent to not specifying the key at all)
    • Element FourCC (see below)
      • Child Elements (count/types according to parent)
• _END

Script Types

Type	Magic	Purpose
PART	GPSM	Particle element generator
SWHC	SWSH	Swoosh generator
ELSC	ELSM	Electric generator
DPSC	DPSM	Decal generator
WPSC	WPSM	Projectile weapon configuration
CRSC	CRSM	Projectile collision response configuration

Elements

Many of the animated qualities in particle scripts are achieved with dynamic elements. These elements provide I/O interfaces and internally process numeric data that passes through. They may also gather data from other sources within the particle system's state.

Int Elements

FourCC	Parameters	Description	Notes	MP1	MP2	MP3	DKCR	DKCTF
ADD_	(IntElement a, IntElement b)	Add	Returns a + b	✔	✔	✔	✔	✔
CHAN	(IntElement a, IntElement b, IntElement thresholdFrame)	Time Chain	Returns a when current frame index is less-than thresholdFrame, otherwise b	✔	✔	✔	✔	✔
CLMP	(IntElement min, IntElement max, IntElement val)	Clamp	Returns val clamped between min and max	✔	✔	✔	✔	✔
CNST	(s32 value)	Constant	Returns value on every call	✔	✔	✔	✔	✔
DETH	(IntElement passthrough, IntElement thresholdFrame)	Death	Always returns passthrough, and signals out-of-band to cease updating the system when the current frame index exceeds thresholdFrame	✔	✔	✔	✔	✔
GAPC	()	Unknown		✔	✔	✔	✔	✔
GEMT	()	Unknown		✔	✔	✔	✔	✔
GTCP	()	Unknown		✔	✔	✔	✔	✔
ILPT	(IntElement percent)	Lifetime Percent	Queries the frame index at percent/100.0 into the lifetime of the particle instance	✔	✔	✔	✔	✔
IMPL	(IntElement val)	Impulse	Returns val ONLY at frame index 0, then returns 0 for subsequent frames	✔	✔	✔	✔	✔
IRND	(IntElement a, IntElement b)	Initial Random	Rolls a random value between a and b on frame index 0; returns that value for subsequent frames	✔	✔	✔	✔	✔
KEYE	(KeyframeEmitterData data)	Keyframe Emitter	List of synchronized animation keys	✔	✔	✔	✔	✔
KEYP	(KeyframeEmitterData data)	Keyframe Emitter	List of percentage-tweened animation keys	✔	✔	✔	✔	✔
MODU	(IntElement a, IntElement b)	Modulo	Returns a % b	✔	✔	✔	✔	✔
MULT	(IntElement a, IntElement b)	Multiply	Returns a * b	✔	✔	✔	✔	✔
PULS	(IntElement aDuration, IntElement bDuration, IntElement a, IntElement b)	Pulse	Returns a for aDuration frames then b for bDuration frames, then repeats this cycle	✔	✔	✔	✔	✔
RAND	(IntElement a, IntElement b)	Random	Rolls a random value between a and b	✔	✔	✔	✔	✔
SPAH	(IntElement val, IntElement waitMin, IntElement waitMax)	Sample And Hold	Stores val for a random count of frames between waitMin and waitMax and repeats this cycle	✔	✔	✔	✔	✔
SUB_	(IntElement a, IntElement b)	Subtract	Returns a - b	✔	✔	✔	✔	✔
TSCL	(RealElement dv)	Time Scale	Returns dv times the current frame index (rounding down to nearest integer)	✔	✔	✔	✔	✔

Real Elements

FourCC	Parameters	Description	Notes	MP1	MP2	MP3	DKCR	DKCTF
ADD_	(RealElement a, RealElement b)	Add	Returns a + b	✔	✔	✔	✔	✔
CHAN	(RealElement a, RealElement b, IntElement thresholdFrame)	Time Chain	Returns a when current frame index is less-than thresholdFrame, otherwise b	✔	✔	✔	✔	✔
CLMP	(RealElement min, RealElement max, RealElement val)	Clamp	Returns val clamped between min and max	✔	✔	✔	✔	✔
CNST	(float value)	Constant	Returns value on every call	✔	✔	✔	✔	✔

Keyframe Emitter Template

KEYE and KEYP elements are able to statically encode a list of key values for all element types (except UV and Emitter elements). T represents the type being encoded.

Data Type	Description	Notes
u32	Percentage-Tweening Flag	If non-zero, this is a KEYP and there are exactly 100 keys in the list; all of these keys are linearly-interpolated over the lifetime of the particle instance (however long that may be)
u32	Unknown	Not used by GetValue
u8	Loop Flag	If non-zero, the key values are looped between loopStart and loopEnd indices (does not apply to KEYP)
u8	Unknown	Not used by GetValue
u32	Loop End	Final key index in the loop
u32	Loop Start	First key index in the loop
u32	Key Count	Count of keys encoded in the list
T[keyCount]	Keys	The actual key values themselves