PTCL (File Format): Difference between revisions
Aboood40091 (talk | contribs) mNo edit summary |
Aboood40091 (talk | contribs) (Added more data for the particle emission shapes.) |
||
Line 266: | Line 266: | ||
|- |
|- |
||
|0x280 |
|0x280 |
||
|Unknown<br> |
|Unknown<br>3 bytes |
||
⚫ | |||
⚫ | |||
|- |
|||
|0x283 |
|||
|<code>bool</code> |
|||
|Transform Acceleration |
|||
|Transforms the acceleration vector for each particle using the particle's base Rotation and Translation. |
|||
(Before applying it to the velocity) |
|||
|- |
|||
|0x284 |
|||
⚫ | |||
|Unknown |
|Unknown |
||
| - |
| - |
||
Line 276: | Line 287: | ||
|- |
|- |
||
|0x286 |
|0x286 |
||
|<code>ubyte</code> |
|||
⚫ | |||
|Latitude Division Array Index |
|||
⚫ | |||
| Only for the <code>Equally-Partitioned Spherical Surface</code> particle emission function. |
|||
⚫ | |||
Used as an index to a table containing arrays of latitudes of equally-divided parts of a sphere surface. |
|||
It determines possible latitudes the particle can be spawned at. |
|||
|- |
|||
|0x287 |
|||
|<code>bool</code> |
|||
|Random Arc Start Angle |
|||
|Only for the arc-shaped particle emission functions, except for <code>Equally-Partitioned Spherical Surface</code>. |
|||
Determines whether to use the arc start angle stored in this emitter or to generate a random one. |
|||
|- |
|- |
||
|0x288 |
|0x288 |
||
Line 292: | Line 312: | ||
|- |
|- |
||
|0x28A |
|0x28A |
||
|<code>bool</code> |
|||
⚫ | |||
|No Random Latitude |
|||
|Only for spherical surface particle emission functions. |
|||
Determines whether to use the latitude stored in this emitter or to generate a random one. |
|||
The arc start angle and arc length values are ignored when this is enabled. |
|||
|- |
|||
|0x28B |
|||
|Unknown<br>1 byte |
|||
|Unknown |
|Unknown |
||
| - |
| - |
||
|- |
|- |
||
|0x28C |
|0x28C |
||
Line 304: | Line 332: | ||
|<code>uint</code> |
|<code>uint</code> |
||
|Particle Sync Mode |
|Particle Sync Mode |
||
|0: All particles |
|0: All particles' base transformation is set to the emitter's base Scale, Rotation and Translation.<br>1: Each particle has an independent base transformation (Scale, Rotation and Translation).<br>2: All particles follow the emitter's base Translation, but have independent base Scale and Rotation. |
||
|- |
|- |
||
|0x294 |
|0x294 |
||
Line 383: | Line 411: | ||
|Particle Emission Shape |
|Particle Emission Shape |
||
|Used as an index to a table of shape-based particle emission functions. TODO: List shapes. |
|Used as an index to a table of shape-based particle emission functions. TODO: List shapes. |
||
|- |
|||
|0x350 |
|||
|<code>Vec3f</code> |
|||
|Particle Emission Shape Extent |
|||
|The extent of the shape of the particle emission function. |
|||
This vector is multiplied by the emitter's base scale at runtime. |
|||
|- |
|||
|0x35C |
|||
|<code>uint</code> |
|||
|Arc Start Angle |
|||
|Only for the arc-shaped particle emission functions, except for <code>Equally-Partitioned Spherical Surface</code>. |
|||
|- |
|||
|0x360 |
|||
|<code>uint</code> |
|||
|Arc Length |
|||
|Only for the arc-shaped particle emission functions, except for <code>Equally-Partitioned Spherical Surface</code>. |
|||
|- |
|||
|0x364 |
|||
|<code>float</code> |
|||
|Fill Exclude Percentage |
|||
|Only for the "fill" particle emission functions. Which % of the emission shape should not contain particles. |
|||
|- |
|||
|0x368 |
|||
|<code>float</code> |
|||
|Latitude |
|||
|Only for spherical surface particle emission functions. |
|||
Minimum latitude at which the particle is spawned. |
|||
|- |
|||
|0x36C |
|||
|<code>Vec3f</code> |
|||
|Latitude Basis |
|||
|Only for the <code>Equally-Partitioned Spherical Surface</code> particle emission function. |
|||
The basis to which the latitude should be transformed. |
|||
The original basis is <code>(0, 1, 0)</code>. |
|||
|- |
|||
|0x378 |
|||
⚫ | |||
|Unknown |
|||
| - |
|||
|- |
|||
|0x37C |
|||
|<code>Vec3f</code> |
|||
|Particle Emission Shape Extent |
|||
Scale Factor |
|||
|This vector is multiplied by the particle emission shape extent to get the final extent. |
|||
|- |
|||
|0x388 |
|||
|<code>Color4f</code> |
|||
|Color 0 |
|||
| - |
|||
|- |
|||
|0x398 |
|||
|<code>Color4f</code> |
|||
|Color 1 |
|||
| - |
|||
|- |
|||
|0x3A8 |
|||
|<code>float</code> |
|||
|Alpha |
|||
| |
|||
|- |
|- |
||
|... |
|... |
Revision as of 23:34, 23 May 2021
PTCL is the binary serialization format for nw::eft
(NintendoWare Eft Library) particle effect resources.
It has gone through several revisions across games. Known versions are: 0x28
(New Super Mario Bros. U), 0x41
(Mario Kart 8) and 0x42
(Super Mario Maker and later).
Known magic numbers are SPBD
(version 0x28) and EFTF
(other known versions).
While it is unknown what the former stands for, the latter stands for "Eft Cafe", where Eft is the name of the library.
Through a debug message left in the library, it has been determined that there exists a separate format for particle effect resources on Windows with a different magic number. The magic number is speculated to be EFTW
.
This page documents version 0x28
of the format. For version 0x41
(and possibly version 0x42
), visit this page.
File Header
The structure that the file begins with. Size is 0x40 bytes.
Offset | Data Type | Name | Description |
---|---|---|---|
0x00 | char[4]
|
Magic number (SPBD )
|
This value is not checked in version 0x28 and can be set to anything. |
0x04 | uint
|
Version | - |
0x08 | uint
|
Number of Emitter Sets | The number of emitter sets that follow this header. |
0x0C | Unknown 4 bytes |
Unknown | This value is not referenced in the code. Looks to be 0 in all PTCL files I checked. |
0x10 | uint
|
String / Name Table Offset | The offset to a table of null-terminated strings, which are the names of emitters and emitter sets. Encoding is not known, but it's very likely to be SHIFT-JIS. |
0x14 | uint
|
Texture Data Table Offset | The offset to section where all the raw texture data for emitters is stored. |
0x18 | uint
|
Texture Data Table Size | - |
0x1C | uint
|
Shader Table Offset | The offset to the section that points to all shader sources / binaries. |
0x20 | uint
|
Shader Table Size | - |
0x24 | uint
|
Keyframe Animation Array Table Offset | - |
0x28 | uint
|
Keyframe Animation Array Table Size | - |
0x2C | uint
|
Primitive Info Table Offset | The offset to a table of primitive data that is used by emitters. |
0x30 | uint
|
Primitive Info Table Size | - |
0x34 | Unknown 12 bytes |
Unknown | These 12 bytes are not referenced in the code. Newer versions of the format still have these 12 unknown bytes. |
Emitter Set
This structure immediately follows the file header. It is a set of several emitters to create a single effect. Size is 0x1C bytes.
There are as many instances of it as the number of emitter sets defined in the file header.
Offset | Data Type | Name | Description |
---|---|---|---|
0x00 | uint
|
User Data (?) | No references to this value have been found in the Eft library, but it is used by NSMBU's PtclMgr to determine the emitter group to place this emitter set in. |
0x04 | Unknown 4 bytes |
Unknown | Never found any references to this value. |
0x08 | uint
|
Name Offset | The offset to the name of this emitter set, relative to the name table specified in the file header. |
0x0C | char*
|
Name | Pointer set at runtime for convenience. |
0x10 | uint
|
Number of Emitters | The number of emitter references (therefore emitters) for this emitter set. |
0x14 | uint
|
Emitter References Offset | The offset to the first emitter reference for this emitter set. Offset is absolute. |
0x18 | Pointer(?) | Emitter References (?) | This value is not referenced in the code, but guessing from a pattern that exists in this file format, it was probably meant to be a pointer to the first emitter reference for this emitter set. |
Emitter Reference
This structure exists for every emitter in each emitter set. Size is 8 bytes.
There are as many instances of it as the number of emitters defined in the emitter set.
Offset | Data Type | Name | Description |
---|---|---|---|
0x0 | uint
|
Data Offset | The offset to the data for this emitter. Offset is absolute. |
0x4 | Pointer | Data | Pointer set at runtime for convenience. |
Emitter Data
The base data of the emitter. Size is 0x280 bytes.
TODO: Simple and Complex data.
Offset | Data Type | Name | Description |
---|---|---|---|
0x000 | uint
|
Type | 0 = Simple, 1 = Complex. |
0x004 | uint
|
Flags | |
0x008 | uint
|
Random Seed | The number used to initialize the random number generator of this emitter. If 0 or 0xFFFFFFFF, the global random number generator is used to generate a seed. |
0x00C | uint
|
User Data (?) | Same as the parent emitter set's user data. |
0x010 | uint
|
Unknown | This value is not referenced in the code, except for what looks to be an inlined copy constructor for this structure. Perhaps more user data? |
0x014 | float[8]
|
Unknown | This array is not referenced in the code, except for what looks to be an inlined copy constructor for this structure. Perhaps more user data? |
0x034 | int
|
Custom Action Callback ID | Which custom callback to trigger when an action occurs. TODO: List of actions. |
0x038 | uint
|
Name Offset | The offset to the name of this emitter set, relative to the name table specified in the file header. |
0x03C | char*
|
Name | Pointer set at runtime for convenience. |
0x040 | nw::eft::TextureRes[2]
|
Textures | Each emitter can have up to two textures. |
0x268 | Pointer | Keyframe Animation Array | Pointer set at runtime for convenience. |
0x26C | uint
|
Keyframe Animation Array Offset | The offset to the Keyframe Animation Array, relative to the table specified in the file header. |
0x270 | uint
|
Keyframe Animation Array Size | - |
0x274 | Pointer (?) | Primitive Info (?) | Value unused. |
0x278 | uint
|
Primitive Info Size | - |
0x27C | uint
|
Primitive Index | The index into the primitive info table specified in the file header. |
Simple Emitter Data (nw::eft::SimpleEmitterData
)
This structure inherits / extends the base emitter data structure.
It is used when the Type
field is set to Simple
. Size is 0x6F4 bytes (0x474 additional bytes).
Offset | Data Type | Name | Description |
---|---|---|---|
0x000 | Emitter Data | - | - |
0x280 | Unknown 3 bytes |
Unknown | - |
0x283 | bool
|
Transform Acceleration | Transforms the acceleration vector for each particle using the particle's base Rotation and Translation.
(Before applying it to the velocity) |
0x284 | Unknown 1 byte |
Unknown | - |
0x285 | bool
|
No Emission During Fade | Stops particle emission when the emitter set is fading. |
0x286 | ubyte
|
Latitude Division Array Index | Only for the Equally-Partitioned Spherical Surface particle emission function.
Used as an index to a table containing arrays of latitudes of equally-divided parts of a sphere surface. It determines possible latitudes the particle can be spawned at. |
0x287 | bool
|
Random Arc Start Angle | Only for the arc-shaped particle emission functions, except for Equally-Partitioned Spherical Surface .
Determines whether to use the arc start angle stored in this emitter or to generate a random one. |
0x288 | bool
|
Is Visible | Determines if to draw the emitter. For complex emitters, child emitters are not affected by this. |
0x289 | bool
|
Same Distance Emission | Should emitter re-emission follow its previous trajectory, I think.
(Calls |
0x28A | bool
|
No Random Latitude | Only for spherical surface particle emission functions.
Determines whether to use the latitude stored in this emitter or to generate a random one. The arc start angle and arc length values are ignored when this is enabled. |
0x28B | Unknown 1 byte |
Unknown | - |
0x28C | uint
|
Particle Rotation Mode | Rotation is considered when this value is non-zero. |
0x290 | uint
|
Particle Sync Mode | 0: All particles' base transformation is set to the emitter's base Scale, Rotation and Translation. 1: Each particle has an independent base transformation (Scale, Rotation and Translation). 2: All particles follow the emitter's base Translation, but have independent base Scale and Rotation. |
0x294 | uint
|
Color Mode (?) | This value was noticed to be consistent with the color mode in the shader (binary and source). The value is only used in the code as part of the key to the fragment shader for this emitter. 0: |
0x298 | uint
|
Alpha Mode (?) | This value was noticed to be consistent with the alpha mode in the shader (binary and source). The value is only used in the code as part of the key to the fragment shader for this emitter. 0: |
0x29C | Unknown 4 bytes |
Unknown | - |
0x2A0 | uint
|
Culling | Value matches with nw::eft::DisplaySideType .
0: Cull None. |
0x2A4 | Unknown 100 bytes |
Unknown | - |
0x308 | Vec3f
|
Base Scale | Base Scale for all particles. |
0x314 | Vec3f
|
Base Rotation | Base Rotation for all particles. |
0x320 | Vec3f
|
Base Translation | Base Translation for all particles. |
0x32C | Vec3f
|
Rotation Randomizer | Used to calculate randomized additional rotation. The additional rotation is calculated as follows:
|
0x338 | Vec3f
|
Translation Randomizer | Used to calculate randomized additional translation. The additional translation is calculated as follows:
|
0x344 | uint
|
Blend Type | Value matches with nw::eft::BlendType . TODO: Document this.
|
0x348 | uint
|
Alpha Test Type | Value matches with nw::eft::ZBufATestType . TODO: Document this.
|
0x34C | uint
|
Particle Emission Shape | Used as an index to a table of shape-based particle emission functions. TODO: List shapes. |
0x350 | Vec3f
|
Particle Emission Shape Extent | The extent of the shape of the particle emission function.
This vector is multiplied by the emitter's base scale at runtime. |
0x35C | uint
|
Arc Start Angle | Only for the arc-shaped particle emission functions, except for Equally-Partitioned Spherical Surface .
|
0x360 | uint
|
Arc Length | Only for the arc-shaped particle emission functions, except for Equally-Partitioned Spherical Surface .
|
0x364 | float
|
Fill Exclude Percentage | Only for the "fill" particle emission functions. Which % of the emission shape should not contain particles. |
0x368 | float
|
Latitude | Only for spherical surface particle emission functions.
Minimum latitude at which the particle is spawned. |
0x36C | Vec3f
|
Latitude Basis | Only for the Equally-Partitioned Spherical Surface particle emission function.
The basis to which the latitude should be transformed. The original basis is |
0x378 | Unknown 4 bytes |
Unknown | - |
0x37C | Vec3f
|
Particle Emission Shape Extent
Scale Factor |
This vector is multiplied by the particle emission shape extent to get the final extent. |
0x388 | Color4f
|
Color 0 | - |
0x398 | Color4f
|
Color 1 | - |
0x3A8 | float
|
Alpha | |
... | ... | ... | ... |