TXTR (Metroid Prime) and PART (File Format): Difference between pages

From Retro Modding Wiki
(Difference between pages)
Jump to navigation Jump to search
>Aruki
 
imported>Jackoalan
 
Line 1: Line 1:
''See [[TXTR (File Format)]] for the other revisions of this format.''
{{research|1|Key descriptions are subject to corrections}}
The '''PART''' [[Effect Script|effect script]] format is used to configure ''particle effects''.


'''TXTR''' is, as the name suggests, the Retro Studios texture format. The format remains completely unchanged from Metroid Prime all the way up to Donkey Kong Country Returns.
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.


{{todo|Could possibly use some more information on how the formats work and how to decode them, but then again the Custom Mario Kart Wiiki has this covered pretty nicely already.}}
The particle system is configurable to generate many visual effects:


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


== Format ==
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.


TXTR files contain a very short 12-byte header, followed by the image data.
== Particle Instance ==


=== Header ===
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"
{| class="wikitable"
! Offset
!FourCC
! Size
!Scope
! Description
!Data Type
!Description
!Notes
|-
|-
| 0x0
|<code>EMTR</code>
| 4
|System
| '''Image format'''. Possible values range from 0x0 to 0xA; see below for more details.
|<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
|-
|-
| 0x4
|<code>MAXP</code>
| 2
|Constant
| '''Width'''
|<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.
|-
|-
| 0x6
|<code>GRTE</code>
| 2
|System
| '''Height'''
|<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.
|-
|-
| 0x8
|<code>LTME</code>
| 4
|System
| '''Mipmap count'''
|<code>int</code>
|Particle lifetime
|Count of frames for generated particles to exist in the scene
|-
|-
| 0xC
|<code>PSLT</code>
| colspan=2 {{unknown|End of header}}
|Constant
|}
|<code>int</code>
 
|Particle-system lifetime
=== Palettes ===
|Count of frames for emitter to generate particles. Default behavior is infinite if <code>PSLT</code> not specified.
 
|-
The C4 and C8 image formats contain a palette table after the header, before the image data begins.
|<code>PSTS</code>
 
