User:Jackoalan/PART (File Format)

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

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.

PART 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)	✔	✔	✔	✔	✔
PSVM	ModVectorElement	System Velocity Mod	System Post Particles Update	Mod Vector which influences the position and velocity of the entire system in local space	✔	✔	✔	✔	✔
PSOV	VectorElement	System Orientation Velocity	System Post Particles Update	Angular velocity (in degrees/frame) of the system's orientation	✔	✔	✔	✔	✔
PSLT	IntElement	System Lifetime	System Init	Count of frames that the system generates new particles	✔	✔	✔	✔	✔
PSWT	IntElement	System Warmup Time	System 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	System 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, System Post Particles Update	Vector that offsets all particles in world-space	✔	✔	✔	✔	✔