Data formats

These are the bytes that the tools write and the library reads. Numbers of more than one byte are little-endian, if a table does not tell otherwise.

Packed pixels and the SHR screen

A pixel is a 4-bit palette index. A byte holds two pixels. The left pixel is in bits 7-4. A row of w pixels uses (w + 1) / 2 bytes.

A palette word is 0x0RGB, with four bits each for red, green and blue. Thus 0x0F00 is red and 0x0FFF is white.

Palette JSON

["#000000", "#FFFFFF", "#FF0000", 255, 4095]

The list has a maximum of sixteen entries. Each entry is a 0RGB integer 0-4095 or a "#RRGGBB" string. A string keeps the high four bits of each channel. Missing entries are 0. assets.py image --palette-output writes the sixteen words as 32 bytes.

TI4 images

A surface view uses offset 8. The mask_offset of a ti_sprite is the offset of the mask.

Indexed image JSON

{"width": 4, "height": 2, "pixels": [0, 1, 1, 0, 1, 2, 2, 1], "masked": true}

TIF fonts

{"width": 3, "height": 3, "first": 48, "glyphs": [["###", "#.#", "###"]]}

TIM tile maps

{"rows": [[0, 1, 2], [3, 4, 5]], "tile_count": 6}

TPK1 resource packs

• Names are unique and in strictly increasing byte sequence. All padding bytes are zero.
• The data starts after the directory. The entries are in name sequence, and they do not overlap.
• All bytes are in the file. The file fits the 24-bit length of ProDOS.

ti_pack_load checks all of these conditions for each entry before it allocates memory. The pack manifest is {"entries": [{"name": "SHIP", "path": "ship.ti4"}]}. Each entry is 1 byte to 4 MiB.

Pattern songs

tools/music.py writes these bytes for a song document. ti_song_start reads them.

The row length, volume, decay and floor continue into the next pattern. Each pattern starts after the tables. It ends in the song with $FF, and it holds at least one note, rest or hold.

At each row, a track whose note has ended reads its next note, rest or hold. A note sets the tone and starts at the volume of the track. Every decay ticks, it decreases by one level, until it reaches the floor. A decay of 0 keeps the volume.

Decay runs before the row, so a note starts at full volume. After a late update, decay catches up a maximum of 16 ticks.

Song JSON

{"credit": "optional text for the header comment",
 "song": {"bpm": 152, "rows_per_beat": 8, "loop": 0,
   "tracks": [{"name": "lead", "volume": 12, "decay": 4, "floor": 8, "order": ["a", "a", "b"]}],
   "patterns": {"a": "D#5:2 F#5:2 -:4 G#5:8", "b": "v10 B5:12 ^:4"}}}

• bpm 20-400 and rows_per_beat 1-16 must give rows of 1-100 ticks.
• Tokens are NOTE:ROWS (rows 1-255), -:ROWS for a rest, ^:ROWS for a hold, and vN, dN, fN with N 0-15.
• A note is a name with an optional # or b and an octave. C4 is MIDI note 60. Each note must have a period of 1-2047.
• The default values of a track are volume 12, decay 0 and floor 0. All orders have the same number of positions, a maximum of 255. All tracks have the same number of rows.
• The compiler stores only the notes that the song uses, in pitch sequence. It stores only the patterns that an order uses. A note of more than 64 rows continues as holds.

Event score JSON

{"voices": 6, "events": [{"duration": 0, "period": 956, "voice": 0, "volume": 7},
                         {"duration": 25, "period": 1517, "voice": 1, "volume": 5}]}

voices is 6 or 12. There are 1-512 events. Each event has exactly four keys: duration 0-65,535 ticks, period 0-2047, voice less than voices, and volume 0-15.

At least one duration must not be zero. A maximum of 31 zero durations can follow each other. The header holds a ti_music_event array, with six bytes for each event.

Speech JSON and phoneme bytes

{"phrases": {"SAY_READY": "Ready.", "SAY_SCORE": "Score 100!"},
 "pronunciations": {"UP": ["UH", "P"], "CLEAR": "K L IY R"}}

• Phrase names are C identifiers in capitals: a capital or underscore, then capitals, digits or underscores.
• Text contains letters, digits, spaces and the characters . , ! ? ; : - '. The compiler ignores these characters.
• A sequence of digits, 0-9999, becomes number words.
• A pronunciation is a list, or a string of phoneme names with spaces between them. A PA pause separates the words.

Each generated byte holds an SSI-263 phoneme code in bits 0-5 and a duration value in bits 6-7. The duration value is 0 for vowels, 2 for stops and the pause, and 1 for all other sounds.