# Message System Architecture

**Status**: Draft
**Last Updated**: 2025-11-21
**Related Code**: `src/app/editor/message/`, `src/cli/handlers/game/message.cc`

This document outlines the architecture of the Message (Text) System in YAZE.

## Overview

The Message System manages the in-game dialogue and narration. ALttP uses a custom text engine with:
*   **Proportional Font**: Variable width characters.
*   **Dictionary Compression**: Common words/phrases are stored in a dictionary and referenced by single bytes to save space.
*   **Command Codes**: Byte sequences control window layout, scrolling, text speed, and player interaction.

## Data Structures

### 1. MessageData
Represents a single dialogue entry.
*   **ID**: Message index (0-396 in vanilla).
*   **Address**: ROM offset.
*   **RawString**: Human-readable text with dictionary tokens (e.g., `[D:01]`).
*   **ContentsParsed**: Fully expanded text (e.g., `Link`).
*   **Data**: Raw ROM bytes.

### 2. DictionaryEntry
A phrase used for compression.
*   **ID**: Index (0x00 - 0x60).
*   **Contents**: The text (e.g., " the ").
*   **Token**: Representation in `RawString` (e.g., `[D:00]`).

### 3. TextElement
Represents special control codes or characters.
*   **Commands**: `[W:02]` (Window Border), `[SPD:01]` (Scroll Speed).
*   **Special Chars**: `[UP]` (Arrow), `[A]` (Button), `...` (Ellipsis).

## ROM Layout (Vanilla)

*   **Bank 0E (0xE0000)**: Primary text data block (32KB).
*   **Bank 0E (0x75F40)**: Secondary text data block (5.3KB).
*   **Dictionary**: Pointers at `0x74703`.
*   **Font Graphics**: 2BPP tiles at `0x70000`.
*   **Character Widths**: Table at `0x74ADF`.

## Pipeline

### Loading
1.  **Read**: `ReadAllTextData` scans the ROM text blocks.
2.  **Parse**: Bytes are mapped to characters using `CharEncoder`.
3.  **Expand**: Dictionary references (`0x88`+) are looked up and replaced with `[D:XX]` tokens.
4.  **Preview**: `MessagePreview` renders the text to a bitmap using the font graphics and width table.

### Saving
1.  **Parse**: User text is converted to bytes.
2.  **Optimize**: `OptimizeMessageForDictionary` scans the text for dictionary phrases and replaces them with single-byte references.
3.  **Write**: Data is written sequentially to the ROM text blocks. If the first block overflows, it spills into the second block.

## Editor UI

*   **Message List**: Displays all messages with ID and preview.
*   **Editor**: Multiline text input. Buttons to insert commands/special chars.
*   **Preview**: Live rendering of the message box as it would appear in-game.
*   **Dictionary**: Read-only view of dictionary entries.

## Limitations

*   **Hardcoded Limits**: The text block sizes are fixed for vanilla.
*   **Translation**: No specific tooling for side-by-side translation.
*   **Export**: Limited to binary "Expanded Messages" format; no JSON/YAML support.