Files
CoCoLetters/HACKING.md
T
Brian Holman 4cedb2d94a Import coco-letters 0.1.0 upstream source snapshot
Original author: Pierre Sarrazin. Preserve upstream GPLv3-or-later and file-specific notices.
Source: http://sarrazip.com/dev/coco-letters-0.1.0.tar.gz
Archive SHA-256: ad7c7771845e1a35014644fb562634a558abee632e1d7738683db6e9e9e46b94
2026-11-09 23:39:21 -07:00

4.1 KiB

Memory map after initialization

Banks    Address      Size    Description

0        0000          8 k    Dictionary access bank.
1..3     2000         24 k    Code and global variables.
4..6     8000         24 k    Graphics screen (256x192x16).
7        E000        960 B    32x16 and 40x24 (no attributes) text screens.
7        E3C0        768 B    4x7 font (right side text).
7        E6C0        256 B    5x8 font (used on board).
7        E7C0       5696 B    Stack space.
7        FE00        238 B    Not used.
-        FEEE         18 B    CoCo 3 Interrupt vectors.
-        FF00        256 B    I/O addresses.

MMU blocks

48..50   Word dictionary.
51..53   Graphics screen.
54..56   Word dictionary.
57..59   Code and global variables.
60..62   Word dictionary.
63       Text screen, fonts, stack space.

Automating the keyboard

To automate keystrokes, edit the scriptedKeys[] array in main.c. Use \r to represent the Enter key. The pollKeyboard() function will return each of the characters in that array before calling Keyboard_poll().

Word list

The word-list.txt word list is based on enable.txt from figshare.com, with a few edits, and is in the public domain.

See https://figshare.com/articles/dataset/Enable_Scrabble_Dictionary/7492499.

Variables MIN_WORD_LEN and MAX_WORD_LEN in the Makefile determine which words get selected from that word list.

Variable MAX_NUM_DICT_BLOCKS in the Makefile limits the number of 8k blocks that can be used to contain the selected words. The dictMMUBlockIndexes[] array in dict.c must contain that number of MMU block indexes.

Data file format

The data file is named by variable DATA_FILENAME in the Makefile and is generated by build-data.pl and read by loadDataFile() in dict.c.

The format:

  • Sectors that contain the 4x8 font used in the right side of the game screen. (See FONT_4x8_BUFFER, FONT_4x8_SECTORS.)

  • Sectors that contain the 5x8 font used on the board. (See FONT_5x8_BUFFER, FONT_5x8_SECTORS.)

  • Sequence of 8k blocks:

    • 16-bit big endian unsigned word: Number of words in the 8k block.
    • List of words:
      • One byte per character of the word.
      • Bit 7 of the last byte of the word is 1. (This prevents support for Latin-1 characters.)

Putting the font data in the data file instead of the executable allowed shrinking the size of the latter. This was useful to avoid reaching the limit at $7F80, which is necessary for the LOADM command to be able to load the entire file.

The fonts are defined by C files because those files define byte arrays that used to be included in the compilation.

Text window at the right of the board

At the right of the board is a text window of 14 columns by 24 rows.

writeStringAt() is the main function to use to write text.

Calls to printf(), putchar(), etc. print to a subwindow of 14 columns by 8 rows at the bottom. This subwindow can be used to print debugging information.

See TEXT_WIN_LEFT, TEXT_WIN_TOP, TEXT_WIN_WIDTH, TEXT_WIN_HEIGHT, etc., in defs.h.

Tile types

TILE_TYPE_NONE represents the absence of any tile on a board square.

TILE_TYPE_BLANK represents an unmarked wildcard that can represent any letter.

Values 1 to 26 represent letters A to Z.

Tile values in points

These are defined in the letterSpecs[] array in GameState.c.

Debugging with traces in the Becker port

During the game, printf() et al. print to a small text window at the buttom right corner of the game screen.

This can be used for debugging, as long as the quantity of traces is small.

For larger traces, sending the output to a CoCo emulator's Becker port is more viable.

To do this, edit graphics.c and uncomment this line:

//#define TRACES_TO_BECKER_PORT

Then build. Before launching the emulator, a server on the same machine must be listening to TCP port 65504. This server should then copy all the traces it receives to standard output or to a file.

This only applies to the graphical screen, not to the help screen.