The Workstation

Verifying the workstation

The first machine in The World is the workstation: the compiler, the container engine, and the directory where the server starts. Never trust an installed tool until it has run something and you have read the output.

An installer finishing without complaint proves the installer ran. It does not prove the compiler compiles or the container engine starts containers. Each tool you install today earns its place by doing its actual job once, in front of you, before anything depends on it.

The world is the reason for the strictness. It will run on a machine you control: ground with real soil chemistry, water that flows where the terrain says it must, plants that compete for light, creatures that eat the plants and each other, and a village of characters who remember what happened to them.

The client program is also yours. It lets you walk in, stand in that village, and be remembered. The world ticks while you sleep. It keeps its own history. It never resets.

None of that exists yet, and the book does not hand it over whole. You build the server that owns all of it, the simulation that advances it, the wire protocol that carries it, and the renderer that shows it.

The language is Go. The runtime home is a container. By the last page of this volume, the first server lives in a box that can keep counting time whether or not you are logged in.

Create the theworld module and its worldd command below. Run the formatter, vet and tests before adding simulation behavior.

Go and the first program

go version

$ go version
go version go1.26.3 linux/amd64

The version line proves the toolchain exists. Now make it do its job. Create a scratch directory anywhere (it will not be part of the project; ~/scratch is fine) and put one file in it.

// hello.go
package main

import "fmt"

func main() {
	fmt.Println("the world is not running yet")
}

$ go run hello.go
the world is not running yet

The module and worldd

A scratch file proves the compiler works, but a project of this size needs a structure the tools recognize. Go's unit of project is the module: a directory tree with a go.mod file at its root.

That file names the module and records which Go version and which outside libraries it depends on. Everything you build across all twenty-five volumes lives in one module. Create its home and initialize it:

mkdir theworld
cd theworld
go mod init theworld
go mod edit -go=1.26

$ go mod init theworld
go: creating new go.mod: module theworld
go: to add module requirements and sums:
	go mod tidy

$ cat go.mod
module theworld

go 1.26

Inside the module, layout is convention. Go projects put each runnable program in its own directory under cmd/, named after the binary it produces.

This one is cmd/worldd: the world daemon, the server that will own every rock, river, creature, and villager. The trailing d is an old Unix habit marking a program built to run continuously in the background. By the end of this volume it has work to justify the letter.

// cmd/worldd/main.go
package main

import (
	"fmt"
	"runtime"
)

const version = "0.0.1"

func main() {
	fmt.Println("worldd", version, "starting")
	fmt.Println("go runtime:", runtime.Version())
	fmt.Println("nothing exists yet: no ground, no water, no time")
}

$ go vet ./...

$ go run ./cmd/worldd
worldd 0.0.1 starting
go runtime: go1.26.3
nothing exists yet: no ground, no water, no time

$ go run ./cmd/worldd
# theworld/cmd/worldd
cmd/worldd/main.go:5:2: "os" imported and not used

Podman containers

Podman runs the world's supporting services and reference checks in containers. Each container has a separate user-space view, but shares the host kernel on Linux or a helper VM's kernel on Windows and macOS.

Rootless Podman avoids a privileged daemon. Processor architecture still matters for replay.

podman --version
podman run --rm docker.io/library/alpine:3.22 echo "a container said this"

$ podman --version
podman version 5.7.0

$ podman run --rm docker.io/library/alpine:3.22 echo "a container said this"
a container said this

Replay conditions

A replay claim names its conditions: the same source and inputs, deterministic draw and update order, an exact compiler and dependencies, and a reference platform. A seed alone does not fix all of those.

Later simulation code uses floating-point arithmetic. Its final bits can depend on the architecture and compiler even when every operation appears in a fixed order. The book's byte comparisons test the recorded reference environment; they do not prove identical results on any machine.

Today's go.mod records a compatibility requirement. Likewise, alpine:3.22 and golang:1.26 are mutable tags: a publisher can move either to new content while your local cache still holds the old image.

Exact replay requires an image reference ending in @sha256:… and an explicit platform such as --platform linux/amd64, plus the recorded Go version. Inspect a pulled image with podman image inspect and record its RepoDigests and platform before using the digest reference.

The early volume scripts retain tags. They do not record the original image digest, so resolving a tag today cannot recover that missing provenance. The contract compatibility note records this limit and the digest-pinned references the later volumes actually use.

Checkpoint