retro-superfx

An umbrella workspace coordinating retro gaming libraries, compilers, language tooling, and homebrew demos targeting the Super Nintendo Entertainment System (SNES) and the SuperFX (GSU / FX3) RISC coprocessor.

---

Workspace Architecture

This repository links 5 specialized Git submodules:

                                [java-language-server]
                             (LSP protocol models & RPC)
                                          │
                                          ├────────────────────────┐
                                          ▼                        ▼
                                    [retro-common] ──> [sfx-optimizer] ──> [retro-lsp]
                              (Lexer, parser, AST)     (Register allocator    (VS Code extension
                                          │             & compiler pass)      & server backend)
                                          │                        │
                                          │                        ▼ (future compiler hook)
                                          └───────────────> [snes-sfx-demo]
                                                      ├── libSFX (SDK & cc65 tools)
                                                      ├── X-GSU  (Macro DSL & 3D math)
                                                      └── SpriteScale / edge-table (Demos)

Subproject	Description	Tech Stack
java-language-server	Zero-dependency pure-Java LSP data models and JSON-RPC message pump.	Java 26, Maven
retro-common	Lexer, parser, tokenization, symbol indexing, and doc extraction for CA65 / SuperFX / X-GSU.	Java 26, Maven
sfx-optimizer	Compiler pass, register allocator (Chaitin-Briggs), stack depth tracker, and web visualizer.	Kotlin, Java 26, Maven
retro-lsp	SNES/SuperFX Language Server Protocol backend and VS Code extension client.	Java 26, JLink, TypeScript, Node.js
snes-sfx-demo	SuperFX homebrew codebase: libSFX SDK, X-GSU macro language, 3D math, and test suite.	SuperFX Assembly, ca65, C, Lua

---

Prerequisites

Ensure the following tools are installed on your host system:

1. Java Development Kit (JDK) 26+:

   java -version

2. Python 3.10+: Used for symbol map synchronization and test harness scripts.

   python3 --version

3. Node.js 20+ & npm: Required for building the retro-lsp VS Code extension.

   node --version && npm --version

4. GNU Make: Required for building SNES ROMs and running unit tests.

   make --version

5. Mesen CE (SNES Emulator): Required for running headless automated tests.
   • Recommended location: ~/Programs/Mesen, specified via MESEN_PATH, or available on your system PATH as Mesen / mesen.

Note on Assembler Toolchain: Precompiled cc65 binaries (ca65, ld65, superfamicheck) are bundled directly inside snes-sfx-demo/libSFX/tools/cc65/bin/ and used automatically by the build system.

---

Installation & Setup

1. Clone the Umbrella Repository

Clone with all submodules initialized and populated:

git clone --recurse-submodules git@github.com:secondsun/retro-superfx.git
cd retro-superfx

If you already cloned the repository without --recurse-submodules:

git submodule update --init --recursive

---

2. Check Workspace Status

Run the workspace status script to verify all submodules, active branches, and working tree states:

./tools/status.sh

---

3. Install Upstream JVM Artifacts to Local Maven Cache

Because downstream projects (sfx-optimizer and retro-lsp) depend on retro-common and languageserver, build and install them to your local ~/.m2 repository:

./tools/install-local.sh

This builds and installs in strict topological order:

1. java-language-server (dev.secondsun:languageserver)
2. retro-common (dev.secondsun:retro-common)
3. sfx-optimizer (dev.secondsun:sfx-optimizer)

---

4. Build and Verify the Entire Stack

To compile and execute unit tests across all JVM projects:

./tools/build-all.sh

Build Options:

• Build and install locally:

  ./tools/build-all.sh --install

• Build everything and compile SNES sample ROMs:

  ./tools/build-all.sh --install --roms

• Fast compile (skip test execution):

  ./tools/build-all.sh --skip-tests

---

Working with SuperFX Assembly & Tests

Running Automated SuperFX Unit Tests

Automated unit tests live in snes-sfx-demo/X-GSU/tests/ and execute via Mesen CE in headless mode with Lua breakpoints:

./tools/run-sfx-test.sh <test_name> [timeout_in_seconds]

