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. Perhaps uncleared padding?

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 nw::eft::EmitterSimpleCalc::EmitSameDistance() when set)
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: OutputColor = Color0 1: OutputColor = Color0 * Texture 2: OutputColor = Color0 * Texture + Color1 * ( 1 - Texture ) 3: OutputColor = Color0 * Texture + Color1
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: 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.
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. 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.
...	...	...	...