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

129 lines
4.1 KiB
Markdown

# 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.