Difference between revisions of "PART (File Format)"

From Retro Modding Wiki
Jump to: navigation, search
(Initial PART doc)
(RSOP description)
 
(10 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
{{research|1|Key descriptions are subject to corrections}}
+
{{research|1|Properties beyond MP1 need to be discovered and documented}}
−
 
+
The '''PART''' [[Particle Script|particle script]] format is used to configure ''particle effects''.
−
The '''PART''' [[effect script]] format is used to configure ''particle effects''.
+
  
 
Particles are the most widely-used effect in ''Metroid Prime'', with approximately
 
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''
+
3,500 unique scripts across the [[PAK_(Metroid_Prime)|PAK archives]].  
−
that may draw into the scene.
+
Each script configures a complete ''particle system'' that may draw into the scene.
  
 
The particle system is configurable to generate many visual effects:
 
The particle system is configurable to generate many visual effects:
Line 18: Line 17:
  
 
The concept behind the particle system is quite simple: lots of  
 
The concept behind the particle system is quite simple: lots of  
−
view-aligned (camera-facing) quadrilaterals (rectangles) with a texture-image
+
view-aligned (camera-facing) quads with a texture-image
 
are emitted, positioned, rotated, sized, colored, etc... according to the
 
are emitted, positioned, rotated, sized, colored, etc... according to the
 
parameters in the particle script.
 
parameters in the particle script.
  
−
== Particle Instance ==
+
== Particle System ==
  
−
Using the ''power-in-numbers'' principle, sophisticated visual effects
+
The ''particle system'' ties together all procedures necessary to host an ''emitter''
−
may be assembled from a large number of individual ''particles''.  
+
and specifies the rate at which new particles should be created. New particles have a predetermined
−
The effect runtime manages the state of all
+
''lifetime'' (in frames) set by the system, and the emitter initializes the position and velocity of these particles.
−
active particles and their visual properties.
+
The system continuously updates all currently-living particles that it's created. This includes updating
 +
properties like ''position'', ''velocity'', ''color'', ''size'' and ''view-rotation''.  
  
−
For each frame, each particle does the following primary tasks:
+
=== Child Systems ===
  
−
* Integrates all velocity sources, applies time-scale and advances position 1/60th of a second
+
Particle systems may also host ''child systems'' which are timed and positioned within the parent's reference.
−
* Evaluates local transforms
+
Not only does this include other PART systems, but [[SWHC (File Format)|SWHC]] and [[ELSC (File Format)|ELSC]]
−
** Scale
+
systems may be parented as well.
−
** 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
+
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.
  
−
== Emitter ==
+
=== Line Mode ===
  
−
Each particle-system employs a single ''emitter'' (<code>EMTR</code>) context.
+
When the <code>LINE</code> property is activated, particles are rendered as ''lines'' rather than quads.
−
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:
+
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.
  
−
=== Point Emitter (<code>SEMR</code> and <code>SETR</code>) ===
+
=== Model Mode ===
  
−
Both nodes receive position and velocity vector parameters.
+
When the <code>PMDL</code> property is provided with a [[CMDL (File Format)|CMDL]], particles are rendered
−
All particle instances are constructed using the parameters directly.
+
using that ''model'', in addition to the quad. Alternatively, <code>PMUS</code> generates a quad transformed
 +
as if it were a model (non view aligned).
  
−
The differences between <code>SEMR</code> and <code>SETR</code> are presently unknown.
+
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.
  
−
=== Sphere Emitter (<code>SPHE</code>) ===
+
Many weapon effects, notably the "sphere" of the charge-beam, are accomplished using particle models.
  
−
The *sphere emitter* randomly evaluates a point on a sphere of specified
+
== Particle Instance ==
−
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>) ===
+
For each frame, each particle does the following primary tasks:
  