|Constant
{| class="wikitable"
|<code>float</code>
! Offset
|Particle-system time-scale
! Size
|Factor to multiply with time-differentials (velocities, gen-rates and lifetimes).
! Description
|-
|<code>ICTS</code>
|Constant
|<code>int</code> ([[PART (File Format)|PART]] 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> ([[PART (File Format)|PART]] 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. In <code>ORNT</code> mode, this specifies the particle's aspect ratio instead.
|-
|<code>POFS</code>
|Particle
|<code>float3</code>
|Particle offset
|Vector to translate particle instance within system
|-
|<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> ([[TXTR (File Format)|TXTR]] ref), <code>ATEX</code>
|Texture attachment
|Specifies the texture resource to map to each particle instance’s surface.
|-
|<code>TIND</code>
|Constant
|<code>int</code> ([[TXTR (File Format)|TXTR]] 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)
|-
|-
| 0x0
|<code>LENG</code>
| 4
|Particle
| '''Palette format'''. Possible values range from 0 to 2.
|<code>float</code>
|Line length
|In line mode, specifies the line length (as a multiple of each frame's velocity magnitude)
|-
|-
| 0x4
|<code>PMUS</code>
| 2
|Constant
| '''Width'''. always 1 in C4, 256 in C8
|<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.
|-
|-
| 0x6
|<code>PMSC</code>
| 2
|Particle
| '''Height'''. always 16 in C4, 1 in C8
|<code>float3</code>
|Particle-model scale
|Local particle model scale vector
|-
|-
| 0x8
|<code>PMRT</code>
| Varies
|Particle
| '''Palette colors'''. 16-bit color values; 16 colors in C4, 256 in C8.
|<code>float3</code>
|Particle-model rotation
|XYZ-euler particle model rotation
|-
|-
| colspan=3 {{unknown|End of palette table; image data begins immediately after}}
|<code>PMOP</code>
|}
|Particle
 
|<code>float3</code>
== Image Formats ==
|Particle-model offset
 
|Local particle model offset (after scale and rotation)
There are 11 different image formats supported by the hardware. Rather than storing pixels in a linear left-to-right order, GameCube textures are swizzled in blocks. Blocks are 32 bytes large (except for RGBA8), with their dimensions varying depending on the BPP of the image format.
 
For example, suppose you have a format that stores 4x4 blocks. Pixels 1-4 of the image will make up the first row of the first block; pixels 5-8 will make up the second row; 9-12 will make up the third row; 13-16 will make up the fourth row, completing the block; and then 17-20 will begin the first row of the second block, appearing directly to the right of the first row of the first block.
 
{| class="wikitable"
! ID
! Name
! Bits per pixel
! Block size
! Description
|-
|-
| 0x0
|<code>PMAB</code>
| I4
|Constant
| 4
|<code>bool</code>
| 8x8
|Particle-model additive blending
| 4-bit greyscale intensity values. Two pixels per byte.
|<code>AAPH</code> for particle models
|-
|-
| 0x1
|<code>VELn</code>
| I8
|Particle
| 8
|<code>WIND</code>, <code>GRAV</code>, <code>SWRL</code>, <code>BNCE</code>, <code>EXPL</code>, <code>IMPL</code>, <code>EMPL</code>, <code>LMPL</code>
| 8x4
|Velocity attachments (1-4)
| 8-bit greyscale intensity values.
|In addition to the initial velocity provided by the emitter, other simulated forces may be attached as velocity sources.
|-
|-
| 0x2
|<code>SORT</code>
| IA4
|Constant
| 8
|<code>bool</code>
| 8x4
|Particle depth sort
| 4-bit greyscale intensity values with an additional 4-bit alpha channel.
|Particle instances are sorted from back-to-front in view (for proper alpha-blending)
|-
|-
| 0x3
|<code>ZBUF</code>
| IA8
|Constant
| 16
|<code>bool</code>
| 4x4
|Particle z-buffer write
| 8-bit greyscale intensity values with an additional 8-bit alpha channel.
|Particle instances modify the z-buffer if set
|-
|-
| 0x4
|<code>LTYP</code>
| C4
|Constant
| 4
|<code>int</code>
| 8x8
|Lamp type enumeration
| 4-bit palette indices.
|Particle emitter is also a dynamic area lamp when non zero (0:off, 1:point, 2:spot)
|-
|-
| 0x5
|<code>LOFF</code>
| C8
|System
| 8
|<code>float3</code>
| 8x4
|Lamp offset vector
| 8-bit palette indices.
|Local offset from emitter to position lamp
|-
|-
| 0x6
|<code>LDIR</code>
| C14x2
|System
| 16
|<code>float3</code>
| 4x4
|Lamp direction vector
| Another palette format. Not used by any official textures.
|Local direction to cast spot lamps
|-
|-
| 0x7
|<code>LFOT</code>
| RGB565
|Constant
| 16
|<code>int</code>
| 4x4
|Lamp falloff type
| 16-bit colors without alpha.
|Affects how quadratic falloff coefficients are assigned in the lighting shader (0:constant, 1:inverse-linear, 2:inverse-quadratic)
|-
|-
| 0x8
|<code>LFOR</code>
| RGB5A3
|System
| 16
|<code>float</code>
| 4x4
|Lamp falloff radius
| 16-bit colors with alpha.
|Radius from emitter that lamp casts light
|-
|-
| 0x9
|<code>LCLR</code>
| RGBA8
|System
| 32
|<code>float4</code>
| 4x4
|Lamp color
| Uncompressed 32-bit colors with alpha.
|RGBA vector of lamp’s color
|-
|-
| 0xA
|<code>LINT</code>
| CMPR
|System
| 4
|<code>float</code>
| 8x8
|Lamp intensity
| Compressed textures (almost the same as DXT1, but with a couple small differences)
|Multiplied with lamp color to affect lamp’s energy
|}
|}


== External links ==
== PART Nodes ==
 
{{main|Effect Script}}
 
PART scripts share [[Effect Script#Script Nodes|effect nodes]] with other effect script formats.


* [http://wiki.tockdom.com/wiki/Image_Formats Custom Mario Kart Wiki]: More detailed information on each format, and how to decode them.
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 21:29, 14 March 2015

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 (PART ref) Concurrent particle-system Specifies an external particle script to construct into a parallel system that shares time and space.
IDTS Constant int (PART 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. In ORNT mode, this specifies the particle's aspect ratio instead.
POFS Particle float3 Particle offset Vector to translate particle instance within system
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 (TXTR ref), ATEX Texture attachment Specifies the texture resource to map to each particle instance’s surface.
TIND Constant int (TXTR 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