MSX2 BASIC Knowledge Base
A source-grounded knowledge base for a future model that reads and generates MSX2 BASIC programs, supported by language documentation, authentic program listings, and validation tools.

GIT

Create a structure for storing the MSX2 Basic language model:
language-knowledge/
├── README.md
├── specification/
│   ├── overview.md
│   ├── lexical-rules.md
│   ├── types.md
│   ├── variables.md
│   ├── expressions.md
│   ├── control-flow.md
│   └── runtime.md
│
├── commands/
│   ├── move.md
│   ├── create.md
│   ├── print.md
│   └── wait.md
│
├── grammar/
│   ├── language.ebnf
│   └── tokens.md
│
├── registry/
│   ├── commands.yaml
│   ├── types.yaml
│   └── diagnostics.yaml
│
├── examples/
│   ├── basic/
│   │   ├── hello.xyz
│   │   └── variables.xyz
│   ├── intermediate/
│   └── advanced/
│
├── tests/
│   ├── valid/
│   ├── invalid/
│   └── runtime/
│
└── prompts/
    └── generation-rules.md

We are going to build language-knowledge base for the future MSX2 Basic Model.
Read the book in the folder @"C:WorkspaceMSX2_LLMMSX2 docs"
Go other language-knowledge and fill in relevant data. 
Remove irrelevant stub files.
File extension for basic files is .bas

Recursively read this path: C:WorkspaceMSX2_LLMMSX2 docsBAS Examples
These are real, correct programs written in MSX2 Basic.
Improve language-knowledge

You had used a two pass detokenizer. Create a powershell script with the detokinizer in tools/detokinizer

### Build a syntax checker

Having a checker will greatly improve the result, but it does not have to be ready before the first prototype.

It is better to divide validation into three levels.

#### Level 1 — a simple validator

Implement:

- maximum line length checks;
- string literal validity checks;
- balanced parentheses checks;
- known command checks;
- command parameter checks;
- reference checks for `GOTO`, `GOSUB`, `THEN`, `RESTORE`;
- `FOR`/`NEXT` matching;
- `IF` compliance with MSX BASIC syntax;
- checks that called subroutines exist;

Place the checker script in tools/syntaxChecker

Add to AGENTS:

# MSX2 BASIC generation rules

1. Generate code only for MSX2 BASIC.
2. Do not use GW-BASIC, QuickBASIC, or Visual Basic syntax.
3. Before generation, find the following in language-knowledge:
   - a description of every command used;
   - at least one similar example program.
4. Do not invent commands, functions, or parameters.
5. All GOTO, GOSUB, THEN, and RESTORE jumps must lead
   to existing lines.
6. Check FOR/NEXT and GOSUB/RETURN matching.
7. Take the selected SCREEN mode into account.
8. Return the complete program listing by default.
9. If a required capability is not described in the knowledge base,
   report this instead of inventing syntax.

Add a root index, for example:

language-knowledge/
├── INDEX.md
├── registry/
│   └── commands.yaml
├── commands/
├── specification/
├── examples/
└── grammar/

Describe routing in INDEX.md, for example:

# Knowledge index

## Graphics

- commands/screen.md
- commands/line.md
- commands/circle.md
- examples/graphics/

## Sprites

- commands/sprite.md
- commands/put-sprite.md
- examples/sprites/

## Sound

- commands/sound.md
- commands/play.md
- examples/sound/

## Files

- commands/open.md
- commands/close.md
- commands/input.md
- examples/files/

So that the agent reads INDEX.md first instead of scanning all of language-knowledge.

# MSX-2 SCREEN Concept
The **MSX-2 SCREEN concept** revolves around *multiple screen modes*, each tailored for different use cases like text, tile-based graphics, bitmapped images, and sprites. MSX-2 greatly expanded upon the original MSX video capabilities by leveraging the **Yamaha V9938** video display processor (VDP), allowing for higher resolution, more colors, and multiple VRAM pages.
—
## 🎨 Overview of SCREEN Modes in MSX-2
| Mode       | Type     | Resolution     | Colors           | Description                                  |
|————|———-|—————-|——————|———————————————-|
| SCREEN 0   | Text     | 40×24 (text)    | 2 colors         | Default text screen (40 columns)             |
| SCREEN 1   | Text     | 32×24 (text)    | 15 colors (limited) | Colorful, 32-column text mode             |
| SCREEN 2   | Tile     | 256×192         | 16 (per 8×1 area) | Tile-based mode for games                    |
| SCREEN 4   | Tile     | 256×212         | 16 (fixed palette) | MSX2 version of SCREEN 2                     |
| SCREEN 5   | Bitmap   | 256×212         | 16 (from 512)     | Direct pixel graphics                         |
| SCREEN 6   | Bitmap   | 512×212         | 4 (from 512)      | High-res graphics mode                        |
| SCREEN 7   | Bitmap   | 512×212         | 16 (from 512)     | High-res, 16-color mode                       |
| SCREEN 8   | Bitmap   | 256×212         | 256 (fixed)       | 8-bit color mode (no sprite support)         |
| SCREEN 10  | YJK      | 256×212         | ~12,000 (YJK)     | Photo-realistic color encoding               |
| SCREEN 11  | YJK+PAL  | 256×212         | ~12,000 + 16      | YJK with palette override                    |
| SCREEN 12  | YJK      | 512×212         | ~12,000           | Hi-res YJK mode (MSX2+)                      |
—
## 📦 Concepts Behind the SCREEN System
### 1. Tile Modes vs Bitmap Modes
- **Tile-based (SCREEN 1–4):**
  - Use **character patterns** and **name tables**.
  - Efficient and fast—perfect for retro-style games.
