Jo Engine 2026.11.6
Jo Sega Saturn Engine
Loading...
Searching...
No Matches
level.h File Reference

Levels (.JOL files): the data of a level of a game (terrain, models, plants, decals...), see Documentation/level_format.md. The files are written by the Python tools of Compiler/COMMON/jo_level. More...

#include "level_format.h"

Go to the source code of this file.

Data Structures

struct  jo_level
 A loaded level. More...

Macros

#define JO_LEVEL_MAX_COPIES
 Maximum number of normalized copies of headers and records of a level (older files, see jo_level_get_records()).
#define JO_LEVEL_HEADER(LEVEL, ID, NAME)
 Read a header of a section (typed): jo_level_xxx_header *h = JO_LEVEL_HEADER(level, TERR, terr).
#define JO_LEVEL_RECORDS(LEVEL, ID, NAME, COUNT)
 Read the records of a section (typed): jo_level_xxx_record *r = JO_LEVEL_RECORDS(level, PLNT, plnt, &count).

Functions

jo_level * jo_level_load (const char *const filename)
 Load a level file (in the current directory of the CD, see jo_fs_cd()).
void jo_level_free (jo_level *const level)
 Free a level (the pointers given by the functions below are not valid any more).
const jo_level_directory_entry * jo_level_find_section (const jo_level *const level, const unsigned int id)
 Find a section (also a section of the game: identifier with a lowercase letter).
const void * jo_level_section_data (const jo_level *const level, const unsigned int id)
 Start of a section in the file.
const void * jo_level_get_header (jo_level *const level, const unsigned int id, const unsigned int size, const void *const defaults)
 Header of a section, with the fields of this engine.
const void * jo_level_get_records (jo_level *const level, const unsigned int id, const unsigned int size, const void *const defaults, unsigned int *const count)
 Records of a section, with the fields of this engine.
const void * jo_level_get_array (const jo_level *const level, const unsigned int id, const unsigned int offset)
 Array of a section (an offset field of its header).
const char * jo_level_string (const jo_level *const level, const unsigned int offset)
 A string of the level (field of type string).
bool jo_level_set_textures16_palette (jo_level *const level, const jo_palette *const palette)
 Copy the palette of the textures of 16 colors of a level in a palette.
bool jo_level_add_textures16 (jo_level *const level, const jo_palette *const palette, const int first, const int count, int *const sprite_ids)
 Make the sprites of textures of 16 colors of a level, each one with its color lookup table.
bool jo_level_set_textures8_palette (jo_level *const level, const jo_palette *const palette)
 Copy the palette of the textures of 256 colors of a level in a palette.
bool jo_level_add_textures8 (jo_level *const level, const int first, const int count, int *const sprite_ids)
 Make the sprites of textures of 256 colors of a level, and of their smaller copies (the sprites after each texture, given to jo_3d_set_texture_mipmap_copies() with the 3D support).

Detailed Description

Levels (.JOL files): the data of a level of a game (terrain, models, plants, decals...), see Documentation/level_format.md. The files are written by the Python tools of Compiler/COMMON/jo_level.

Author
Johannes Fetz
Remarks
With the file system module (JO_COMPILE_WITH_FS_MODULE, on by default: the levels are files)
The file is read once and used as it is (big endian, aligned): a section is a pointer in the file. A header or records of an older version (smaller) are copied with the default values of the missing fields (jo_level_get_header(), jo_level_get_records())

Data Structure Documentation

◆ jo_level

struct jo_level

A loaded level.

Data Fields
void * copies[(16)]
unsigned int copy_count
unsigned char * data
const jo_level_directory_entry * directory
unsigned int section_count
unsigned int size
const char * strings
unsigned int strings_size

Macro Definition Documentation

◆ JO_LEVEL_HEADER

#define JO_LEVEL_HEADER ( LEVEL,
ID,
NAME )

Read a header of a section (typed): jo_level_xxx_header *h = JO_LEVEL_HEADER(level, TERR, terr).

◆ JO_LEVEL_MAX_COPIES

#define JO_LEVEL_MAX_COPIES

Maximum number of normalized copies of headers and records of a level (older files, see jo_level_get_records()).

◆ JO_LEVEL_RECORDS

#define JO_LEVEL_RECORDS ( LEVEL,
ID,
NAME,
COUNT )

Read the records of a section (typed): jo_level_xxx_record *r = JO_LEVEL_RECORDS(level, PLNT, plnt, &count).

Function Documentation

◆ jo_level_add_textures16()

bool jo_level_add_textures16 ( jo_level *const level,
const jo_palette *const palette,
const int first,
const int count,
int *const sprite_ids )

Make the sprites of textures of 16 colors of a level, each one with its color lookup table.

