CEBK ("KBEC") - Cell Bank

Author(s): Gonhex
Research: NOCASH, Gonhex

The cell bank creates a number of cells by combining tiles and selecting a palette for each cell. It usually operates on dimensionless (1D mapped) character graphics and is used in combination with the animation runtime to display dynamic objects.

Data Structure
Specification
- Dimension Keys
- Files
TODO

Data Structure

Section Container

struct ContainerSectionCEBK
{
    /* 0x0    */ struct NitroSectionHeader sectionHeader;
    /* 0x8    */ struct ContainerCEBK sectionData;
    /* append */ uint8_t paddingDWORD[?];
}; // entry size = sectionHeader.lengthSection

Field Name	Description	Data Type
sectionHeader	Header of this section. `sectionHeader.signature = "KBEC"`.	NitroSectionHeader
sectionData	Content of this section.	ContainerCEBK
paddingDWORD	Padding for DWORD alignment, if LABL-section follows.	uint8_t[]

CEBK Container

struct ContainerCEBK
{
    // header
    /* 0x00 */ uint16_t numberCells;
    /* 0x02 */ uint16_t useBounds;      // rename?
    /* 0x04 */ uint32_t offsetDataCell;
    /* 0x08 */ uint32_t sizeBoundary;
    /* 0x0C */ uint32_t unknown0;
    /* 0x10 */ uint32_t unknown1;
    /* 0x14 */ uint32_t unknown2;
    
    // data
    /* offsetDataCell */ struct Cell dataCell[numberCells];
    /* offsetDataCell + numberCells * (8 << useBounds) */ struct ObjectAttribute dataAttributes[?];
}; // entry size = sectionHeader.lengthSection - 0x8

Field Name	Description	Data Type
numberCells	Number of cells.	uint16_t
useBounds	Extended cell struct, if `== 1`.	uint16_t
offsetDataCell	Offset to the cell table data section relative to `ContainerCEBK`.	uint32_t
sizeBoundary	Size boundary, `result = sizeBoundary << 6`.	uint32_t
unknown0	Unused offset?	uint32_t
unknown1	Unused offset?	uint32_t
unknown2	Unused offset?	uint32_t
dataCell	Cell configuration table.	Cell[]
dataAttributes	Object attributes.	ObjectAttribute[]

Cell

struct Cell
{
    // header
    /* 0x0 */ uint16_t numberObjects;
    /* 0x2 */ uint8_t unknown0;
    /* 0x3 */ uint8_t unknown1;
    /* 0x4 */ uint32_t offsetObject;
// }; // entry size = 0x8, if useBounds == 0
    
    // optional. Are they redundant even if used?
    /* 0x8 */ int16_t boundRight;
    /* 0xA */ int16_t boundBottom;
    /* 0xC */ int16_t boundLeft;
    /* 0xE */ int16_t boundTop;
}; // entry size = 0x10, if useBounds == 1

Field Name	Description	Data Type
numberObjects	Number of objects building this cell.	uint16_t
unknown0	What is this?	uint8_t
unknown1	What is this?	uint8_t
offsetObject	Offset within object attribute data.	uint32_t
boundRight	Right border of the cell.	int16_t
boundBottom	Bottom border of the cell.	int16_t
boundLeft	Left border of the cell.	int16_t
boundTop	Top border of the cell.	int16_t

Object Attributes

struct ObjectAttribute
{
    /* 0x0 */ uint16_t positionY : 8;          // 0b00000000'11111111
              uint16_t transformable : 1;      // 0b00000001'00000000
              uint16_t doubleSized : 1;        // 0b00000010'00000000
              uint16_t objectMode : 2;         // 0b00001100'00000000
              uint16_t mosaic : 1;             // 0b00010000'00000000
              uint16_t paletteMode : 1;        // 0b00100000'00000000
              uint16_t keyShape : 2;           // 0b11000000'00000000
    
