Jo Engine 2026.11.1
Jo Sega Saturn Engine
Loading...
Searching...
No Matches
Jo Engine documentation

Jo Engine is an open source 2D and 3D game engine for the Sega Saturn, written in C under the MIT license. It lets you develop games without extensive knowledge of embedded development, and the games run on emulators as well as on the original console.

The engine talks directly to the hardware (VDP1, VDP2, SCSP, SMPC, CD block): it doesn't need any Sega library.

Getting started

Development works on Windows, Linux and macOS. The fastest way to start is to copy a folder from Samples (for instance Samples/demo1) and to modify it:

  1. Write your game in main.c (and add your other source files to SRCS in the makefile).
  2. Put your assets (images, sounds, maps, etc) in the cd folder: it becomes the file system of the CD.
  3. Run compile.bat (Windows) or compile.sh (Linux and macOS): it builds game.iso and game.cue.
  4. Run the game with one of the run_with_* scripts (Yabause, Mednafen, Kronos, SSF, etc) or burn it.

A minimal game, which displays a sprite loaded from the CD:

#include <jo/jo.h>
void my_draw(void)
{
jo_sprite_draw3D(0, 0, 0, 500);
}
void jo_main(void)
{
jo_core_init(JO_COLOR_Black);
jo_sprite_add_tga("TEX", "SONIC.TGA", JO_COLOR_Transparent);
jo_core_add_callback(my_draw);
jo_core_run();
}
JO_COLOR_Black
#define JO_COLOR_Black
Definition colors.h:57
JO_COLOR_Transparent
#define JO_COLOR_Transparent
Transparent color.
Definition colors.h:87
jo_core_init
void jo_core_init(const jo_color back_color)
Init the engine.
jo_core_run
void jo_core_run(void)
Run the game.
jo_core_add_callback
int jo_core_add_callback(const jo_event_callback callback)
Add a callback in the game loop on main CPU.
jo.h
Jo Engine Main Header.
jo_sprite_add_tga
int jo_sprite_add_tga(const char *const sub_dir, const char *const filename, const jo_color transparent_color)
Add a sprite from a TGA file.

jo_main() is the entry point. jo_core_init() initializes the hardware, jo_core_add_callback() registers a function called every frame and jo_core_run() starts the main loop (it never returns).

The project makefile

Every module can be enabled or disabled in the makefile of your project to save memory:

Option Description
JO_COMPILE_WITH_3D_MODULE 3D meshes, matrices, camera, models, lights and glows (3d.h, model.h, light.h, glow.h)
JO_COMPILE_WITH_LEVEL_MODULE Levels (.JOL files): cells and portals, entities, weapons, vehicles (level.h)
JO_COMPILE_WITH_AUDIO_MODULE PCM sounds and CD audio tracks (audio.h)
JO_COMPILE_WITH_AUDIO_DRIVER_MODULE The 68000 runs a sound driver: glides, tones (needs the audio module)
JO_COMPILE_WITH_AUDIO_DSP_MODULE The DSP of the SCSP adds a reverberation (needs the audio module)
JO_COMPILE_WITH_BACKUP_MODULE Save data in the internal memory, on a cartridge or an external device (backup.h)
JO_COMPILE_WITH_TGA_MODULE TGA image loader (tga.h)
JO_COMPILE_WITH_VIDEO_MODULE Sega FILM (CPK) video player (video.h)
JO_COMPILE_WITH_PSEUDO_MODE7_MODULE Mode 7 floor (mode7.h)
JO_COMPILE_WITH_EFFECTS_MODULE Special effects: particles, flash, fade, shake (effects.h)
JO_COMPILE_WITH_PROFILER_MODULE Time spent by the CPUs and the VDP1 in each frame (profile.h)
JO_COMPILE_WITH_DUAL_CPU_MODULE Run code on the slave SH-2
JO_DEBUG Debug mode: error checks, error screen (press START to continue) and memory usage tools
JO_NTSC 1: NTSC (60 Hz), 0: PAL (50 Hz)
JO_480i 480 lines interlaced high resolution
JO_FRAMERATE The game runs every n VBLANK (1: 60 FPS, 2: 30 FPS). JO_FRAMERATE_DYNAMIC = 1: as soon as a frame is done
JO_GAME_TITLE, JO_GAME_VERSION, JO_GAME_RELEASE_DATE, JO_GAME_MAKER_ID, JO_GAME_PRODUCT_NUMBER, JO_GAME_PERIPHERALS Game information written in the IP.BIN (the boot header of the CD)
JO_GLOBAL_MEMORY_SIZE_FOR_MALLOC Memory size used by jo_malloc() in the high work RAM
JO_MAX_SPRITE, JO_VDP1_MAX_COMMANDS Maximum sprites (textures) and VDP1 commands per frame: smaller to save RAM

