Vision Script Compiler + Simulator: A local-first compiler pipeline and visual robot simulator 📦

Note: This package contains only the Vision Script compiler pipeline (lexer → parser → semantic analysis → IR) extracted from the full robot project. It includes a small CLI that compiles a .vscript file and generates a self contained HTML file that visually simulates the robot acting out the compiled program directly in your browser. No server, no hardware, nothing else required.A traditional compiler translates source code into machine code or bytecode while preserving the program’s control flow and runtime behavior.The Vision Script compiler is intentionally different. It is a domain-specific, safety first compiler that evaluates as much of the program as possible at compile time. The final output is a simple, fully resolved, linear sequence of robot instructions.This design prioritizes predictability, inspectability, and safety over flexibility and performance.

---

Table of Contents

1. Layout
2. Setup
3. Run a Script & Get the Simulation
4. Run the Compiler's Own Tests
5. Key Differences
6. Notes & Technical Details

Layout

Setup

# Install dependencies
npm install

Run a Script & Get the Simulation

npm run simulate -- test/scripts/demo.vscript

This compiles test/scripts/demo.vscript and writes test/output/demo.html. You can open it in any browser using your OS-specific command:

Operating System	Command
macOS	open test/output/demo.html
Linux	xdg-open test/output/demo.html
Windows	start test/output/demo.html

What you will see inside the Simulator:

• Robot Head Visuals: A big-eyed head animation reacting in real-time.
• Eye Movements: Eyes move dynamically as EYE_SET, EYE_LEFT, EYE_RIGHT, or EYE_CENTER execute.
• Body Rotations: The body turns on screen during TURN_LEFT and TURN_RIGHT.
• Animations: A walking bob effect for WALK_FORWARD / WALK_BACKWARD and a wiggle animation for DANCE.
• Audio & Logging: A physical speech bubble pops up for AUDIO_SPEAK.
• Control Panel: A live instruction log equipped with Play, Pause, Step, Reset buttons, and an execution speed slider. PRINT outputs show up directly inside the log panel.

You can point the command at any script and choose your own custom output path:

npm run simulate -- path/to/your.vscript path/to/output.html

⚠️ Compilation Safety: If the script fails to compile, the CLI prints the compiler's native diagnostics (line:column: severity: message) and exits non-zero — no HTML is written.

Run the Compiler's Own Tests

npm test

This runs the original unit tests against the extracted compiler (lexer, parser, semantic analyzer, IR generation, loops, variables, IF/RANDOM, etc.) to confirm absolutely nothing was broken while pulling the compiler out of the larger project.

Key Differences

Aspect	Traditional Compiler	Vision Script Compiler
Primary Goal	Generate fast, general-purpose machine/bytecode	Generate a safe, fully predictable robot program
Final Output	Machine code / bytecode / assembly	Flat IR (EXEC / SLEEP / LOG) + HTML simulator
Target Runtime	CPU or Virtual Machine	Physical robot or browser visual simulator
Language Type	General-purpose	Domain-specific (robot control only)
Runtime Loops	Supported	Not supported — fully unrolled at compile time
Runtime Branching	Supported (if, switch, etc.)	Not supported — conditions evaluated at compile time
Variables at Runtime	Yes	No — all values substituted before IR is produced
Dynamic / Random	Runtime evaluation	RANDOM is rolled once at compile time
Arithmetic	Evaluated at runtime	Fully folded at compile time
Safety Limits	Soft or none	Hard limits (MAX_REPEAT=100, MAX_NESTING=5, MAX_INSTRUCTIONS=500)

Notes & Technical Details

• Visual Approximation: The simulator is built to help you understand script behavior quickly — it is not a real-time hardware physics simulation. Action durations (WALK_FORWARD 1200, TURN_LEFT 600, etc.) are rendered proportionally rather than physically accurate.
• Eye Parameters: EYE_SET and EYE_TRACK_PERSON take an absolute angle from 0–180 (where 90 is center). EYE_LEFT and EYE_RIGHT take an optional relative step parameter (defaults to 15°).
• Non-Visual Commands: Commands not interacting directly with the eyes, body