PART (File Format)

This file format is almost completely documented Properties beyond MP1 need to be discovered and documented

The PART particle script format is used to configure particle effects.

Particles are the most widely-used effect in Metroid Prime, with approximately 3,500 unique scripts across the PAK archives. Each script configures a complete particle system that may draw into the scene.

The particle system is configurable to generate many visual effects:

• Flames and smoke
• Floating embers
• Water splashes/drips
• Dust and dirt in windy conditions
• Volumetric light "shimmers"
• Energy/plasma discharges
• Many others

The concept behind the particle system is quite simple: lots of view-aligned (camera-facing) quads with a texture-image are emitted, positioned, rotated, sized, colored, etc... according to the parameters in the particle script.

Particle System

The particle system ties together all procedures necessary to host an emitter and specifies the rate at which new particles should be created. New particles have a predetermined lifetime (in frames) set by the system, and the emitter initializes the position and velocity of these particles. The system continuously updates all currently-living particles that it's created. This includes updating properties like position, velocity, color, size and view-rotation.

Child Systems

Particle systems may also host child systems which are timed and positioned within the parent's reference. Not only does this include other PART systems, but SWHC and ELSC systems may be parented as well.

A good example of this is the flamethrower's system, which composes flame particles with a trailing SWHC and small cinders from a separate PART.

Line Mode

When the LINE property is activated, particles are rendered as lines rather than quads.

The usual 3D particle position is used as the trailing-point of the line, with the leading-point computed via positional-differential, scaled by other parameters. Lines sample textures diagonally as a single-texel strip, allowing for gradients to be applied via spherical or diagonal ramp-textures.

Model Mode

When the PMDL property is provided with a CMDL, particles are rendered using that model, in addition to the quad. Alternatively, PMUS generates a quad transformed as if it were a model (non view aligned).

Model-based particles have a whole separate suite of properties for controlling local-transformation and color. Most of the properties involving positioning and transforms from the client systems are shared from the normal quad-mode.

Many weapon effects, notably the "sphere" of the charge-beam, are accomplished using particle models.

Particle Instance

For each frame, each particle does the following primary tasks:

• Determines if particle's lifetime has finished, removing it from the scene and releasing its resources for newly created particles to use
• Invokes all velocity/position sources; advancing position 1/60th of a second
• Evaluates local transforms
  • Size
  • View-aligned rotation
  • View-aligned offset
• Evaluates particle color (shader-multiplied with texture-image)

Emitter

Main article: Emitter Elements

Each particle-system employs a single emitter context. The system generates a specified number of particles each frame; the emitter initializing the position and velocity-vector for each.

Properties

Particle generator properties are assembled into a particle script file tagged with GPSM. Any of the following properties are loaded into a description class for constructing an arbitrary number of particle generators.