- **Bitmap modes (SCREEN 5–8, 10–12):**
  - Allow **per-pixel** control.
  - Best for drawing, images, or artistic apps.
—
### 2. Color System
- MSX-1: fixed 16-color palette.
- MSX-2:
  - **512-color palette**
  - Custom palette via `COLOR=` or `VDP` register.
  - Bitmap screens can use these with up to 16 or 256 colors.
  - YJK modes allow 12,000+ virtual colors.
—
### 3. Pages
- Most modes support **multiple VRAM pages**.
- You can:
  - Draw on one page.
  - Show another page.
  - Swap for **smooth animation** (double-buffering).
—
### 4. Sprites
- Used in SCREEN 1–7.
- **32 hardware sprites**, up to 16 colors.
- Limit: **4 sprites per scanline**.
—
### 5. VRAM Layout
- Use `VPOKE`, `VPEEK`, and `COPY` to directly manage VRAM:
  - Tiles, bitmaps, sprite patterns, palettes, etc.
—
## 🧪 Example: Draw a Pixel in SCREEN 5
“`basic
SCREEN 5
PSET (100, 100), 15  ’ White pixel

<#
.SYNOPSIS
    Processes a text file by adding line numbers and replacing label-based GOTO/GOSUB commands.
.DESCRIPTION
    - Each line is numbered sequentially starting from a given Start, with an increment of Step.
    - Labels (lines starting with ’:') are replaced with a numbered line containing ”REM :label”.
    - GOSUB and GOTO commands referencing a label (e.g., ”gosub myLabel”) are replaced with the numeric line.
    - Case-insensitive matching for labels and commands.
.PARAMETER FilePath
    Path to the file to process.
.PARAMETER Start
    Starting number for line numbering (default: 10).
.PARAMETER Step
    Increment step for line numbering (default: 10).
.EXAMPLE
    .RenumberWithLabels.ps1 -FilePath ”C:codescript.bas” -Start 10 -Step 10
#>
param(
    [string]$FilePath,
    [int]$Start = 10,
    [int]$Step = 10
)
if (-not (Test-Path $FilePath)) {
    Write-Error ”File not found: $FilePath”
    exit 1
}
$lines = Get-Content $FilePath
$output = @()
$labelMap = @{}
$lineNumber = $Start
# First pass: assign line numbers and store label mappings
foreach ($line in $lines) {
    $trimmed = $line.Trim()
    if ($trimmed -match ’^:([a-zA-Z_][w]*)$’) {
        $label = $matches[1]
        $labelMap[$label.ToLower()] = $lineNumber
        $output += ”$lineNumber REM :$label”
    }
    else {
        $output += ”$lineNumber $line”
    }
    $lineNumber += $Step
}
# Second pass: replace GOSUB/GOTO label references
for ($i = 0; $i -lt $output.Count; $i++) {
    $line = $output[$i]
    foreach ($label in $labelMap.Keys) {
        $line = $line -replace ”(?i)bgosubs+:?$labelb”, ”gosub $($labelMap[$label])”
        $line = $line -replace ”(?i)bgotos+:?$labelb”, ”GOTO $($labelMap[$label])”
    }
    $output[$i] = $line
}
# Save to file or print
$output | Set-Content ”$FilePath.processed”
Write-Host ”Processed file saved as: $FilePath.processed”

MSX-2 Disk Deployment Script Requirements

This document outlines the complete functionality for a PowerShell script that builds a bootable MSX-2 .dsk image from a BASIC project.

Input Parameters

• MainBasPath (Required, String): Full path to the main .BAS file.
• ProjectName (Optional, String): Optional project name. Defaults to the base name of the .BAS file.

Folder and File Structure

Work Folder

• Location: Sibling to the folder containing MainBasPath.
• Name Format: ProjectName_Hash (the hash is 6 characters from a GUID).
• Contents: Renumbered .BAS files and AUTOEXEC.BAS.

Disk Image

• Name: ProjectName.dsk.
• Location: Same parent folder as the folder containing MainBasPath.
• Base: Created by copying the "New 720KB Boot Disk.dsk" template.
• Overwrite: If the file already exists, it is overwritten.

Steps

1. Resolve and Print All Paths
   • Compute all paths (folders, tools, and output) at the top of the script and print them.
2. Create Work Folder
   • Create a work folder as a sibling to the project folder using the format: ProjectName_Hash.
3. Create AUTOEXEC.BAS
   • Create AUTOEXEC.BAS in the work folder.
   • The file content should be: RUN "MainFile.BAS" (using the actual main file name), written in ASCII.
4. Copy and Renumber .BAS Files
   1. Copy all .BAS files from the folder containing MainBasPath to the work folder.
   2. Renumber each .BAS file by calling the external renumbering script:
      D:WorkspaceMSXtoolsrenumber.ps1 -FilePath -Step 10 -Start 10
5. Create and Populate Disk Image
   1. Copy the template image "New 720KB Boot Disk.dsk" to the destination DiskImage path, overwriting any existing file.
   2. Add each file from the work folder to the disk image using the command:
      dsktool.exe A "C:pathtoimage.dsk" "C:pathtofile.ext"
   3. If adding a file fails, print the exact command used for troubleshooting.
6. Cleanup or Error Handling
   1. If all files are added successfully, delete the work folder and print "Deployment Complete".
   2. If any file fails to add, do not delete the work folder and print "Deployment Failed" along with the error information and the failed command.

Additional Notes

• All paths are fully resolved and printed before any processing begins.
• Original file casing is preserved in the disk image.
• The final disk image will overwrite any existing file with the same name.
• Failures in file addition are clearly reported along with the command used.