PTCL (File Format)

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 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	(As described in the vertex shader) 0: Billboard 1: Plate XY 2: Plate XZ 3: Directional Y 4: Directional Polygon 5: Stripe 6: Complex Stripe 7: Primitive 8: Y Billboard
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	Shader Variation Type	0: Shader with no user defined macro set 1: Shader with first user defined macro set 2: Shader with second user defined macro set
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