PTCL (File Format)

From Zenith
Revision as of 19:27, 25 May 2021 by Aboood40091 (talk | contribs)
Jump to navigation Jump to search

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 an 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 & 0x00800: Fragment First Texture Color Source

& 0x01000: Fragment Second Texture Color Source

& 0x02000: Fragment Primitive Color Source

& 0x04000: Fragment First Texture Alpha Source

& 0x08000: Fragment Second Texture Alpha Source

& 0x10000: Fragment Primitive Alpha Source

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 Particle Acceleration Transforms the acceleration vector for each particle using the particle's base Rotation and Translation.

(Before applying it to the particle's velocity vector)

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 Equidistant Particle Emission Emit a particle at every distance unit traveled by the emitter.

(Calls nw::eft::EmitterSimpleCalc::EmitSameDistance() when set)

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 Fragment 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: OutputColor = Color0
1: OutputColor = Color0 * Texture
2: OutputColor = Color0 * Texture + Color1 * ( 1 - Texture )
3: OutputColor = Color0 * Texture + Color1

0x298 uint Fragment 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: OutputAlpha = TextureA * Alpha
1: OutputAlpha = ( TextureA - ( 1 - Alpha ) ) * 2
2: OutputAlpha = TextureR * Alpha
3: OutputAlpha = ( TextureR - ( 1 - Alpha ) ) * 2

0x29C Unknown
4 bytes
Unknown -
0x2A0 uint Culling Value matches with nw::eft::DisplaySideType.

0: Cull None.
1: Cull Back.
2: Cull Front.

(Note that the polygon offset mode is always disabled)

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:

Vec3f addRot = emitterRandom.getF32Range(-1.0f, 1.0f) * emitterRotationRandom

0x338 Vec3f Translation Randomizer Used to calculate randomized additional translation. The additional translation is calculated as follows:

Vec3f addTrans = emitterRandom.getF32Range(-1.0f, 1.0f) * emitterTranslationRandom

0x344 uint Blend Type Value matches with nw::eft::BlendType.
0x348 uint Depth / Alpha Test Type Value matches with nw::eft::ZBufATestType.
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 (0, 1, 0).

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 Emitter Color 0 Multiplied by the emitter set's (runtime) color at runtime.
0x398 Color4f Emitter Color 1 Multiplied by the emitter set's (runtime) color at runtime.
0x3A8 float Emitter Alpha Multiplied by the emitter set's (runtime) alpha at runtime.
0x3AC float Equidistant Particle Emission

Distance Unit

Only for when equidistant particle emission is enabled.

Every unit of distance a particle should be emitted at when the emitter moves.

0x3B0 float Per-frame Emitter Traveled

Distance Clamp High

Only for when equidistant particle emission is enabled.

The clamp high for the distance the emitter traveled between frames.

0x3B4 float Per-frame Emitter Traveled

Distance Clamp Low

Only for when equidistant particle emission is enabled.

The clamp low for the distance the emitter traveled between frames.

0x3B8 float Per-frame Emitter Traveled

Distance Error (?)

Only for when equidistant particle emission is enabled.

If the distance traveled by the emitter between frames is less than this value, it will be set to the clamp low value.

0x3BC float Base Emission Rate Base value for number of particles to emit per frame.

Ignored if equidistant particle emission is enabled.

0x3C0 int Emission Start Frame At which frame after the emitter's initialization should emissions start.
0x3C4 int Emission End Frame At which frame after the emitter's initialization should emissions end.
0x3C8 int In-Emission Interval Interval in frames between emissions.
0x3CC int In-Emission Interval

Randomizer

Used to calculate randomized additional in-Emission interval frames. It is calculated as follows:

int addInterval = emitterRandom.getS32(emitIntervalRandom)

0x3D0 float Particle Velocity Magnitude Base velocity magnitude for each particle. A randomized direction vector is calculated depending on the emission

shape and is scaled by this magnitude to get the relative velocity vector of the particle.

The final velocity vector of the particle is the relative velocity vector added to the emitter velocity vector.

0x3D4 float Emitter Velocity Magnitude Magnitude of the velocity vector for the emitter.
0x3D8 float Particle Velocity Magnitude

Randomizer

Used to calculate randomized scale factor for the particle final velocity vector. It is calculated as follows:

float scaleF = 1.0f - emitterRandom.getF32() * velocityMagRandom

0x3DC Vec3f Emitter Velocity Direction Direction vector of the velocity vector for the emitter.
0x3E8 float Emitter Velocity Direction

Randomizer (?)

Used to randomize the velocity direction vector? The calculation is a bit complicated.
0x3EC Vec3f Particle Velocity Randomizer Used to calculate randomized additional velocity to the particle velocity. For each axis, it is calculated as follows:

float addVelocity[axis] = emitterRandom.getNormalizedVec3f()[axis] * velocityRandom[axis]

0x3F8 float Particle Velocity Scale Factor Yet another scale factor to apply to the velocity.

This value has a negative relationship with the emitter's emission speed (set at runtime).

0x3FC Vec3f Particle Acceleration Acceleration to apply to the particle veclocity.
0x408 float Particle Additional

XZ Velocity (?)

This value is scales the normalized vector of the XZ position, then the vector is added to the particle velocity.
0x40C float Position Randomizer Used to calculate randomized additional displacement for the emitter. It is calculated as follows:

Vec3f addPos = emitterRandom.getNormalizedVec3f() * emitterPosRandom

0x410 int Particle Maximum Lifespan For how long should a particle exist at max, in frames.
0x414 int Particle Lifespan Randomizer Used to calculate the randomized lifespan of the particle. It is calculated as follows:

int particleLifespan = particleMaxLifespan - emitterRandom.getS32(particleLifespanRandom)

0x418 uint Mesh Type Value matches with nw::eft::MeshType.

0: Particle

1: Primitive

0x41C uint Vertex Transform Mode -
0x420 Vec2f Rotation Pivot (As described in the vertex shader)
0x428 float Camera Offset (As described in the vertex shader)
0x42C nw::eft::TextureEmitterData[2] Texture Parameters Each emitter can have up to two textures.
0x51C uint Particle Color Source 0: First

1: Random

2: 3v4k Animation (?)

0x524 Color4f[3] Color 0 Table Particle color 0 retrieved from here depending on the source type.
0x554 Color4f[3] Color 1 Table Particle color 1 retrieved from here depending on the source type.
0x584 int[5][2] 3v4k-Color-Source related 5 tables of an element for each color (0, 1). Only used if the Particle Color Source is set to 3v4k Animation.
0x5AC float Emitter Set Color Scale Factor Used to scale the emitter set's (runtime) color and alpha.
0x5B0 Unknown
20 bytes
Unknown -
0x5C4 uint Fragment Texture Color

Blend Type

This value was noticed to be consistent with the texture color blend type 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: Texture = Texture0 * Texture1

1: Texture = Texture0 + Texture1

2: Texture = Texture0 - Texture1

0x5C8 uint Fragment Primitive Color

Blend Type

This value was noticed to be consistent with the primitive color blend type 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: OutputColor *= PrimitiveColor

1: OutputColor += PrimitiveColor

2: OutputColor -= PrimitiveColor

0x5CC uint Fragment Texture Alpha

Blend Type

This value was noticed to be consistent with the texture alpha blend type 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: TextureA = Texture0A * Texture1A

1: TextureA = Texture0A + Texture1A

2: TextureA = Texture0A - Texture1A

0x5D0 uint Fragment Primitive Alpha

Blend Type

This value was noticed to be consistent with the primitive alpha blend type 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: OutputAlpha *= PrimitiveAlpha

1: OutputAlpha += PrimitiveAlpha

2: OutputAlpha -= PrimitiveAlpha

0x5D4 Unknown
92 bytes
Unknown -
0x630 float Unknown -
0x634 float Alpha Fade Rate -
0x638 ubyte Fragment Shader Mode 0: Normal

1: Reflect

2: Distortion

0x639 ubyte Shader User Setting Possible values if set are from 1 to 8.

Sets the macro USR_SETTING_[val].

0x63A bool Fragment Soft Edge Sets the macro FRAGMENT_PARTICLE_SHADER_SOFT_EDGE.
0x63B bool Fragment Reflection Alpha Sets the macro REFRECTION_APPLY_ALPHA.
0x63C float Shader Param 0 Maps to u_shaderParam.x in the emitterStaticUniformBlock uniform block.
0x640 float Shader Param 1 Maps to u_shaderParam.y in the emitterStaticUniformBlock uniform block.
0x644 float Fragment Soft Edge

Fade Distance

(As described in the fragment shader)
0x648 float Fragment Soft Edge

Volume

(As described in the fragment shader)
0x64C char[16] User-defined macro 1 -
0x65C char[16] User-defined macro 2 -
0x66C uint Shader User Flag Possible values are from 0 to 31.

Sets the macro USR_FLAG_[val].

0x670 uint Shader User Switch Flag Possible values are from 0 to 31.

Sets the macro USR_SWITCH_FLAG_[val].

... ... ... ...

Depth / Alpha Test Type (nw::eft::ZBufATestType)

Alpha Test is always enabled and the Alpha Function is always Greater.

Stencil is always disabled.

Value Depth Test Depth Write Depth Function Alpha Reference Blending
0 Yes No Less Or Equal 0.0f Yes
1 No - - 0.0f Yes
2 Yes Yes Less Or Equal 0.5f No

Blend Type (nw::eft::BlendType)

Same options apply for both color and alpha blending.

Value Source Destination Function
0 Source Alpha 1 - Source Alpha Add
1 Source Alpha 1 Add
2 Source Alpha 1 Destination - Source
3 1 - Destination Color 1 Add
4 0 Source Color Add

Shader Table

This is the structure that points to all shader sources and binaries in this file. Size is 0x10 bytes.

Offset Data Type Name Description
0x0 uint Number of Shader Programs -
0x4 uint Section Size -
0x8 uint Shader Source Info Offset The offset to the shader source info structure, relative to the start of this section.
0xC uint Shader Programs Offset The offset to the first shader program, relative to the start of this section.

Shader Program

This structure describes a (binary) shader program and its parameters. Size is 0x5C.

There are as many instances of it as the number of shader binaries defined in the shader table.

Offset Data Type Name Description
0x00 nw::eft::VertexShaderKey Vertex Shader Key Parameters unique to the vertex shader of this shader program.

Can be used as a key to find the corresponding shader program for each emitter.

0x20 nw::eft::FragmentShaderKey Fragment Shader Key Parameters unique to the fragment shader of this shader program.

Can be used as a key to find the corresponding shader program for each emitter.

0x50 Unknown
4 bytes
Geometry Shader Key (?) Unused.
0x54 uint Shader Binary Size -
0x58 uint Shader Binary Offset The offset to the shader binary of this shader program, relative to the end of all shader programs in the shader table.

This is a GFD shader file (.gsh) containing the vertex, fragment and geometry shaders. (Only a single instance of each type if present)

Vertex Shader Key (nw::eft::VertexShaderKey)

Size is 0x20 bytes. Padding is skipped.

Offset Data Type Name Description
0x00 ubyte Vertex Transform Mode -
0x01 ubyte Vertex Rotation Mode Rotation is considered when this value is non-zero.
0x02 ubyte Shader User Setting Possible values if set are from 1 to 8.
0x03 ubyte Stripe Type (As described in the vertex stripe shader)

0: STRIPE_TYPE_BILLBOARD

1: STRIPE_TYPE_EMITTER_MATRIX

2: STRIPE_TYPE_EMITTER_UP_DOWN

0x04 bool Stripe Follows Emitter (As described in the vertex stripe shader)

STRIPE_TYPE_EMITTER_COORD

0x05 bool Is Primitive Emitter's mesh type is primitive.
0x08 uint Shader User Flag Possible values are from 0 to 31.

Sets the macro USR_FLAG_[val].

0x0C uint Shader User Switch Flag Possible values are from 0 to 31.

Sets the macro USR_SWITCH_FLAG_[val].

0x10 char[16] User-defined macro -
Vertex Transform Mode

(As described in the vertex / stripe shader)

Value Mode
0 Billboard
1 Plate XY
2 Plate XZ
3 Directional Y
4 Directional Polygon
5 Stripe
6 Complex Stripe
7 Primitive
8 Y Billboard

Fragment Shader Key (nw::eft::FragmentShaderKey)

Size is 0x30 bytes. Padding is skipped.

Offset Data Type Name Description
0x00 ubyte Fragment Shader Mode 0: Normal

1: Reflect

2: Distortion

0x01 bool Fragment Soft Edge -
0x02 ubyte Fragment Shader Mode 0: Emitter has only 1 texture

2: Emitter has two textures

0x03 ubyte Fragment Color Mode (See Simple Emitter Data)
0x04 ubyte Fragment Alpha Mode (See Simple Emitter Data)
0x05 ubyte Shader User Setting Possible values if set are from 1 to 8.
0x06 bool Is Primitive Emitter's mesh type is primitive.
0x07 ubyte Fragment Texture Color

Blend Type

(See Simple Emitter Data)
0x08 ubyte Fragment Texture Alpha

Blend Type

(See Simple Emitter Data)
0x09 ubyte Fragment Primitive Color

Blend Type

(See Simple Emitter Data)
0x0A ubyte Fragment Primitive Alpha

Blend Type

(See Simple Emitter Data)
0x0B ubyte Fragment First Texture

Color Source

0: Color

1: One

0x0C ubyte Fragment Second Texture

Color Source

0: Color

1: One

0x0D ubyte Fragment Primitive

Color Source

0: Color

1: One

0x0E ubyte Fragment First Texture

Alpha Source

0: Alpha

1: One

0x0F ubyte Fragment Second Texture

Alpha Source

0: Alpha

1: One

0x10 ubyte Fragment Primitive

Alpha Source

0: Alpha

1: One

0x11 bool Fragment Reflection Alpha (See Simple Emitter Data)
0x14 uint Shader User Flag Possible values are from 0 to 31.
0x18 uint Shader User Switch Flag Possible values are from 0 to 31.
0x1C char[16] User-defined macro -
0x2C Unknown
4 bytes
Unused -

Shader Source Info

This is the section containing the offsets and sizes of all shader sources. Size is 0x48 bytes.

There is only a single instance of it in a single PTCL file.

This section can be omitted as it is not used in runtime, but NSMBU includes it.

Offset Data Type Name Description
0x00 uint Number of Shader Sources How many of the below shader sources are used.
0x04 uint Section Size Including all shader sources and files.
0x08 Shader Source Vertex Shader

(eft_Particle.vsh)

This is a shader provided by Nintendo in the NintendoWare SDK.
0x10 Shader Source Fragment Shader

(eft_Particle.fsh)

This is a shader provided by Nintendo in the NintendoWare SDK.
0x18 Shader Source Stripe Vertex Shader

(eft_Stripe.vsh)

This is a shader provided by Nintendo in the NintendoWare SDK.
0x20 Shader Source Geometry Shader (?) Unused in NSMBU. It does not seem like the geometry shader can be stored anywhere else.
0x28 Shader Source User Vertex Shader

(UsrShader.vsh)

Anything the user codes in here is added after the declaration vertex shader and before the vertex shader source before compilation.
0x30 Shader Source User Fragment Shader

(UsrShader.fsh)

Anything the user codes in here is added after the declaration fragment shader and before the fragment shader source before compilation.

Unused in NSMBU.

0x38 Shader Source Declaration Vertex Shader

(eft_ParticleDeclaration.vsh)

This is a shader provided by Nintendo in the NintendoWare SDK.

A shader to be added to the top of the vertex shader source before compilation.

It includes important declarations of things such as uniform blocks.

0x40 Shader Source Declaration Fragment Shader

(eft_ParticleDeclaration.fsh)

This is a shader provided by Nintendo in the NintendoWare SDK.

A shader to be added to the top of the fragment shader source before compilation.

It includes important declarations of things such as uniform blocks.

Shader Source

A structure describing a single shader source file. Size is 8 bytes.

Offset Data Type Name Description
0x0 uint Length Length of the source file.
0x4 uint Offset Offset to the source file, which is a string encoded using SHIFT-JIS, relative to the end of the Shader Source Info structure.