Forge Setup: OCaml on Your Machine

The in-page engine is a fine training sword, but real games need a real forge: today you install the OCaml toolchain on your own machine, build the starter game, and watch it bounce at localhost:8000.

You will be able to…

Say what opam, a switch, dune, utop and js_of_ocaml each do
Install OCaml 5.5.0 and the game-dev tools from the terminal
Build the canvas-starter template and serve it locally
Change the game, rebuild, refresh — the loop you'll live in for months
Put AI assistants to work on boilerplate without handing them the fun parts

Meet the crew

Why leave the browser at all? Because the page engine, honest as it is, can't build multi-file projects, can't read files, and — this matters in Phase 4 — can't run truly parallel code. For that you need the full toolchain. Five names, five jobs:

opam — the quartermaster. A package manager that fetches, builds and installs OCaml software: compilers, libraries, tools. One command, correct versions, no tar-file archaeology.
a switch — not a program but an opam idea: a self-contained OCaml world (one compiler + its libraries) living in its own directory. You can keep several — this course on 5.5.0, experiments elsewhere — and nothing ever collides.
dune — the master builder. It reads tiny dune files describing what your project is, then works out what to compile, in what order, with which flags. You say dune build; it does the thinking.
utop — the toplevel in power armour. The same conversation you've been having in this page, but with history, tab-completion and colours. Your scratchpad on the machine.
js_of_ocaml — the portal. It translates compiled OCaml into JavaScript so your game runs in any browser. It's how this site's engine exists, and how the starter template ships your code to a canvas.

Light the forge

Commands below are for Linux and macOS. Windows knights: use WSL2 and follow the Linux path. The Setup page has full per-OS instructions, package-manager alternatives and fixes for the usual ambushes — keep it open in a second tab. First, install opam and let it set up its home:

opam init takes a few minutes and offers to hook itself into your shell — say yes. Then create the course switch, wire it into the current terminal, and stock it:

opam switch create 5.5.0 downloads and compiles the compiler itself — a coffee-length wait is normal. The last line is the victory condition: if ocaml -version answers 5.5.0, the forge is lit.

⚠️ Fresh terminal says

command not found:
    dune

? That shell hasn't been introduced to your switch yet. Run eval $(opam env) in it (or restart the terminal if you let opam init hook your shell). This is the single most common setup ambush — now you know the counter-spell.

Summon the starter

Download canvas-starter.zip — a minimal, complete OCaml game project: a splash of OCaml, a dune file that compiles it to JavaScript via js_of_ocaml, and a web page with a canvas. Unzip, build, serve:

Now open http://localhost:8000. A colourful square should be bouncing around a canvas — your machine just compiled OCaml to JavaScript and served it like a real web game. (opam exec -- simply runs the command inside your switch; Python's http.server is nothing OCaml-ish, just a one-line static file server.)

Time for the sacred loop: edit → build → refresh. Leave the server running in its terminal and open a second one. In the project, open the main OCaml file (src/main.ml in the starter) and find the square's colour string — change it to "hotpink", or make the speed number outrageous. Then:

Refresh the browser. Your change is live. That loop is 90% of game development; everything after this lesson just makes the edit step more interesting. Claim your XP:

`opam --version` answers with 2.1 or newer `ocaml -version` answers `The OCaml toplevel, version 5.5.0` `opam install -y dune utop js_of_ocaml js_of_ocaml-ppx` finished without errors — the forge is stocked `opam exec -- dune build` succeeds in `canvas-starter` and http://localhost:8000 shows the bouncing square You changed a colour or speed in the starter, rebuilt, refreshed — and saw your change in the browser

🎮 Side quest: the built game is just static files sitting in _build/default/web — no server logic at all. Copy them onto the homelab (the Setup page has Docker + nginx notes) and serve the bouncing square to the whole house. Playing your build from a tablet on the sofa is a rite of passage.

The AI at the forge

You have apprentice smiths available: Claude, Antigravity and friends. Camel Quest's rule for them is simple — AI kills the grind, not the learning. Let them write what's boring and standardised: dune stanzas, js_of_ocaml FFI bindings (the repetitive glue between OCaml and browser APIs — you'll meet it properly later), HTML scaffolds. Keep for yourself what the course is actually about: game logic, types, architecture. A decent test: if getting it wrong would teach you nothing, delegate it; if getting it wrong is the lesson, write it yourself.

So a fine prompt this week is "add a dune stanza that also copies assets/ into the build output" — and a self-defeating one is "write the bounce logic for my square". Either way, read the diff before you accept it. You are the smith; they hold the tongs.

🧠 Coach's corner — Run this session driver/navigator: Maks types every command and reads every line of output aloud; you navigate and resist touching the keyboard. When something breaks — PATH, proxy, an unhooked shell — debugging it together is the lesson; which ocaml pointing into ~/.opam/5.5.0/bin is the "am I in the right world?" probe worth teaching. And agree on the AI contract now, while the stakes are boilerplate-sized: generated code gets read line by line before it's committed, every time.

Checkpoint quiz

Loot collected

opam quartermasters, a switch isolates, dune builds, utop converses, js_of_ocaml teleports OCaml into browsers.
Your machine runs OCaml 5.5.0 with the full game-dev kit installed.
canvas-starter builds with dune build and serves at localhost:8000.
The loop: edit → build → refresh. You've run it at least once.
AI writes boilerplate; you write the game. Read every diff.

Next: back to the browser with new respect — and 120,000 pixels to paint.