FourCC	Type	Description	Scope	Notes	MP1	MP2	MP3	DKCR	DKCTF
PSIV	VectorElement	System Initial Velocity	System Init	Defines the initial velocity vector which moves the entire system in local orientation (may be overridden by PSVM)	Demo	✖	✖	✖	✖
PSVM	ModVectorElement	System Velocity Mod	Post Particles Update	Mod Vector which influences the position and velocity of the entire system in local space	Demo	✖	✖	✖	✖
PSOV	VectorElement	System Orientation Velocity	Post Particles Update	Angular velocity (in degrees/frame) of the system's orientation	Demo	✖	✖	✖	✖
PSLT	IntElement	System Lifetime	System Init	Count of frames that the system generates new particles	✔	✔	✔	✔	✔
PSWT	IntElement	System Warmup Time	Warmup-Phase Update	Count of frames that the particle system virtually updates itself within one initial frame; exiting the warmup phase afterwards	✔	✔	✔	✔	✔
PSTS	RealElement	System Time Scale	Pre Particles Update	Factor that redefines the second for the system, including the rate at which the system's frame count is incremented. 1.0 is native 60-fps. 0.5 causes every other frame to skip updates, slowing down and making the motion "choppy". 2.0 causes 2 updates every frame, speeding up.	✔	✔	✔	✔	✔
POFS	VectorElement	Particle Offset	System Init, Post Particles Update	Vector that offsets all particles in world space	✔	✔	✔	✔	✔
SEED	IntElement	Random Seed	System Init	Value used to initialize the LCG seed state used within the system's update and render cycles (default 99)	✔	✔	✔	✔	✔
LENG	RealElement	Line Length	Line Particle Creation, Line Particle Update	Length of LINE particles, scaled according to FXLL	✔	✔	✔	✔	✔
WIDT	RealElement	Line Width	Line Particle Render	Width of LINE particles in viewport pixels	✔	✔	✔	✔	✔
MAXP	IntElement	Max Particles	System Init, Pre Particles Update	Max count of particles allowed to live at once. No new particles created if there are already this many active particles.	✔	✔	✔	✔	✔
GRTE	RealElement	Generation Rate	Pre Particles Update	Count of particles to create each frame. Remainder value is accumulated for the next update cycle.	✔	✔	✔	✔	✔
COLR	ColorElement	Color	Particle Creation, Particle Update	Color to multiply with particle's texture	✔	✔	✔	✔	✔
LTME	IntElement	Lifetime	Particle Creation	Count of frames the about-to-be-created particle lives	✔	✔	✔	✔	✔
ILOC	VectorElement	Particle Emit Location	Particle Creation	Position to initialize particle in local space (replaced by EMTR)	Demo	✖	✖	✖	✖
IVEC	VectorElement	Particle Emit Velocity	Particle Creation	Velocity to initialize particle in local space (replaced by EMTR)	Demo	✖	✖	✖	✖
EMTR	EmitterElement	Emitter	Particle Creation	Modular data source for initializing position and velocity of new particles	✔	✔	✔	✔	✔
LINE	bool	Line Mode	System Init	Render particles as lines instead of quads	✔	✔	✔	✔	✔
FXLL	bool	Line Mode	System Init	Scale leading point of line as the exact value of LENG, rather than multiplying LENG with the position-differential	✔	✔	✔	✔	✔
AAPH	bool	Additive Alpha	System Init	Set up blending of quads and lines with source factor of GX_BL_SRCALPHA and destination factor of GX_BL_ONE as opposed to GX_BL_SRCALPHA and GX_BL_INVSRCALPHA	✔	✔	✔	✔	✔
ZBUF	bool	Z-buffer Write	System Init	Perform rendering while writing into the z-buffer to ensure later-drawn objects don't occlude particles if positioned behind them	✔	✔	✔	✔	✔
SORT	bool	View-space Sort	System Init	Sort particles by their z-coordinate in view-space before drawing, which is essential for proper alpha blending (although mathematically unnecessary when AAPH is active)	✔	✔	✔	✔	✔
LIT_	bool	Unknown	System Init	Unused in demo	✔	✔	✔	✔	✔
ORNT	bool	Orient To Origin	System Init	New in retail - Simultaneously orients particle instances toward the local origin and view-point via cross-product. ROTA is used to control the width of quads in this mode, while SIZE controls the length.	✔	✔	✔	✔	✔
RSOP	bool	Right Vector Scaled on Particle	System Init	New in retail - The right vector (particle width) is proportionally scaled with length	✔	✔	✔	✔	✔
MBLR	bool	Motion Blur	System Init	Enables sub-positional overdraw of each particle instance between its previous position and new position each frame; draw count controlled by MBSP	✔	✔	✔	✔	✔
PMAB	bool	Model Additive Alpha	System Init	Equivalent of AAPH for models and PMUS quads	✔	✔	✔	✔	✔
PMUS	bool	Model Unoriented Square	System Init	Draws a 1x1 quad in the XZ-plane in place of a PMDL model	✔	✔	✔	✔	✔
PMOO	bool	Model Object Orientation	System Init	Includes client-supplied orientation in model's transform chain (after PMRT). Unlike other bool properties, this property is enabled by default	✔	✔	✔	✔	✔
VMDn	bool	Local Vector Mod [1-4]	System Init	Applies mod vectors VELn in system local-space rather than world-space	✔	✔	✔	✔	✔
CIND	bool	Colored Indirect Texture	System Init	When TIND is active, texels copied from the underlying framebuffer are multiplied with the texels in TEXR (rather than added). The alpha component is always multiplied.	✔	✔	✔	✔	✔
OPTS	bool	Optional System	System Init	When a client system constructs a generator instance, it has the option to filter out child systems at any level that aren't essential to the effect. The exclusion is a mutual decision between the client and the particle description via this property.	✔	✔	✔	✔	✔
MBSP	IntElement	Motion Blur Samples	Pre Particles Update	When MBLR is active, this is the number of times the position differential of each particle instance is subdivided for overdraw	✔	✔	✔	✔	✔
SIZE	RealElement	Particle Size	Particle Creation, Particle Update	Proportional scale (length and width) of particle quads	✔	✔	✔	✔	✔
ROTA	RealElement	Particle View-Rotation	Particle Creation, Particle Update	View-aligned counterclockwise-rotation of particle instances	✔	✔	✔	✔	✔
TEXR	UVElement	Particle Texture	Particle Creation, Particle Update	Particle texture map and UV coordinate source	✔	✔	✔	✔	✔
TIND	UVElement	Indirect Particle Texture	Particle Creation, Particle Update	Indirect texture map and UV coordinate source. Setting this property enables framebuffer->texture copies of the rectangular region behind particle instances. These texels are warped using coordinates defined in the texels of the IA texture in this property.	✔	✔	✔	✔	✔
PMDL	CMDL	Particle Model	System Init	Render particle instances using this model, in addition to quads	✔	✔	✔	✔	✔
PMOP	VectorElement	Particle Model Pre-Offset	Particle Model Render	Translate models using this vector before transforming normally	✔	✔	✔	✔	✔
PMRT	VectorElement	Particle Model Rotate	Particle Model Render	Rotate models using these euler angles (in degrees, ZYX order)	✔	✔	✔	✔	✔
PMSC	VectorElement	Particle Model Scale	Particle Model Render	Scale models using this (potentially non-proportional) vector	✔	✔	✔	✔	✔
PMCL	ColorElement	Particle Model Color	Particle Model Render	Multiply textured model color with this color	✔	✔	✔	✔	✔
VELn	ModVectorElement	Particle Mod Vectors [1-4]	Particle Update	Up to 4 mod vectors invoked (in order) on each particle instance for each frame; influencing position and velocity	✔	✔	✔	✔	✔
ICTS	PART	Counted Child System	System Init	Child particle system to spawn multiple instances of	✔	✔	✔	✔	✔
NCSY	IntElement	Counted Child System Count	System Init	Count of ICTS systems to spawn (default 1)	✔	✔	✔	✔	✔
CSSD	IntElement	Counted Child System Frame	System Init	Frame index to spawn ICTS instances	✔	✔	✔	✔	✔
IDTS	PART	Done Child System	System Init	Child particle system to spawn multiple instances of when parent system's lifetime finishes	✔	✔	✔	✔	✔
NDSY	IntElement	Done Child System Count	System Init	Count of IDTS systems to spawn (default 1)	✔	✔	✔	✔	✔
IITS	PART	Interval Child System	System Init	Child particle system to spawn at regular intervals	✔	✔	✔	✔	✔
PISY	IntElement	Interval Child System Frame Interval	System Init	Frame interval to emit IITS instances	✔	✔	✔	✔	✔
SISY	IntElement	Interval Child System Start Frame	System Init	Frame index to start emitting IITS instances	✔	✔	✔	✔	✔
KSSM	SpawnSystemKeyframeData	Timed-Spawn Particle Systems	System Init	List of start-frame events and corresponding child systems to spawn	✔	✔	✔	✔	✔
SSWH	SWHC	Child Swoosh System	System Init	Child swoosh system parented to this system	✔	✔	✔	✔	✔
SSSD	IntElement	Child Swoosh System Start Frame	System Init	Frame index to start emitting SSWH	✔	✔	✔	✔	✔
SSPO	VectorElement	Child Swoosh System Offset	System Init	Offset supplied as swoosh system's translation	✔	✔	✔	✔	✔
SELC	ELSC	Child Electric System	System Init	Child electric system parented to this system	✔	✔	✔	✔	✔
SESD	IntElement	Child Electric System Start Frame	System Init	Frame index to start emitting SELC	✔	✔	✔	✔	✔
SEPO	VectorElement	Child Electric System Offset	System Init	Offset supplied as electric system's translation	✔	✔	✔	✔	✔
LTYP	IntElement	System Light Type	System Init	Type of GX light to parent to system None (no light) Custom (point) Directional Spot	✔	✔	✔	✔	✔
LCLR	ColorElement	System Light Color	Post Particles Update	Diffuse color of GX light	✔	✔	✔	✔	✔
LINT	RealElement	System Light Intensity	Post Particles Update	Light intensity factor used for calculating falloff	✔	✔	✔	✔	✔
LOFF	VectorElement	System Light Offset	Post Particles Update	Light offset (not applicable to directional lights)	✔	✔	✔	✔	✔
LDIR	VectorElement	System Light Direction	Post Particles Update	Light direction (not applicable to custom lights)	✔	✔	✔	✔	✔
LFOT	IntElement	System Light Falloff Type	System Init	Type of linear-attenuation equation to use for light Constant Linear Quadratic	✔	✔	✔	✔	✔
LFOR	RealElement	System Light Falloff Radius	Post Particles Update	Falloff radius for linear-attenuation (not applicable to constant)	✔	✔	✔	✔	✔
LSLA	RealElement	System Light Cutoff Angle	Post Particles Update	Cutoff angle for angular-attenuation (only applicable to spot)	✔	✔	✔	✔	✔
ADVn	RealElement	Advance Parameters [1-8]	Pre Particles Update	Parameters to compute per system update, values shared across all particle instances via PAPn real elements	✔	✔	✔	✔	✔

SpawnSystemKeyframeData

Data Type	Description	Notes
u32	Unknown
u32	Unknown
u32	End Frame	Final frame index where a system is spawned
u32	Unknown
u32	List Count
{u32 frame, u32 infoCount, SpawnSystemKeyframeInfo[infoCount]}[listCount]	Lists	Pairs of frame index and sequence of SpawnSystemKeyframeInfo for grouping systems that start on the same frame

SpawnSystemKeyframeInfo

Data Type	Description	Notes
PART	Child System ID
u32	Unknown
u32	Unknown
u32	Unknown