PART (File Format)

This file format is almost completely documented Key descriptions are subject to corrections

The PART effect 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) quadrilaterals (rectangles) with a texture-image are emitted, positioned, rotated, sized, colored, etc... according to the parameters in the particle script.

Particle Instance

Using the power-in-numbers principle, sophisticated visual effects may be assembled from a large number of individual particles. The effect runtime manages the state of all active particles and their visual properties.

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

• Integrates all velocity sources, applies time-scale and advances position 1/60th of a second
• Evaluates local transforms
  • Scale
  • View-aligned rotation
  • View-aligned offset
• Evaluates particle color (shader-multiplied with texture-image)

There are other operational steps activated and controlled by the script

Emitter

Each particle-system employs a single emitter (EMTR) context. The emitter generates a specified number of particles each frame; determining the initial position and velocity-vector for each. It also evaluates a lifetime (frame count) for each particle to be in the scene.

Emitters are represented by multiple node-classes:

Point Emitter (SEMR and SETR)

Both nodes receive position and velocity vector parameters. All particle instances are constructed using the parameters directly.

The differences between SEMR and SETR are presently unknown.

Sphere Emitter (SPHE)

The sphere emitter randomly evaluates a point on a sphere of specified offset-vector and radius. The velocity vector is computed from the sphere's normal and scaled by a specified amount.

Partial-Sphere Emitter (ASPH)

Same as the sphere emitter; with additional angular constraints to randomly evaluate within. Therefore, only a sphere-section is emitted from.

PART Keys

Scope is one of (Constant, System, Particle)

• 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.

FourCC	Scope	Data Type	Description	Notes
EMTR	System	SEMR, SETR, SPHE, ASPH	Emitter attachment	References the object responsible for positioning and setting the initial velocity of new particles
MAXP	Constant	int	Maximum particle count	The maximum number of particle instances that may exist simultaneously. The emitter will suspend emissions when this count is reached.
GRTE	System	float	Generation rate	An accumulated floating-point value that specifies how many particles to generate each frame. A value of 1.0 will generate one particle each frame. A value of 2.0 will generate two particles per frame. A value of 0.5 will generate one particle every other frame.
LTME	System	int	Particle lifetime	Count of frames for generated particles to exist in the scene
PSLT	Constant	int	Particle-system lifetime	Count of frames for emitter to generate particles. Default behavior is infinite if PSLT not specified.
PSTS	Constant	float	Particle-system time-scale	Factor to multiply with time-differentials (velocities, gen-rates and lifetimes).
ICTS	Constant	int (data ref)	Concurrent particle-system	Specifies an external particle script to construct into a parallel system that shares time and space.
IDTS	Constant	int (data ref)	Deferred particle-system	Specifies an external particle script to construct a particle system that shares space, but doesn’t start emitting until this system’s emitter stops.
KSSM	Constant	Compound	Child effect tree	A tree structure that constructs an arbitrary set of external particle effects and starts them emitting after specified frame-counts.
SIZE	Particle	float	Particle size	Proportional scale (against normalized device coordinates) of the particle instance
ROTA	Particle	float	View-aligned rotation angle	Angle (in degrees) to rotate the particle counter-clockwise around the view-axis.
POFS	Particle	float3	View-aligned particle offset	Vector to translate particle instance after view-alignment
COLR	Particle	float4	Particle color	RGBA vector specifying a color to multiply the particle instance’s texture with.
AAPH	Constant	bool	Additive blending	Particle instances are drawn with graphics pipeline configured to add particle’s color with existing framebuffer color.
TEXR	Constant	int (data ref)	Texture attachment	Specifies the texture resource to map to each particle instance’s surface.
TIND	Constant	int (data ref)	Indirect texture attachment	Certain particle effects are drawn after the main scene against the player’s ‘visor’. Effects that simulate visor water-droplet refraction use an indirect texture to warp texture coordinates when sampling the underlying scene.
ORNT	Constant	bool	Oriented particle mode	The X-axis of generated particles will extend towards the particle’s emitter. The Y and Z axis are computed via up-vector and cross product. In this mode, ROTA specifies the particle’s aspect ratio instead of rotation. Commonly used to implement radial light-beams.
MBLR	Constant	bool	Motion blur mode	Each particle instance is over-drawn a specified number of times along the velocity-vector.
MBSP	Constant	int	Motion blur sample count	Number of times to draw motion-blur particle instances.
LINE	Constant	bool	Line rendering mode	Instead of the view-aligned appearance, particle instances are drawn as a line with a trailing, specified length
WIDT	Particle	float	Line width	In line mode, specifies the projected line width (in 480p pixels)
LENG	Particle	float	Line length	In line mode, specifies the line length (as a multiple of each frame's velocity magnitude)
PMUS	Constant	bool	Non-view-aligned quad mode	In addition to the view-aligned appearance, particle instances transform a normalized, non-view-aligned quadrilateral in the XZ plane. All ‘particle model’ parameters (PMAB, PMSC, PMCL, etc…) affect this quad.
PMSC	Particle	float3	Particle-model scale	Local particle model scale vector
PMRT	Particle	float3	Particle-model rotation	XYZ-euler particle model rotation
PMOP	Particle	float3	Particle-model offset	Local particle model offset (after scale and rotation)
PMAB	Constant	bool	Particle-model additive blending	AAPH for particle models
VELn	Particle	WIND, GRAV, SWRL, BNCE, EXPL, IMPL, EMPL, LMPL	Velocity attachments (1-4)	In addition to the initial velocity provided by the emitter, other simulated forces may be attached as velocity sources.
SORT	Constant	bool	Particle depth sort	Particle instances are sorted from back-to-front in view (for proper alpha-blending)
ZBUF	Constant	bool	Particle z-buffer write	Particle instances modify the z-buffer if set
LTYP	Constant	int	Lamp type enumeration	Particle emitter is also a dynamic area lamp when non zero (0:off, 1:point, 2:spot)
LOFF	System	float3	Lamp offset vector	Local offset from emitter to position lamp
LDIR	System	float3	Lamp direction vector	Local direction to cast spot lamps
LFOT	Constant	int	Lamp falloff type	Affects how quadratic falloff coefficients are assigned in the lighting shader (0:constant, 1:inverse-linear, 2:inverse-quadratic)
LFOR	System	float	Lamp falloff radius	Radius from emitter that lamp casts light
LCLR	System	float4	Lamp color	RGBA vector of lamp’s color
LINT	System	float	Lamp intensity	Multiplied with lamp color to affect lamp’s energy

PART Nodes

Main article: Effect Script

PART scripts share effect nodes with other effect script formats.

Some nodes are exclusive to PART:

• SETR
• SEMR
• SPHE
• ASPH
• SPOS
• PLCO
• PLOC