Parameters
levelLevel
paletteJO_NULL: tables of RGB colors (the colors of the textures with their MSB set: drawn like RGB textures, gouraud shading, half transparency); a palette (see jo_level_set_textures16_palette()): tables of its color codes (the pixels have the colors of the color RAM: opaque over a see-through bottom where their MSB is cleared, see jo_vdp2_blend_rgb_sprites_only(); the blend ratio of each pixel value, see jo_vdp2_set_sprite_blend_ratios())
firstFirst texture (0: the first one of the level)
countNumber of textures
sprite_idsOutput: the sprite Id of each texture (count values)
Returns
false if the level has not these textures (or a texture is damaged: nothing made) or if the VDP1 memory is full (the sprites already made stay, see jo_sprite_free_from())
Remarks
A texture whose pixel value v is the color bank x 16 + v of the palette can also be drawn with its bank: jo_3d_set_mesh_polygon_texture_bank() (its table is not used)

◆ jo_level_add_textures8()

bool jo_level_add_textures8 ( jo_level *const level,
const int first,
const int count,
int *const sprite_ids )

Make the sprites of textures of 256 colors of a level, and of their smaller copies (the sprites after each texture, given to jo_3d_set_texture_mipmap_copies() with the 3D support).

Parameters
levelLevel
firstFirst texture (0: the first one of the level)
countNumber of textures
sprite_idsOutput: the sprite Id of each texture (count values)
Returns
false if the level has not these textures (or a texture is damaged: nothing made) or if the VDP1 memory is full (the sprites already made stay, see jo_sprite_free_from())
Remarks
Draw a polygon with one of them and its palette: jo_3d_set_mesh_polygon_texture_palette()

◆ jo_level_find_section()

const jo_level_directory_entry * jo_level_find_section ( const jo_level *const level,
const unsigned int id )

Find a section (also a section of the game: identifier with a lowercase letter).

Parameters
levelLevel
idIdentifier (JO_LEVEL_ID('T', 'E', 'R', 'R') or JO_LEVEL_SECTION_xxx)
Returns
The entry of the directory (version, sizes, number of records), JO_NULL if the level has no such section

◆ jo_level_free()

void jo_level_free ( jo_level *const level)

Free a level (the pointers given by the functions below are not valid any more).

Parameters
levelLevel

◆ jo_level_get_array()

const void * jo_level_get_array ( const jo_level *const level,
const unsigned int id,
const unsigned int offset )

Array of a section (an offset field of its header).

Parameters
levelLevel
idIdentifier
offsetOffset of the array from the start of the section (field of the header)
Returns
Pointer to the array, JO_NULL if the offset is 0

◆ jo_level_get_header()

const void * jo_level_get_header ( jo_level *const level,
const unsigned int id,
const unsigned int size,
const void *const defaults )

Header of a section, with the fields of this engine.

Parameters
levelLevel
idIdentifier
sizeSize of the header structure of the engine (sizeof(jo_level_xxx_header))
defaultsDefault values (JO_LEVEL_xxx_HEADER_DEFAULTS): the fields missing in an older file
Returns
The header (in the file when it has all the fields, else a copy), JO_NULL if there is no such section

◆ jo_level_get_records()

const void * jo_level_get_records ( jo_level *const level,
const unsigned int id,
const unsigned int size,
const void *const defaults,
unsigned int *const count )

Records of a section, with the fields of this engine.

Parameters
levelLevel
idIdentifier
sizeSize of the record structure of the engine (sizeof(jo_level_xxx_record))
defaultsDefault values (JO_LEVEL_xxx_RECORD_DEFAULTS): the fields missing in an older file
countNumber of records (output, 0 if there is no such section)
Returns
The records (in the file when they have all the fields, else a copy), JO_NULL if there are none

◆ jo_level_load()

jo_level * jo_level_load ( const char *const filename)

Load a level file (in the current directory of the CD, see jo_fs_cd()).

Parameters
filenameFile name (for instance "LEVEL.JOL")
Returns
The level, JO_NULL if the file is missing or invalid (the reason is printed with JO_DEBUG)
Remarks
A section unknown by the engine is ignored, unless it is required (the level is refused)

◆ jo_level_section_data()

const void * jo_level_section_data ( const jo_level *const level,
const unsigned int id )

Start of a section in the file.

Parameters
levelLevel
idIdentifier
Returns
Pointer to the section (its header, then its records, then its arrays), JO_NULL if there is no such section

◆ jo_level_set_textures16_palette()

bool jo_level_set_textures16_palette ( jo_level *const level,
const jo_palette *const palette )

Copy the palette of the textures of 16 colors of a level in a palette.

Parameters
levelLevel
palettePalette (jo_create_palette()): its color n is the color n of the textures (palette->data[n - 1])
Returns
false if the level has no textures of 16 colors, or no colors, or more than JO_PALETTE_MAX_COLORS

◆ jo_level_set_textures8_palette()

bool jo_level_set_textures8_palette ( jo_level *const level,
const jo_palette *const palette )

Copy the palette of the textures of 256 colors of a level in a palette.

Parameters
levelLevel
palettePalette (jo_create_palette()): the pixel value n of the textures is its color n (palette->data[n - 1])
Returns
false if the level has no textures of 256 colors, or no colors, or more than JO_PALETTE_MAX_COLORS

◆ jo_level_string()

const char * jo_level_string ( const jo_level *const level,
const unsigned int offset )

A string of the level (field of type string).

Parameters
levelLevel
offsetOffset in the STRS section
Returns
The string, "" if there is no string