PTCL (File Format)

PTCL is the binary serialization format for nw::eft (NintendoWare Eft Library) particle effect resources.

It has went 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(?)	I never found any references to this value 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 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.