ak47andrew/virtual-console

Purpose and workspace shape

This is a Rust workspace for a VEA virtual-machine/cartridge ecosystem: assemble VEA source and assets into cartridges, run them in an emulator, launch workflows, and provide editor/language tooling. The top-level workspace is defined by Cargo.toml; shared VM and cartridge contracts live in src/shared/.

Executable entry points

• Compiler CLI: src/compiler/src/main.rs, with orchestration in src/compiler/src/entry.rs.

• Emulator/runtime executable: src/runtime/src/main.rs.

• Launcher executable, including a non-UI mode: src/launcher/src/main.rs, src/launcher/src/nonui.rs.

• Language-server executable: src/lsp/src/main.rs.

• Flowchart generator executable: src/flowchart-gen/src/main.rs.

These are separate crates under src/, coordinated through the workspace rather than a single server or web application.

Shared VM and cartridge contract

src/shared/ is the architectural boundary between producer-side tooling and execution-side runtime. It defines cartridge representation and loading-related primitives in src/shared/src/cartridge.rs, cartridge manifest structures in src/shared/src/manifest.rs, and VM instruction/operand/register definitions in src/shared/src/opcodes.rs, src/shared/src/operand_types.rs, and src/shared/src/registers.rs. Compiler, runtime, and tooling should depend on these definitions rather than duplicate instruction encoding or cartridge semantics.

Compilation pipeline

The compiler accepts VEA assembly plus cartridge resources, parses and validates instructions, then emits the shared cartridge format. Assembly parsing and operand validation are concentrated in src/compiler/src/vea/parsing.rs and src/compiler/src/vea/operand_checking.rs; compiler dispatch/error handling is in src/compiler/src/entry.rs and src/compiler/src/errors.rs. Asset compilation is a distinct stage for images and palettes under src/compiler/src/images/mod.rs and src/compiler/src/palette/mod.rs. Example cartridge inputs establish the expected boundary: examples/example_cartridge/source.vea, examples/example_cartridge/manifest.toml, and examples/example_cartridge/palette.pal.

Runtime execution and debugging

The runtime loads a compiled cartridge and executes its VM program. src/runtime/src/emulator.rs owns instruction execution/control flow, while src/runtime/src/memory.rs represents VM memory behavior and src/runtime/src/debugger.rs supplies debugging integration. Its primary dependency boundary is the shared cartridge, opcode, register, and memory constants model in src/shared/src/.

Developer tooling and documentation

The LSP packages opcode documentation from src/lsp/opcodes/ during its build (src/lsp/build.rs) and serves language functionality from src/lsp/src/main.rs; it should remain aligned with shared opcode definitions. src/flowchart-gen/src/graph.rs provides a separate analysis/visualization path over program control flow. The mdBook documentation under docs/src/ describes the language and VM model, especially docs/src/assembler.md, docs/src/memory.md, and docs/src/opcodes.md.