== Introduction

=== What JoeyLib Is

JoeyLib is a single-codebase C game library for five 16-bit and 32-bit retro
machines. You write one program against one API, and the same source compiles
and runs on all of them:

[cols="2,2,2,4", options="header"]
|===
|Platform |CPU |RAM |Notes

|Apple IIgs
|65C816 at 2.8 MHz
|1 MB typical
|The reference platform. Accelerators run faster with no code changes.

|Commodore Amiga
|68000 (A500 class)
|512 KB chip, 512 KB fast recommended
|OCS chipset. Native planar bitplanes.

|Atari ST
|68000 (STF or STE)
|512 KB
|Word-interleaved planar. Shares 68000 assembly with the Amiga port.

|MS-DOS
|386 or later
|2 MB
|VGA required. DPMI supplied by an embedded CWSDPMI.

|Sharp X68000
|68000 at 10 MHz
|stock
|Draws into the text plane, 320x200 centred in a 512x512 screen.
|===

The Apple IIgs is deliberately the slowest target and the design reference. If
something performs acceptably there, it performs acceptably everywhere.

=== The Display Contract

Every JoeyLib program gets exactly the same screen on every platform:

* *320 x 200 pixels*, always. There is no other resolution.
* *16 colours on screen at once*, chosen per scanline from one of 16 palettes.
* *Colour 0 of every palette is black*, always, and is forced to black by the
  library even if you try to set it to something else. This is not negotiable:
  the Amiga and ST hardware border follows colour 0 of the active palette, and
  colour 0 is the transparent colour for sprite drawing. You have 15 usable
  colours per palette.
* Colours are *12-bit `$0RGB`*: bits 11..8 red, 7..4 green, 3..0 blue.
* Origin `(0, 0)` is *top-left*. X increases right, Y increases down.
  Coordinates are signed `int16_t`, so off-screen positions are representable.

Every drawing primitive clips to the surface rectangle. An out-of-bounds draw
is a silent no-op, never an error. There are no "fast unclipped" variants in
the public API, so you cannot corrupt memory by drawing off the edge.

=== What the Library Hides

The five machines store pixels in genuinely incompatible ways. JoeyLib keeps
that out of your program:

[cols="2,3", options="header"]
|===
|Platform |In-memory pixel storage

|Apple IIgs, MS-DOS
|Chunky 4bpp packed: two pixels per byte, high nibble is the left pixel.

|Commodore Amiga
|Native planar: four separate bitplanes.

|Atari ST
|Native planar, word-interleaved: four plane words per 16 pixels, per row.

|Sharp X68000
|Text-plane planes, four planes 128 KB apart.
|===

Every public entry point speaks in *colour indices, 0 to 15*. Your code never
sees the storage format. The one place the difference leaks through is
documented and flagged in this manual -- see <<_writing_portable_code>>.

=== What You Get

* Surfaces, palettes and per-scanline palette selection
* Drawing primitives: pixels, lines, rectangles, circles, flood fill
* 8x8 tiles, tile banks, tile maps and bitmap text
* Sprites with colour-0 transparency and *runtime-compiled blitters* -- the
  library emits native 65816, 68000 or x86 code for each sprite at run time
* Keyboard (both game-style predicates and a typed-character queue), mouse
  and joystick
* Four-channel Protracker `.MOD` music, a portable chip-tracker music format,
  digital one-shot and streaming sound effects, and a PSG-style tone and
  noise layer
* Read-only game data files and writable save files
* An optional RS-232 serial add-on
* A deterministic, seedable random generator that produces *bit-identical*
  output on every port for a given seed

=== How to Read This Manual

If you are new to JoeyLib, read <<_getting_started>>, then
<<_anatomy_of_a_joeylib_program>>, then <<_writing_portable_code>>. Those three
chapters are the whole programming model.

<<_creating_assets>> covers getting graphics, music and sound into a form the
library can load.

<<_adding_your_program_to_the_build>> explains how to get your own program
compiling for all five targets.

The API Reference documents every public function: its exact signature, each
parameter, what it returns, and any per-platform behaviour you need to know
about.