Katana SDK

Dreamcast SDK

Katana SDK (Dreamcast SDK for SEGA Library) was the official SEGA development kit for the Dreamcast console that came with Dreamcast development units. The Dreamcast SDK had a number of libraries and APIs that many developers used in their games. The SDK evolved together with the console, and earlier versions of the SDK had fewer features or targeted different hardware. Updates to the SDK continued after the Dreamcast's release, and some releases were as late as 2001.

The Dreamcast SDK consisted of several subsystems:

The Shinobi library set interfaced with the CPU, cache and memory.

The Kamui API (low level) and the Ninja library (high level) provided access to graphics.

The Manatee and Audio64 subsystems interfaced with sound hardware.

Over the years there have been multiple SDK leaks, including parts of source code for older revisions. For modding purposes, we should focus on the Ninja library, which is used by the Sonic Adventure games.

Common Types

The following types are used in Shinobi and Ninja headers:

Ninja type	C type	Size	Description
Sint8	char	1	Signed 8-bit integer
Uint8	unsigned char	1	Unsigned 8-bit integer
Sint16	__int16	2	Signed 16-bit integer
Uint16	unsigned __int16	2	Unsigned 16-bit integer
Sint32	int	4	Signed 32-bit integer
Uint32	unsigned int	4	Unsigned 32-bit integer
Bool	unsigned int	4	Unsigned 32-bit integer that is either TRUE (1) or FALSE (0)
Float and Float32	float	4	32-bit floating point
Float64	double	8	64-bit floating point
Void	void		Pointer

Ninja Model Formats

The Ninja library can use two model formats, the Basic model and the Chunk model. Basic models were introduced early on, while Chunk models were added later as a format that is optimized for better performance on Dreamcast hardware. The Basic format is easier to read as text.

Ninja Basic Model

The Basic model consists of the following structs:

Material struct (NJS_MATERIAL) and Material Array

The material affects how the model's surface looks. It defines which texture to use, whether to use environment mapping etc.

Field	Offset	Type	Size	Description	Notes
diffuse	0	NJS_COLOR	4	Diffuse color.	In SA1 with palette lighting, only alpha is used.
specular	0x4	NJS_COLOR	4	Specular color.	In SA1 with palette lighting, only alpha is used. The alpha value of 0 is treated as the "ignore specular" flag.
exponent	0x8	Float	4	Specular color strength.
attr_texId	0xC	Uint32	4	Texture ID.
attrflags	0x10	Uint32	4	Material flags.

Size: 20 bytes (0x14).

NJS_COLOR is a union that can be either NJS_BGRA, NJS_TEX or Uint32 (4 bytes).

NJS_BGRAis a 4-byte struct that consists of blue, green, red and alpha values ranging from 0 to 255. For example, the color A255 R178 G178 B178 would be 0xFFB2B2B2.

NJS_TEX (4 bytes) is a struct commonly used in UVs. It consists of two Sint16 values: one for U (horizontal) and one for V (vertical). UVs used in SA1 range from 0 to 255.

The following flags can be used in attrflags:

Flag name	Flag bit	Description	Comments
NJD_FLAG_IGNORE_LIGHT	25	Ignore lighting.
NJD_FLAG_USE_FLAT	24	Flat lighting.	Has no effect when palette-based lighting in SA1 is used.
NJD_FLAG_DOUBLE_SIDE	23	Double-sided mesh.	May be used for collision.
NJD_FLAG_USE_ENV	22	Enable environment mapping.
NJD_FLAG_USE_TEXTURE	21	Enable texture.
NJD_FLAG_USE_ALPHA	20	Enable transparency.
NJD_FLAG_IGNORE_SPECULAR	19	Disable specular lighting.	Used for specular palette selection in palette-based lighting in SA1.
NJD_FLAG_FLIP_U	18	Flip Us.
NJD_FLAG_FLIP_V	17	Flip Vs.
NJD_FLAG_CLAMP_U	16	Clamp Us.
NJD_FLAG_CLAMP_V	15	Clamp Vs.
NJD_FLAG_USE_ANISOTROPIC	12	Enable anisotropic filtering,	Unused.
NJD_FLAG_PICK	7	"Pick status"	Unused.

Basic models' materials are stored in arrays of NJS_MATERIAL.

NJS_MATERIAL matlist_004451A8[] = {
	{ { 0xFFFFFFFF }, { 0xFFFFFFFF }, 11, 14, NJD_D_100 | NJD_FILTER_BILINEAR | NJD_FLAG_CLAMP_V | NJD_FLAG_CLAMP_U | NJD_FLAG_IGNORE_SPECULAR | NJD_FLAG_USE_TEXTURE | NJD_DA_INV_SRC | NJD_SA_SRC },
	{ { 0xFFB2B2B2 }, { 0xFFFFFFFF }, 11, 13, NJD_D_100 | NJD_FILTER_BILINEAR | NJD_FLAG_CLAMP_V | NJD_FLAG_CLAMP_U | NJD_FLAG_IGNORE_SPECULAR | NJD_FLAG_USE_ALPHA | NJD_FLAG_USE_TEXTURE | NJD_DA_INV_SRC | NJD_SA_SRC },
	{ { 0xFFB2B2B2 }, { 0xFFFFFFFF }, 11, 15, NJD_D_100 | NJD_FILTER_BILINEAR | NJD_FLAG_CLAMP_V | NJD_FLAG_CLAMP_U | NJD_FLAG_IGNORE_SPECULAR | NJD_FLAG_USE_TEXTURE | NJD_DA_INV_SRC | NJD_SA_SRC }
};