JO_DEBUG should be disabled in the final version of your game: the checks are removed and the game is faster.

Modules

Core

Header Content
jo.h Main header: the only one to include
core.h Initialization, main loop, callbacks, error handler
conf.h Engine configuration (limits, sizes)
types.h Common types (positions, sizes, images, etc)
malloc.h Dynamic memory allocation (jo_malloc(), jo_free())
list.h Linked list
time.h Ticks, elapsed time and delta time
tools.h Utilities (printf, strings, endianness, etc)
math.h Fixed point numbers, trigonometry, random numbers, vectors and matrices
sega_saturn.h Sega Saturn hardware: registers, addresses, memory map
dsp.h SCU DSP programs (the third processor)

Graphics

Header Content
sprites.h Sprites (VDP1): loading, drawing, scaling, rotation
sprite_animator.h Sprite animations
image.h Image definition and conversion tools
tga.h Truevision Targa (TGA) loader
palette.h 8 bits palettes
colors.h Standard colors
vdp2.h Backgrounds (VDP2): NBG0 to NBG3, RBG0 rotation, line scroll, mosaic, etc
background.h Background helpers
vdp2_malloc.h VDP2 memory allocation
vdp1_command_pipeline.h VDP1 command table, windows, wireframe
map.h Tile maps
mode7.h Mode 7 floor
3d.h 3D meshes, camera, matrices, texture subdivision, slave CPU rendering
model.h 3D models (.JOM files, see Jo Engine 3D model file (JOM)) made by Compiler/COMMON/jo_model.py, skeletons and poses
light.h Point lights baked in the gouraud tables of the meshes
glow.h Glows: the halo of light around a lamp (VDP2 layers)
software_renderer.h Triangle based software renderer
voxel.h Voxel landscape renderer
effects.h Special effects: particles, flash, fade, shake
storyboard.h Storyboard animations (movements, rotations)
font.h Bitmap fonts
video.h Video player (Sega FILM/CPK)

Input, sound and storage

Header Content
input.h Gamepads, analog pads, mouse, multitap
keyboard.h Keyboard
smpc.h System Management & Peripheral Control
audio.h PCM sounds and CD audio tracks
fs.h CD file system
backup.h Saves (internal memory, cartridge or external device)
serial.h Serial link (Taisen cable)
vcd_card.h VCD card (work in progress)

Levels (JO_COMPILE_WITH_LEVEL_MODULE)

Header Content
level.h Levels (.JOL files, see Jo Engine level file (JOL)), written by Compiler/COMMON/jo_level
level_format.h The sections of a level file
cell.h Cells and portals: the rooms of an inside level, the visibility
entity.h Entities: doors, explosives, triggers, actors (animated models), enemies
weapon.h Weapons of the player
vehicle.h Vehicles driven by the player

Tools

Header Content
console.h Debug console
hitbox.h Hitboxes and collisions
physics.h Basic physics
profile.h Profiler: the time of the CPUs and of the VDP1 in each frame

File formats

Page Content
Jo Engine 3D model file (JOM) 3D models (.JOM): points, polygons, materials, textures, vertex colors, groups, skeletons and animations
Jo Engine level file (JOL) Levels (.JOL): the sections of a level file (terrain, cells and portals, entities, weapons, vehicles, etc)

The sources of these pages are in the Documentation folder (level_format.md is generated from the schema of Compiler/COMMON/jo_level).

Samples

The Samples folder contains about 50 demos (sprites, 3D, 3D models, environment mapping, VDP2 planes, mode 7, audio, video, backup, gamepads, mouse, keyboard, a first person shooter, etc). They are the best way to learn how to use each module.

Tools

The Python scripts of Compiler/COMMON prepare the assets of a game:

Generated by doxygen 1.18.0