First steps

Install the compiler and the ProDOS input. Build the library and its examples, boot a disk, and then start a game of your own.

Equipment

On the Apple

• An enhanced Apple //e (65C02) with an Appletini that has firmware F1.3.2. You do not change the firmware or the slots.
• RamWorks enabled. A game grants a set of expansion banks (selectors) to libtini with ti_init. No RAM disk or other driver can use these banks. The diagnostic uses selectors 1-2. The starter and STARFALL use selectors 1-3.
• SmartPort in slot 7. It holds the boot disk.
• A Mockingboard or Phasor personality in slot 4. It gives sound, speech, the game clock and the joystick timer.

On the development computer

Download cc65 2.19 from its release page. The build makes sure that all four cc65 programs report V2.19. To find the SDK, the build uses one of these:

• The --cc65-home option.
• The CC65_HOME environment variable.
• The SDK bin/ folder on PATH.

The examples on this page use D:/Repos/cc65.

Build the library and the examples

Run all commands from the libtini/ folder of the repository.

python tools/setup_inputs.py
python tools/build.py --cc65-home D:/Repos/cc65

The first command downloads the official ProDOS 8 2.4.3 disk image one time. It makes sure that the SHA-256 is correct and keeps the image in build-inputs/prodos/, which git ignores. All subsequent builds work offline. The repository does not distribute ProDOS. Read the ProDOS terms before you share a disk that contains it. The --no-disk option builds the programs and the library without ProDOS.

A build compiles the library, links all programs and games, checks each linked layout and writes bootable disks:

At the end, the build shows one memory line for each game. For example:

starfall memory: LOW $0800-$1FFF 88 free; IMAGE $2000-$BEFF 1032 free; WORK $A26C-$B3FF 1110 free; NEAR $B480-$B6FF 1 free
starter memory: MAIN $2000-$9FFF 12321 free; NEAR $A900-$AEFF 1532 free

Run a disk

Boot build/starter.po from slot 7. To move the square, hold WASD or the arrow keys, or move a joystick. A joystick button plays a tone. Q returns to ProDOS. The starter needs the slot-4 card. Without the card, the screen shows that a slot 4 audio card is necessary.

build/starfall.po starts STARFALL. Return or a joystick button starts the game with the Mockingboard. P starts it with the Phasor.

build/libtini.po runs five memory tests and shows PASS or FAIL for each test. If a granted bank is missing or aliased, the diagnostic shows this in text and then exits normally.

Start your own game

In this repository

A game is a folder in games/ or examples/ with a game.json manifest. The build finds all manifests automatically. Do these steps:

1. Make a folder, for example games/mygame/.
2. Copy examples/starter/main.c into the folder.
3. Add a manifest:

{
  "name": "mygame",
  "title": "MY GAME",
  "sources": ["main.c"],
  "disk": {"volume": "MYGAME", "system": "MYGAME.SYSTEM", "blocks": 280}
}

4. Build the game:

python tools/build.py --cc65-home D:/Repos/cc65 --game mygame

The --game option builds the library, the diagnostic and this one game. The outputs are build/mygame.system and build/mygame.po. Builds and game manifests gives all manifest keys, generated assets and extra disk files.

As a separate project

python examples/starter/create.py C:/Projects/MyGame

This command copies the runtime sources, the public headers, the cfg/libtini.cfg layout and the disk tools into C:/Projects/MyGame/runtime/. It also adds the starter main.c and a small build.py. The destination folder must not exist. SDK_INPUTS.json keeps the hash of each copied file. The project does not need this repository:

cd C:/Projects/MyGame
python runtime/tools/setup_inputs.py
python build.py --cc65-home D:/Repos/cc65

The project builds build/APP.SYSTEM and build/APP.po. The copied runtime does not change when the SDK changes. To get a new SDK version, make a new project or copy the new sources. Do not change the copies as a replacement for a change to the SDK source.

Read the starter

The starter has approximately one hundred lines. It uses the functions that most games need first:

• ti_init and a 320x200 surface.
• ti_gfx_begin for the screen.
• ti_audio_init for the clock.
• ti_steps_due for thirty updates each second.
• ti_input_held and ti_stick_read for movement.
• ti_gfx_present for the changed rectangle.

Examples explains the starter.

Run on the development emulator

The development emulator of the repository runs the same disks. It needs GCC. A ProDOS boot also needs the enhanced //e ROM and the SmartPort ROMs. The repository does not distribute these ROMs. Install them in build-inputs/native-roms/, as tools/DEPENDENCIES.md tells.

python tools/native_emulator.py --cc C:/msys64/ucrt64/bin/gcc.exe play --disk build/starfall.po --boot `
    --rom build-inputs/native-roms/Apple2e_Enhanced.rom `
    --slot7-rom build-inputs/native-roms/smartport_a2retronet_style_c700.mem `
    --slot7-c8-rom build-inputs/native-roms/smartport_a2retronet_style_c800.mem `
    --video-rom build-inputs/native-roms/apple2e-video.bin --profile vtw33

This command runs without sound. The browser player plays a game with sound and speech in a web page. The vtw33 profile runs at a nominal 33.33 MHz. The turbo-f122 profile uses the TURBO cost model.

With --disk and --system instead of --boot, the emulator uses a ProDOS MLI stand-in. This stand-in does not have ALLOC_INTERRUPT. Thus ti_audio_init fails, and a game that needs the audio clock reports that the slot-4 card is missing.