Poly Array

The poly array in an array of Sint16 that lists the model's primitives (polygons). It is commonly formatted with the number of vertices (points) followed by vertex indices. The indices are used to pick the specific vertices from the model's vertices array.

Here is an example of a polys array. The 4 in each new line indicates the number of vertices in the surface, and the following four values are vertex indices.

Sint16 poly_0000002C[] = {
	4, 13, 12, 5, 4,
	4, 9, 8, 1, 0,
	4, 11, 10, 3, 2,
	4, 15, 14, 7, 6
};

The number of vertices can be ORd with 0x8000, which indicates a flipped surface. TODO: Confirm this.

UV Array

The UV array is an array of NJS_TEX. UVs determine how the texture is applied to the model's surface. For exampled, bigger UV values will make the texture "zoomed in", adding values to U will make the texture offset horizontally etc. UVs are per-polygon.

NJS_TEX uv_000003A4[] = {
	{ 130, 145 },
	{ 212, 225 },
	{ 124, 230 },
	// And so on...
};

Vertex Color Array

This is an array of NJS_COLOR that determines the colors of the model's vertices. Vertex colors are used per-polygon, not per-vertex.

NJS_COLOR vcolor_0000003C[] = {
	{ 0xFFFFFFDF },
	{ 0xFFFFFFFF },
	{ 0xFFFFDFBF },
	{ 0xFFFFFFFF },
	{ 0xFFFFDFBF },
	// And so on...
};

Polynormal Array

Normals determine the model's lighting and environment mapping distortion. Normals can be specified per-vertex or por-polygon. Almost no models in SA1 use per-poly normals (polynormals), with the exception of Tails' tails and Sonic's stretchy shoes. When polynormals are used, this is the array they are expected to be in.

Normals and polynormals are defined as arrays of NJS_VECTOR. NJS_VECTOR consists of three floats for X, Y and Z.

NJS_VECTOR polynormal_007383D8[] = {
	{ 0 },
	{ 0 },
	{ 0 },
	{ 0 },
	{ 0 },
	{ 0 }
};

Polygon Attribute Array

This is an array of Uint32 containing polygon-specific attributes. It is not used in Sonic Adventure games.

Meshset Struct (NJS_MESHSET) and Meshset Array

The NJS_MESHSET struct defines a single mesh.

Field	Offset	Type	Size	Description	Notes
type_matId	0	Uint16	2	Diffuse color.	Bits 0-13 are material id (0-4095) in the material array. Bits 14-15 are meshset type bits (see below).
nbMesh	0x2	Uint16	2	Number of meshes.
*meshes	0x4	Sint16*	4	Pointer to the poly array.
*attrs	0x8	Uint32*	4	Pointer to the poly attribute array.	Unused in SA games.
*normals	0xC	NJS_VECTOR*	4	Pointer to the polynormal array.	Almost never used.
*vertcolor	0x10	NJS_COLOR*	4	Pointer to the vertex color array.
*vertuv	0x14	NJS_TEX*	4	Pointer to the UV array.
buffer	0x18	void	4	Pointer to the Direct3D mesh buffer.	Always null. SADX PC 2004, SADX X360 and SADX PS3 only.

In the 2004 PC port of SADX this struct contains an extra field for the mesh buffer (buffer). This version of the struct is used in the PC, X360 and PS3 versions.

SA2 and Gamecube versions of SADX use the original struct without the extra field.

In SADX Mod Loader headers the original Ninja version is NJS_MESHSET, and the one with the extra field is NJS_MESHSET_SADX.

In the SADX X360 prototype with symbols, the one with the extra field is NJS_MESHSET, and the original Ninja version is NJS_MESHSET_OLD.

The size of the original NJS_MESHSET is 24 (0x18) bytes, and the size of NJS_MESHSET_SADX is 28 (0x1C) bytes.

Meshset type bits are as follows:

Meshset type	Value	Description
NJD_MESHSET_3	0x0000	Default mesh type. Technically identical to NJD_MESHSET_TRIMESH.
NJD_MESHSET_4	0x4000	Quad.
NJD_MESHSET_N	0x8000	N-Gon.
NJD_MESHSET_TRIMESH	0xC000	Trimesh, the most common meshset type.
NJS_MESHSET_MASK	0xC000	Meshset type mask.

To get the material ID from the type_matId field in your code, use type_matId & ~NJD_MESHSET_MASK.

Ninja Ports to Other Systems

To be continued...