−
Same as the sphere emitter; with additional angular constraints
+
* Determines if particle's lifetime has finished, removing it from the scene and releasing its resources for newly created particles to use
−
to randomly evaluate within. Therefore, only a sphere-section is emitted from.
+
* Invokes all [[Particle Script#Mod_Vector_Elements|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 ==
  
−
== PART Keys ==
+
''Main article: [[Particle Script#Emitter_Elements|Emitter Elements]]''
  
−
'''Scope''' is one of (''Constant'', ''System'', ''Particle'')
+
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.
  
−
* ''Constant'' parameters are evaluated once initially and retained within the system.
+
== Properties ==
−
* ''System'' parameters are evaluated per-system, per-frame.
+
 
−
* ''Particle'' parameters are evaluated per-system, per-frame, per-particle-instance.
+
Particle generator properties are assembled into a [[Particle Script|particle script]]
 +
file tagged with <code>GPSM</code>. Any of the following properties are loaded into a
 +
''description'' class for constructing an arbitrary number of ''particle generators''.
  
 
{| class="wikitable"
 
{| class="wikitable"
−
!FourCC
+
! FourCC
−
!Scope
+
! Type
−
!Data Type
+
! Description
−
!Description
+
! Scope
−
!Notes
+
! Notes
 +
! MP1
 +
! MP2
 +
! MP3
 +
! DKCR
 +
! DKCTF
 
|-
 
|-
−
|<code>EMTR</code>
+
{{ParticlePropertyRow|PSIV|VectorElement|System Initial Velocity|System Init|Defines the initial velocity vector which moves the entire system in local orientation (may be overridden by <code>PSVM</code>)|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
−
|System
+
{{ParticlePropertyRow|PSVM|ModVectorElement|System Velocity Mod|Post Particles Update|Mod Vector which influences the position and velocity of the entire system in local space|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
−
|<code>SEMR</code>, <code>SETR</code>, <code>SPHE</code>, <code>ASPH</code>
+
{{ParticlePropertyRow|PSOV|VectorElement|System Orientation Velocity|Post Particles Update|Angular velocity (in degrees/frame) of the system's orientation|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
−
|Emitter attachment
+
{{ParticlePropertyRow|PSLT|IntElement|System Lifetime|System Init|Count of frames that the system generates new particles|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
−
|References the object responsible for positioning and setting the initial velocity of new particles
+
{{ParticlePropertyRow|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|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|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.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|POFS|VectorElement|Particle Offset|System Init, Post Particles Update|Vector that offsets all particles in world space|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|SEED|IntElement|Random Seed|System Init|Value used to initialize the [[wikipedia:Linear congruential generator|LCG]] seed state used within the system's update and render cycles (default 99)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|LENG|RealElement|Line Length|Line Particle Creation, Line Particle Update|Length of <code>LINE</code> particles, scaled according to <code>FXLL</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|WIDT|RealElement|Line Width|Line Particle Render|Width of <code>LINE</code> particles in viewport pixels|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|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.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|GRTE|RealElement|Generation Rate|Pre Particles Update|Count of particles to create each frame. Remainder value is accumulated for the next update cycle.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|COLR|ColorElement|Color|Particle Creation, Particle Update|Color to multiply with particle's texture|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|LTME|IntElement|Lifetime|Particle Creation|Count of frames the about-to-be-created particle lives|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|ILOC|VectorElement|Particle Emit Location|Particle Creation|Position to initialize particle in local space (replaced by <code>EMTR</code>)|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
 +
{{ParticlePropertyRow|IVEC|VectorElement|Particle Emit Velocity|Particle Creation|Velocity to initialize particle in local space (replaced by <code>EMTR</code>)|{{maybe|Demo}}|{{nocheck}}|{{nocheck}}|{{nocheck}}|{{nocheck}}}}
 +
{{ParticlePropertyRow|EMTR|EmitterElement|Emitter|Particle Creation|[[Particle Script#Emitter Elements|Modular data source]] for initializing position and velocity of new particles|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|LINE|bool|Line Mode|System Init|Render particles as lines instead of quads|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|FXLL|bool|Line Mode|System Init|Scale leading point of line as the exact value of <code>LENG</code>, rather than multiplying <code>LENG</code> with the position-differential|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|AAPH|bool|Additive Alpha|System Init|Set up blending of quads and lines with source factor of <code>GX_BL_SRCALPHA</code> and destination factor of <code>GX_BL_ONE</code> as opposed to <code>GX_BL_SRCALPHA</code> and <code>GX_BL_INVSRCALPHA</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|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|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|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 <code>AAPH</code> is active)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|LIT_|bool|{{unknown|Unknown}}|System Init|Unused in demo|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|ORNT|bool|Orient To Origin|System Init|''New in retail'' - Simultaneously orients particle instances toward the local origin and view-point via cross-product. <code>ROTA</code> is used to control the width of quads in this mode, while <code>SIZE</code> controls the length.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|RSOP|bool|Right Vector Scaled on Particle|System Init|''New in retail'' - The right vector (particle width) is proportionally scaled with length|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|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 <code>MBSP</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|PMAB|bool|Model Additive Alpha|System Init|Equivalent of <code>AAPH</code> for models and <code>PMUS</code> quads|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|PMUS|bool|Model Unoriented Square|System Init|Draws a 1x1 quad in the XZ-plane in place of a <code>PMDL</code> model|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|PMOO|bool|Model Object Orientation|System Init|Includes client-supplied orientation in model's transform chain (after <code>PMRT</code>). Unlike other <code>bool</code> properties, this property is enabled by default|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|VMDn|bool|Local Vector Mod [1-4]|System Init|Applies mod vectors <code>VELn</code> in system local-space rather than world-space|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|CIND|bool|Colored Indirect Texture|System Init|When <code>TIND</code> is active, texels copied from the underlying framebuffer are multiplied with the texels in <code>TEXR</code> (rather than added). The alpha component is ''always'' multiplied.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|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.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|MBSP|IntElement|Motion Blur Samples|Pre Particles Update|When <code>MBLR</code> is active, this is the number of times the position differential of each particle instance is subdivided for overdraw|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|SIZE|RealElement|Particle Size|Particle Creation, Particle Update|Proportional scale (length and width) of particle quads|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|ROTA|RealElement|Particle View-Rotation|Particle Creation, Particle Update|View-aligned counterclockwise-rotation of particle instances|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|TEXR|UVElement|Particle Texture|Particle Creation, Particle Update|Particle texture map and UV coordinate source|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|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.|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|PMDL|[[CMDL (File Format)|CMDL]]|Particle Model|System Init|Render particle instances using this model, in addition to quads|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|PMOP|VectorElement|Particle Model Pre-Offset|Particle Model Render|Translate models using this vector ''before'' transforming normally|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|PMRT|VectorElement|Particle Model Rotate|Particle Model Render|Rotate models using these euler angles (in degrees, ZYX order)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|PMSC|VectorElement|Particle Model Scale|Particle Model Render|Scale models using this (potentially non-proportional) vector|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|PMCL|ColorElement|Particle Model Color|Particle Model Render|Multiply textured model color with this color|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|VELn|ModVectorElement|Particle Mod Vectors [1-4]|Particle Update|Up to 4 [[Particle Script#Mod Vector Elements|mod vectors]] invoked (in order) on each particle instance for each frame; influencing position and velocity|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|ICTS|PART|Counted Child System|System Init|Child particle system to spawn multiple instances of|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|NCSY|IntElement|Counted Child System Count|System Init|Count of <code>ICTS</code> systems to spawn (default 1)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|CSSD|IntElement|Counted Child System Frame|System Init|Frame index to spawn <code>ICTS</code> instances|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|IDTS|PART|Done Child System|System Init|Child particle system to spawn multiple instances of when parent system's lifetime finishes|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|NDSY|IntElement|Done Child System Count|System Init|Count of <code>IDTS</code> systems to spawn (default 1)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|IITS|PART|Interval Child System|System Init|Child particle system to spawn at regular intervals|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|PISY|IntElement|Interval Child System Frame Interval|System Init|Frame interval to emit <code>IITS</code> instances|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|SISY|IntElement|Interval Child System Start Frame|System Init|Frame index to start emitting <code>IITS</code> instances|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|KSSM|[[#SpawnSystemKeyframeData|SpawnSystemKeyframeData]]|Timed-Spawn Particle Systems|System Init|List of start-frame events and corresponding child systems to spawn|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|SSWH|[[SWHC (File Format)|SWHC]]|Child Swoosh System|System Init|Child swoosh system parented to this system|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|SSSD|IntElement|Child Swoosh System Start Frame|System Init|Frame index to start emitting <code>SSWH</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|SSPO|VectorElement|Child Swoosh System Offset|System Init|Offset supplied as swoosh system's translation|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|SELC|[[ELSC (File Format)|ELSC]]|Child Electric System|System Init|Child electric system parented to this system|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|SESD|IntElement|Child Electric System Start Frame|System Init|Frame index to start emitting <code>SELC</code>|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|SEPO|VectorElement|Child Electric System Offset|System Init|Offset supplied as electric system's translation|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 
|-
 
|-
−
|<code>MAXP</code>
+
| '''LTYP'''
−
|Constant
+
| style="font-family:monospace;" | IntElement
−
|<code>int</code>
+
| System Light Type
−
|Maximum particle count
+
| System Init
−
|The maximum number of particle instances that may exist simultaneously. The emitter will suspend emissions when this count is reached.
+
| Type of GX light to parent to system <ol start="0"><li>None (no light)</li><li>Custom (point)</li><li>Directional</li><li>Spot</li></ol>
 +
| {{check}}
 +
| {{check}}
 +
| {{check}}
 +
| {{check}}
 +
| {{check}}
 +
{{ParticlePropertyRow|LCLR|ColorElement|System Light Color|Post Particles Update|Diffuse color of GX light|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|LINT|RealElement|System Light Intensity|Post Particles Update|Light intensity factor used for calculating falloff|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|LOFF|VectorElement|System Light Offset|Post Particles Update|Light offset (not applicable to directional lights)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|LDIR|VectorElement|System Light Direction|Post Particles Update|Light direction (not applicable to custom lights)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 
|-
 
|-
−
|<code>GRTE</code>
+
| '''LFOT'''
−
|System
+
| style="font-family:monospace;" | IntElement
−
|<code>float</code>
+
| System Light Falloff Type
−
|Generation rate
+
| System Init
−
|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.
+
| Type of linear-attenuation equation to use for light <ol start="0"><li>Constant</li><li>Linear</li><li>Quadratic</li></ol>
 +
| {{check}}
 +
| {{check}}
 +
| {{check}}
 +
| {{check}}
 +
| {{check}}
 +
{{ParticlePropertyRow|LFOR|RealElement|System Light Falloff Radius|Post Particles Update|Falloff radius for linear-attenuation (not applicable to constant)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|LSLA|RealElement|System Light Cutoff Angle|Post Particles Update|Cutoff angle for angular-attenuation (only applicable to spot)|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
{{ParticlePropertyRow|ADVn|RealElement|Advance Parameters [1-8]|Pre Particles Update|Parameters to compute per system update, values shared across all particle instances via <code>PAPn</code> real elements|{{check}}|{{check}}|{{check}}|{{check}}|{{check}}}}
 +
|}
 +
 
 +
=== SpawnSystemKeyframeData ===
 +
 
 +
{| class="wikitable"
 +
! Data Type
 +
! Description
 +
! Notes
 
|-
 
|-
−
|<code>LTME</code>
+
| style="font-family:monospace;" | u32
−
|System
+
| {{unknown|'''Unknown'''}}
−
|<code>int</code>
+
|
−
|Particle lifetime
+
−
|Count of frames for generated particles to exist in the scene
+
 
|-
 
|-
−
|<code>PSLT</code>
+
| style="font-family:monospace;" | u32
−
|Constant
+
| {{unknown|'''Unknown'''}}
−
|<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>
+
| style="font-family:monospace;" | u32
−
|Constant
+
| End Frame
−
|<code>float</code>
+
| Final frame index where a system is spawned
−
|Particle-system time-scale
+
−
|Factor to multiply with time-differentials (velocities, gen-rates and lifetimes).
+
 
|-
 
|-
−
|<code>ICTS</code>
+
| style="font-family:monospace;" | u32
−
|Constant
+
| {{unknown|'''Unknown'''}}
−
|<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>
+
| style="font-family:monospace;" | u32
−
|Constant
+
| List Count
−
|<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>
+
| style="font-family:monospace;" | {u32&nbsp;''frame'', u32&nbsp;''infoCount'', [[#SpawnSystemKeyframeInfo|SpawnSystemKeyframeInfo]][infoCount]}[listCount]
−
|Constant
+
| Lists
−
|Compound
+
| Pairs of ''frame index'' and sequence of ''SpawnSystemKeyframeInfo'' for grouping systems that start on the same frame
−
|Child effect tree
+
|}
−
|A tree structure that constructs an arbitrary set of external particle effects and starts them emitting after specified frame-counts.
+
 
 +
=== SpawnSystemKeyframeInfo ===
 +
 
 +
{| class="wikitable"
 +
! Data Type
 +
! Description
 +
! Notes
 
|-
 
|-
−
|<code>SIZE</code>
+
| style="font-family:monospace;" | PART
−
|Particle
+
| Child System ID
−
|<code>float</code>
+
|
−
|Particle size
+
−
|Proportional scale (against normalized device coordinates) of the particle instance
+
 
|-
 
|-
−
|<code>ROTA</code>
+
| style="font-family:monospace;" | u32
−
|Particle
+
| {{unknown|'''Unknown'''}}
−
|<code>float</code>
+
|
−
|View-aligned rotation angle
+
−
|Angle (in degrees) to rotate the particle counter-clockwise around the view-axis.
+
 
|-
 
|-
−
|<code>POFS</code>
+
| style="font-family:monospace;" | u32
−
|Particle
+
| {{unknown|'''Unknown'''}}
−
|<code>float3</code>
+
|
−
|View-aligned particle offset
+
−
|Vector to translate particle instance after view-alignment
+
 
|-
 
|-
−
|<code>COLR</code>
+
| style="font-family:monospace;" | u32
−
|Particle
+
| {{unknown|'''Unknown'''}}
−
|<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]]

Latest revision as of 19:51, 12 May 2018

Morphball render.png 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
  1. None (no light)
  2. Custom (point)
  3. Directional
  4. 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
  1. Constant
  2. Linear
  3. 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
Retrieved from "http://www.metroid2002.com/retromodding/index.php?title=PART_(File_Format)&oldid=1925"