    /* 0x2 */ uint16_t positionX : 9;          // 0b00000001'11111111
              uint16_t transformParameter : 3; // 0b00001110'00000000
              uint16_t horizontalFlip : 1;     // 0b00010000'00000000
              uint16_t verticalFlip : 1;       // 0b00100000'00000000
              uint16_t keySize : 2;            // 0b11000000'00000000
    
    /* 0x4 */ uint16_t tileIndex : 10;         // 0b00000011'11111111
              uint16_t priority : 2;           // 0b00001100'00000000
              uint16_t paletteIndex : 4;       // 0b11110000'00000000
}; // entry size = 0x6

Field Name	Description	Data Type
positionY	Y position, cast to a signed value.	uint16_t : 8
transformable	Enable flag for affine transformations.	uint16_t : 1
doubleSized	Double the size transformable. Not displayed if this flag is used without transformable.	uint16_t : 1
objectMode	`0` = normal, `1` = semi-transparent, `2` = OBJ window, `3` is not allowed.	uint16_t : 2
mosaic	Enable mosaic.	uint16_t : 1
paletteMode	Select type of the palette. `0`= 16 colors, `1` = 256 colors per palette.	uint16_t : 1
keyShape	Shape: `0` = square, `1` = horizontal, `2` = vertical, `3` is not allowed. See Dimension Keys.	uint16_t : 2
positionX	X position, cast to a signed value.	uint16_t : 9
transformParameter	(TODO) Currently not documented here. Read about it on GBATEK.	uint16_t : 3
horizontalFlip	Flip horizontally, if enabled.	uint16_t : 1
verticalFlip	Flip vertically, if enabled.	uint16_t : 1
keySize	Used to get the size of the OAM cell, see Dimension Keys.	uint16_t : 2
tileIndex	Index of the tile selecten from the character graphic.	uint16_t : 10
priority	Display priority if overlapping. Lower value = higher priority.	uint16_t : 2
paletteIndex	Index of the palette used for this OAM cell.	uint16_t : 4

Specification

Dimension Keys

The width and height of an object isn't defined directly. Instead it uses key values, which allow to reconstruct the size. For example if keyShape == 0, the cell will be a square which size depends on keySize. The dimenions can be converted using lookup tables.

Read dimensions

const uint16_t tableSizeInTiles[4][4] = // [keyShape][keySize]
{
    { 1, 2, 4, 8 },
    { 2, 4, 4, 8 },
    { 1, 1, 2, 4 },
    { 1, 2, 4, 8 } // copy of row 0 for reversed index (3 - shape)
};

uint16_t getWidthInTiles()
{
    return tableSizeInTiles[keyShape][keySize];
}

uint16_t getHeightInTiles()
{
    return tableSizeInTiles[3 - keyShape][keySize];
}

Write dimensions

const uint16_t tableShape[4][4] = // [width][height]
{   //h1 h2 h4 h8
    { 0, 2, 2, 0 },//w1
    { 1, 0, 2, 0 },//w2
    { 1, 1, 0, 2 },//w4
    { 0, 0, 1, 0 } //w8
};

const uint16_t tableSize[4][4] = // [width][height]
{   //h1 h2 h4 h8
    { 0, 0, 1, 0 },//w1
    { 0, 1, 2, 0 },//w2
    { 1, 2, 2, 3 },//w4
    { 0, 0, 3, 3 } //w8
};

void setSizeInTiles(uint16_t widthInTiles, uint16_t heightInTiles)
{
    const uint16_t width = (widthInTiles >= 8) ? 3 : (widthInTiles >> 1);
    const uint16_t height = (heightInTiles >= 8) ? 3 : (heightInTiles >> 1);
    
    keySize = tableSize[width][height];
    keyShape = tableShape[width][height];
}

Files

Nitro Cell Runtime

TODO

Document the transform parameters. transformParameter may also need to be fused with horizontalFlip and verticalFlip, from uint16_t : 3 to uint16_t : 5.
Research unknown0 and unknown1 in cell

Table of Contents​

Data Structure​

Section Container​

CEBK Container​

Cell​

Object Attributes​

Specification​

Dimension Keys​

Read dimensions​

Write dimensions​

Files​

TODO​

Table of Contents