Examples:

# Run 3D vector addition test
./tools/run-sfx-test.sh vector3_add 10

# Run 3D vector subtraction test
./tools/run-sfx-test.sh vector3_subtract 10

# Run vector normalization test
./tools/run-sfx-test.sh normalize 10

run-sfx-test.sh automatically:

1. Compiles the test ROM using ca65/ld65 and libSFX.
2. Synchronizes RAM symbol addresses from Test.cpu.sym into test.lua.
3. Launches Mesen CE headlessly (--testrunner) and validates test assertions.

---

Launching the SFX Optimizer Code Viewer

To visually inspect SuperFX variable liveness swimlanes and register allocations:

cd sfx-optimizer
./mvnw test -Dtest=ViewerServerTest#launchViewerManually

Then open your browser to http://localhost:8080.

---

Running the Mesen MCP Server

For AI agent integration and automated emulation/math verification:

cd tools/mesen-mcp
./run-server.sh

Exposes:

• run_sfx_test: Runs regression tests in snes-sfx-demo/X-GSU/tests/.
• assert_sfx_math: Injects inputs into GSURAM/registers and validates math results within epsilon.
• capture_sfx_render: Headlessly captures framebuffers to PNG with bounding boxes and hash metrics.
• profile_sfx_execution: Profiles GSU execution cycles, hotspots, cache residency, and VBlank FPS.
• sfx_resolve_address: Resolves symbol <-> address, memory region, nearest label with delta, and layout ranges from .dbg and .cpu.sym.

---

Running the Retro-LSP MCP Server

To expose SuperFX static analysis tools over stdio for agents:

./retro-lsp/dist/linux/bin/launcher --mcp --workspace /path/to/project [--log]

• --workspace <path> (Required): Establishes the project root and workspace sandbox boundary. All file URIs passed to tools must reside within this directory or its subdirectories. Files are indexed lazily on-demand and kept synchronized with disk modifications.
• --log (Optional): Enables file logging using standard Java logging (java.util.logging). Outputs plain text logs (INFO level and higher) to a temporary file in java.io.tmpdir (retro-lsp-msp.<date>.<time>.log).

Exposes:

• sfx_audit_diagnostics: Audits syntax errors, block structure (function/endfunction), stack cleanup (Δ_SP == 0), and hardware invariants (8-NOP settling before stop, word alignment, no hardware MERGE, modal lifetimes). Alias sfx_audit_invariants is retained for backwards compatibility.
• sfx_expand_macro: Expands X-GSU macros (function, for, if_lt, etc.) to ca65 SuperFX instructions.
• sfx_lookup_symbol: Resolves symbol definitions, scopes, and docs.
• sfx_find_references: Finds references and usages of symbols across the workspace index (understands call, macros, scopes; skips comments and strings).
• sfx_analyze_registers: Live-range intervals, register pressure, and register coloring suggestions.

---

Submodule Management

• Fetch and rebase submodules on latest GitHub commits:

  ./tools/rebase-submodules.sh
  # Or with an alternate branch / preview:
  ./tools/rebase-submodules.sh --branch <branch>
  ./tools/rebase-submodules.sh --dry-run

• Stage and commit updated submodule pointers to origin:

  ./tools/update-submodules.sh

• Run a Git command across all submodules:

  git submodule foreach 'git status -s'

---

Agentic Infrastructure

This root repository includes agent configuration and automation guides:

• AGENTS.md: Architectural reference, calling conventions, and cross-repo invariants.
• .agents/rules/:
  • cross-repo-invariants.md: Guidelines for dependency hygiene and Maven synchronization.
  • sfx-assembly-rules.md: Hardware constraints for the SuperFX 3 (FX3) coprocessor.
• .agents/skills/:
  • build-workspace: Multi-repo build and install procedures.
  • rebase-submodules: Fetch and rebase Git submodules from GitHub.
  • sfx-macro-language: X-GSU ca65 macro language reference (function, call, stack, control).
  • sfx-test-runner: Automated Mesen CE test execution runbook.
  • update-submodules: Stage, commit, and push updated Git submodules to origin.