libtiniappletini.org

libtini

libtini is a C game SDK for an enhanced Apple //e with an Appletini. You write the game loop in C with cc65. libtini draws Super Hi-Res screens, keeps large data in RamWorks banks and plays Mockingboard or Phasor music. It also speaks through the SSI-263, reads the keyboard and joystick, and loads and saves ProDOS files.

The palette of the starter game. ti_gfx_begin writes these sixteen 0RGB words to the SHR palette at AUX $9E00. Each pixel on a libtini screen is one of these sixteen entries. One byte holds two pixels.

libtini runs on Appletini hardware with firmware F1.3.2. It uses only interfaces that this firmware has:

libtini needs no firmware change, no FPGA change and no slot change. An optional build adds the Appletini AMEM memory service for large banked copies. The default build does not include it.

libtini has the MIT License. A game that uses libtini can have any license. libtini is in the libtini/ folder of the appletini-software repository. This folder also has an example game, STARFALL, and a starter game that you can copy.

Play STARFALL in your browser. The browser player runs the STARFALL disk on the development emulator, with sound and speech.

A first program

This program clears the screen, writes a line of text and waits for a key. When main returns, libtini restores the text screen and quits to ProDOS.

#include "libtini.h"

static ti_surface screen;          /* create needs a structure of zeros */
static const uint16_t palette[16] = {
    0x000, 0xFFF, 0xF00, 0x0F0, 0x00F, 0xFF0, 0x0FF, 0xF0F,
    0x888, 0x444, 0xF80, 0x08F, 0x8F0, 0xF08, 0x0F8, 0xCCC
};

int main(void)
{
    uint8_t key;
    if (ti_init(1, 2) != TI_OK) return 1;        /* RamWorks selectors 1 and 2 */
    if (ti_gfx_surface_create(&screen, 320, 200) != TI_OK) return 1;
    if (ti_gfx_begin(palette) != TI_OK) return 1; /* the screen shows SHR */
    ti_gfx_clear(&screen, 0);
    ti_gfx_text(&screen, 8, 8, "HELLO FROM LIBTINI", 1);
    ti_gfx_present(&screen, 0, 0);                /* publish the whole surface */
    do ti_input_poll(); while (ti_input_key(&key) != TI_OK);
    return 0;                                     /* libtini cleans up on return */
}

The surface is in banked memory, not in C memory. It is a handle and an offset into the RamWorks banks that ti_init grants. The draw functions change only the surface. ti_gfx_present copies the surface to the screen with usual CPU writes. First steps shows how to make a bootable disk from this program.

The parts of libtini

MemoryNear buffers and banked resources: read, write, fill and copy. TimingFixed-rate updates from the audio device clock, at all CPU speeds. Graphics320x200 SHR: surfaces, rectangles, lines, text, sprites, tile maps and palettes. Sprite scenesA band renderer that draws only the blocks that change. AudioSix or twelve AY voices: event scores, pattern songs, effects and envelopes. SpeechSSI-263 phrases from text, spoken numbers and a priority queue. InputKey events, the held key, buttons, paddles and calibrated stick directions. StorageProDOS file reads and writes, and resource packs in banked memory. Optional AMEMOptional private acceleration for large banked transfers.

Host tools change art, fonts, tile maps, speech text, music and MIDI files into data for libtini. They also make bootable ProDOS disks, measure functions on an emulator and make a browser version of a game.

Contents

StartFirst steps, How libtini works, Examples
GuidesGame loop and timing, Draw and publish, Music, effects and speech, Keyboard and joystick, Art, fonts, maps and packs, Saved games, Memory and layouts
APIAll functions, Types and errors, Memory, Timing, Graphics, Sprite scenes, Audio, Speech, Input, Storage, Optional AMEM
ReferenceBuilds and game manifests, Tools, Data formats, Machine contract, Browser player, Checks

The design notes, the development plan and the measurements are Markdown files in libtini/design.