Difference between revisions of "PART (File Format)"

From Retro Modding Wiki
Jump to: navigation, search
m ({{research}})
(Initial PART doc)
Line 1: Line 1:
−
{{research|3|We don't know anything about this format.}}
+
{{research|1|Key descriptions are subject to corrections}}
  
−
The '''PART format''' controls particles. The format is nearly entirely unknown.
+
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_(Metroid_Prime)|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'' (<code>EMTR</code>) 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 (<code>SEMR</code> and <code>SETR</code>) ===
 +
 
 +
Both nodes receive position and velocity vector parameters.
 +
All particle instances are constructed using the parameters directly.
 +
 
 +
The differences between <code>SEMR</code> and <code>SETR</code> are presently unknown.
 +
 
 +
=== Sphere Emitter (<code>SPHE</code>) ===
 +
 
 +
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 (<code>ASPH</code>) ===
 +
 
 +
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.
 +
 
 +
{| class="wikitable"
 +
!FourCC
 +
!Scope
 +
!Data Type
 +
!Description
 +
!Notes
 +
|-
 +
|<code>EMTR</code>
 +
|System
 +
|<code>SEMR</code>, <code>SETR</code>, <code>SPHE</code>, <code>ASPH</code>
 +
|Emitter attachment
 +
|References the object responsible for positioning and setting the initial velocity of new particles
 +
|-
 +
|<code>MAXP</code>
 +
|Constant
 +
|<code>int</code>
 +
|Maximum particle count
 +
|The maximum number of particle instances that may exist simultaneously. The emitter will suspend emissions when this count is reached.
 +
|-
 +
|<code>GRTE</code>
 +
|System
 +
|<code>float</code>
 +
|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.
 +
|-
 +
|<code>LTME</code>
 +
|System
 +
|<code>int</code>
 +
|Particle lifetime
 +
|Count of frames for generated particles to exist in the scene
 +
|-
 +
|<code>PSLT</code>
 +
|Constant
 +
|<code>int</code>
 +
|Particle-system lifetime
 +
|Count of frames for emitter to generate particles. Default behavior is infinite if <code>PSLT</code> not specified.
 +
|-
 +
|<code>PSTS</code>
 +
|Constant
 +
|<code>float</code>
 +
|Particle-system time-scale
 +
|Factor to multiply with time-differentials (velocities, gen-rates and lifetimes).
 +
|-
 +
|<code>ICTS</code>
 +
|Constant
 +
|<code>int</code> (data ref)
 +
|Concurrent particle-system
 +
|Specifies an external particle script to construct into a parallel system that shares time and space.
 +
|-
 +
|<code>IDTS</code>
 +
|Constant
 +
|<code>int</code> (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.
 +
|-
 +
|<code>KSSM</code>
 +
|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.
 +
|-
 +
|<code>SIZE</code>
 +
|Particle
 +
|<code>float</code>
 +
|Particle size
 +
|Proportional scale (against normalized device coordinates) of the particle instance
 +
|-
 +
|<code>ROTA</code>
 +
|Particle
 +
|<code>float</code>
 +
|View-aligned rotation angle
 +
|Angle (in degrees) to rotate the particle counter-clockwise around the view-axis.
 +
|-
 +
|<code>POFS</code>
 +
|Particle
 +
|<code>float3</code>
 +
|View-aligned particle offset
 +
|Vector to translate particle instance after view-alignment
 +
|-
 +
|<code>COLR</code>
 +
|Particle
 +
|<code>float4</code>
 +
|Particle color
 +
|RGBA vector specifying a color to multiply the particle instance’s texture with.
 +
|-
 +
|<code>AAPH</code>
 +
|Constant
 +
|<code>bool</code>
 +
|Additive blending
 +
|Particle instances are drawn with graphics pipeline configured to add particle’s color with existing framebuffer color.
 +
|-
 +
|<code>TEXR</code>
 +
|Constant
 +
|<code>int</code> (data ref)
 +
|Texture attachment
 +
|Specifies the texture resource to map to each particle instance’s surface.
 +
|-
 +
|<code>TIND</code>
 +
|Constant
 +
|<code>int</code> (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.
 +
|-
 +
|<code>ORNT</code>
 +
|Constant
 +
|<code>bool</code>
 +
|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, <code>ROTA</code> specifies the particle’s aspect ratio instead of rotation. Commonly used to implement radial light-beams.
 +
|-
 +
|<code>MBLR</code>
 +
|Constant
 +
|<code>bool</code>
 +
|Motion blur mode
 +
|Each particle instance is over-drawn a specified number of times along the velocity-vector.
 +
|-
 +
|<code>MBSP</code>
 +
|Constant
 +
|<code>int</code>
 +
|Motion blur sample count
 +
|Number of times to draw motion-blur particle instances.
 +
|-
 +
|<code>LINE</code>
 +
|Constant
 +
|<code>bool</code>
 +
|Line rendering mode
 +
|Instead of the view-aligned appearance, particle instances are drawn as a line with a trailing, specified length
 +
|-
 +
|<code>WIDT</code>
 +
|Particle
 +
|<code>float</code>
 +
|Line width
 +
|In line mode, specifies the projected line width (in 480p pixels)
 +
|-
 +
|<code>LENG</code>
 +
|Particle
 +
|<code>float</code>
 +
|Line length
 +
|In line mode, specifies the line length (as a multiple of each frame's velocity magnitude)
 +
|-
 +
|<code>PMUS</code>
 +
|Constant
 +
|<code>bool</code>
 +
|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 (<code>PMAB</code>, <code>PMSC</code>, <code>PMCL</code>, etc…) affect this quad.
 +
|-
 +
|<code>PMSC</code>
 +
|Particle
 +
|<code>float3</code>
 +
|Particle-model scale
 +
|Local particle model scale vector
 +
|-
 +
|<code>PMRT</code>
 +
|Particle
 +
|<code>float3</code>
 +
|Particle-model rotation
 +
|XYZ-euler particle model rotation
 +
|-
 +
|<code>PMOP</code>
 +
|Particle
 +
|<code>float3</code>
 +
|Particle-model offset
 +
|Local particle model offset (after scale and rotation)
 +
|-
 +
|<code>PMAB</code>
 +
|Constant
 +
|<code>bool</code>
 +
|Particle-model additive blending
 +
|<code>AAPH</code> for particle models
 +
|-
 +
|<code>VELn</code>
 +
|Particle
 +
|<code>WIND</code>, <code>GRAV</code>, <code>SWRL</code>, <code>BNCE</code>, <code>EXPL</code>, <code>IMPL</code>, <code>EMPL</code>, <code>LMPL</code>
 +
|Velocity attachments (1-4)
 +
|In addition to the initial velocity provided by the emitter, other simulated forces may be attached as velocity sources.
 +
|-
 +
|<code>SORT</code>
 +
|Constant
 +
|<code>bool</code>
 +
|Particle depth sort
 +
|Particle instances are sorted from back-to-front in view (for proper alpha-blending)
 +
|-
 +
|<code>ZBUF</code>
 +
|Constant
 +
|<code>bool</code>
 +
|Particle z-buffer write
 +
|Particle instances modify the z-buffer if set
 +
|-
 +
|<code>LTYP</code>
 +
|Constant
 +
|<code>int</code>
 +
|Lamp type enumeration
 +
|Particle emitter is also a dynamic area lamp when non zero (0:off, 1:point, 2:spot)
 +
|-
 +
|<code>LOFF</code>
 +
|System
 +
|<code>float3</code>
 +
|Lamp offset vector
 +
|Local offset from emitter to position lamp
 +
|-
 +
|<code>LDIR</code>
 +
|System
 +
|<code>float3</code>
 +
|Lamp direction vector
 +
|Local direction to cast spot lamps
 +
|-
 +
|<code>LFOT</code>
 +
|Constant
 +
|<code>int</code>
 +
|Lamp falloff type
 +
|Affects how quadratic falloff coefficients are assigned in the lighting shader (0:constant, 1:inverse-linear, 2:inverse-quadratic)
 +
|-
 +
|<code>LFOR</code>
 +
|System
 +
|<code>float</code>
 +
|Lamp falloff radius
 +
|Radius from emitter that lamp casts light
 +
|-
 +
|<code>LCLR</code>
 +
|System
 +
|<code>float4</code>
 +
|Lamp color
 +
|RGBA vector of lamp’s color
 +
|-
 +
|<code>LINT</code>
 +
|System
 +
|<code>float</code>
 +
|Lamp intensity
 +
|Multiplied with lamp color to affect lamp’s energy
 +
|}
 +
 
 +
== PART Nodes ==
 +
 
 +
{{main|Effect Script}}
 +
 
 +
PART scripts share [[Effect Script#Script Nodes|effect nodes]] with other effect script formats.
 +
 
 +
Some nodes are exclusive to PART:
 +
 
 +
* <code>SETR</code>
 +
* <code>SEMR</code>
 +
* <code>SPHE</code>
 +
* <code>ASPH</code>
 +
* <code>SPOS</code>
 +
* <code>PLCO</code>
 +
* <code>PLOC</code>
  
 
[[Category:File Formats]]
 
[[Category:File Formats]]

Revision as of 18:03, 20 February 2015

Morphball render.png 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
Retrieved from "http://www.metroid2002.com/retromodding/index.php?title=PART_(File_Format)&oldid=757"