PTCL (File Format): Difference between revisions
Aboood40091 (talk | contribs) No edit summary |
Aboood40091 (talk | contribs) mNo edit summary |
||
Line 89: | Line 89: | ||
|Unknown<br>12 bytes |
|Unknown<br>12 bytes |
||
|Unknown |
|Unknown |
||
|These 12 bytes are not referenced in the code. |
|These 12 bytes are not referenced in the code.<br>Newer versions of the format still have these 12 unknown bytes. |
||
|} |
|} |
||
Revision as of 01:47, 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 5 bytes |
Unknown | - |
0x285 | bool
|
No Emission During Fade | Stops particle emission when the emitter set is fading. |
0x286 | Unknown 2 bytes |
Unknown | - |
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 | Unknown 2 bytes |
Unknown | - |
0x28C | uint
|
Particle Rotation Mode | Rotation is considered when this value is non-zero. |
0x290 | uint
|
Particle Sync Mode | 0: All particles use the emitter's base Scale, Rotation and Translation. 1: Each particle has a unique Scale, Rotation and Translation. 2: All particles use the emitter's base Translation, but have unique 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 Shape | Used as an index to a table of shape-based particle emit functions. TODO: List shapes. |
... | ... | ... | ... |