A modern BASIC for developers who want to build without unnecessary friction — a real compiler to bytecode, with a runtime for 2D/3D graphics, physics, and networking.

You do not need this repository’s source code to use moonBASIC. Install from a pre-built archive, write .mb files, and run them. Everything below about folders like compiler/ or go build is optional and only for people hacking on the engine itself.

Pre-built binaries ship from github.com/CharmingBlaze/moonbasic/releases (Windows, Linux x64, macOS Apple Silicon). This repository is the engine source; end users normally download from the public repo above.

Optional static page (direct archive links): charmingblaze.github.io/moonbasic/

• IDE bundle includes moonbasic-ide + moonbasic + moonrun (+ README-IDE-RELEASE.txt). Extract and run START-IDE — documentation is built into the IDE. Best for beginners.
• Full runtime includes moonbasic + moonrun (+ README-RELEASE.txt). Use this if you want to play or develop games from the terminal.
• Compiler only is a small folder with moonbasic only (no moonrun). See dist/README.md for the full picture.

1. Download moonbasic-<tag>-ide-… from moonbasic releases.
2. Extract and run START-IDE (see README-IDE-RELEASE.txt in the archive).
3. Open a .mb file — F5 run, Ctrl+Shift+C check, Alt+H help at cursor.

Use moonrun — one command to compile and play. The full-runtime archive includes both moonbasic (compiler/LSP) and moonrun (game engine). For your first window you only need moonrun.

New project: moonbasic new MyGame → cd MyGame → moonrun main.mb (creates main.mb, assets/, and VS Code debug config).

1. Open a terminal in the folder that contains moonrun (and moonbasic) from the full runtime zip/tarball.
2. Check it works: moonrun --version (Windows: moonrun.exe --version).
3. Run a game: moonrun path/to/game.mb — compiles in-process if needed, then opens the engine window.
4. Optional — lint only: moonbasic --check path/to/game.mb (no window).
5. Optional — compile to bytecode: moonbasic path/to/game.mb → writes game.mbc next to the source.

Compiler-only installs (CI/tooling) ship moonbasic without moonrun — use those for --check, --lsp, and .mbc output only; install the full runtime to run games with a window.

Release moonrun does not require Go, GCC, or Clang on your machine — it compiles .mb in-process, then runs the engine. You may still need a normal GPU stack (Linux) or the VC++ x64 redistributable on some Windows setups if a DLL is missing; see README-RELEASE.txt inside the full-runtime archive.

Editor: use the moonBASIC IDE download (recommended), or run moonbasic --lsp for other LSP clients. VS Code: download moonbasic-<tag>-vscode.vsix from moonbasic releases — quick steps. Contributors: DEVELOPER.md — moonBASIC in VS Code.

More detail on what each zip contains: dist/README.md · step-by-step install, first window, and how to ship your game to players: docs/GETTING_STARTED.md (section Ship your game)

Many engines impose their own complexity before you can begin creating. moonBASIC is intentionally direct: one toolchain, one mental model, and a workflow that values clarity and speed.

• Vertical integration — compiler, VM, and engine in one stack.
• 2D and 3D — same language and workflow for both.
• Real compilation — not an interpreter; bytecode executed by a production-oriented runtime (Raylib, Jolt 3D, Box2D 2D, ENet, … where enabled).

The compiler is stable; the standard library covers Tiled, materials, sprites, atlases, particles, audio, lighting, shaders, and more. Explore the documentation index and ARCHITECTURE.md when you want to go deeper.

Compact 3D sample (no # / $ / ? suffixes — implicit typing only):

WINDOW.OPEN(960, 540, "Spinning cube")
WINDOW.SETFPS(60)

cam = CAMERA.MAKE()
CAMERA.SETPOSITION(cam, 0, 2, 8)
CAMERA.SETTARGET(cam, 0, 0, 0)
CAMERA.SETFOV(cam, 45)

cube = MESH.MAKECUBE(2, 2, 2)
mat  = MATERIAL.MAKEDEFAULT()
cubeXform = TRANSFORM.IDENTITY()
angle = 0

WHILE NOT (INPUT.KEYDOWN(KEY_ESCAPE) OR WINDOW.SHOULDCLOSE())
    dt = TIME.DELTA()
    angle = angle + 45 * dt
    TRANSFORM.SETROTATION(cubeXform, 0, angle, 0)
    RENDER.CLEAR(12, 14, 22)
    CAMERA.BEGIN(cam)
        MESH.DRAW(cube, mat, cubeXform)
    CAMERA.END(cam)
    RENDER.FRAME()
WEND

MESH.FREE(cube)
MATERIAL.FREE(mat)
TRANSFORM.FREE(cubeXform)
CAMERA.FREE(cam)
WINDOW.CLOSE()

Full sample with grid and text: examples/spin_cube

1. Compilation produces bytecode with the .mbc extension.
2. Execution is handled by the virtual machine, which talks to Raylib, Jolt, Box2D, ENet, and other systems through CGO where enabled in full runtime builds.

More: docs/reference/, docs/reference/MULTIPLAYER.md (multiplayer hub), docs/JOLT_WINDOWS_PARITY.md (Windows Jolt / CGO notes for engine devs), ARCHITECTURE.md.

git clone https://github.com/CharmingBlaze/moonbasic-compiler
cd moonbasic
# Windows (example): set CGO_ENABLED=1 and a working gcc, then:
go build -o moonbasic.exe .

# Run a 3D sample (full runtime + CGO):
CGO_ENABLED=1 go run -tags fullruntime ./cmd/moonrun examples/spin_cube/main.mb

Guidelines: CONTRIBUTING.md and docs/DEVELOPER.md. CI validates builds, tests, and representative go run . --check samples.

On Windows, a fullruntime link that pulls in Jolt may require prebuilt libJolt.a and libjolt_wrapper.a in third_party/jolt-go/jolt/lib/windows_amd64/. scripts/check-jolt-windows-libs.ps1 checks that both files are present.

MIT — see LICENSE.