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 the 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)

Field	Offset	Type	Size	Description
diffuse	0	NJS_COLOR	4	Diffuse color.
specular	0x4	NJS_COLOR	4	Specular color.
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.

NJS_BGRAis a 4-byte struct that consists of B, G, R and A values ranging from 0 to 255. For example, the color A255 R178 G178 B178 would be 0xFFB2B2B2.

NJS_TEX is a struct commonly used in UVs. It consists of two Sint16 values for U and V.

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.

Polys Array

The polys array in an array of Sint16 that lists the model's polygons. It is commonly formatted with the number of vertices followed by vertex IDs in the model's vertex 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.

To be continued...