Watching the Spring Seep

// internal/render/tilemap.go

// DrawMapVia blits the cells of a tile map the camera can see, each at
// the screen pixel the camera puts it on, and returns how many it drew.
// Cells outside the viewport are never offered to the blitter: DrawMap
// leans on the clip rectangle to throw them away, which is honest work
// on a map of ninety-six cells and waste on a map of thousands.
func DrawMapVia(b *Buffer, m *TileMap, s *Sheet, cam Camera) int {
	vis := cam.Cells(TileCell, m.Cols, m.Rows)
	n := 0
	for cy := vis.Y0; cy < vis.Y1; cy++ {
		for cx := vis.X0; cx < vis.X1; cx++ {
			i := m.At(cx, cy)
			sx, sy := cam.ToScreen(cx*TileCell, cy*TileCell)
			b.Blit(s, s.Frame(i%TileCols, i/TileCols), sx, sy)
			n++
		}
	}
	return n
}

$ go run ./cmd/worldc -pan -from 40
worldc 0.0.5 seed 5: 12x8 cells of 16 = 192x128 world pixels, 192x128 window at camera 0,0, 10 ticks a second
  frame  keys           camera    cells  frame
      1  -                0,  0     96  d2ac5a5be8e6
      9  right            0,  0     96  d2ac5a5be8e6
     17  right+down       0,  0     96  d2ac5a5be8e6
     25  down             0,  0     96  d2ac5a5be8e6
     41  left+up          0,  0     96  d2ac5a5be8e6

That switch runs the world up to one tick, freezes it there, and walks the camera about under a scripted set of key holds. The window is left at its default here, which is the size of the valley, and chapter 20's clamp pins a view inside the world it is a view of, so a world exactly as big as the window leaves the camera one legal position: five frames, all ninety-six cells, one hash five times. That equality is what the new name has to earn before anything else. A camera that can see the whole map must draw exactly what DrawMap drew from the origin, down to the digest, or the culling is dropping cells that had pixels to put on the screen. The smaller-window run below is the case where the count moves as the camera scrolls.

// cmd/worldc/main.go

// shared is the client that keeps the world itself instead of a copy of
// what it said. Every field of it is written by the simulation
// goroutine and read by the window's.
type shared struct {
	art *art
	cam render.Camera
	w   *sim.World
}

func (v *shared) Draw(b *render.Buffer) {
	if v.w == nil {
		b.Fill(render.Void)
		return
	}
	kind := make([]render.Kind, MapW*MapH)
	for i := range kind {
		t, _ := v.w.Ground.At(sim.Coord{X: i % MapW, Y: i / MapW})
		kind[i] = kindOf(t)
	}
	b.Fill(render.Void)
	render.DrawMapVia(b, render.Autotile(MapW, MapH, kind), v.art.tiles, v.cam)
	for _, e := range v.w.Roster() {
		if e.Kind != sim.Walker {
			continue
		}
		sx, sy := v.cam.ToScreen(e.At.X*Tile, e.At.Y*Tile)
		b.Blit(v.art.walk, v.art.walk.Frame(0, 0), sx, sy)
	}
	readout(b, v.art.font, frame{Tick: v.w.Tick(),
		Water: v.w.Ground.Count(sim.Water), Pop: v.w.Population()})
}

// cmd/worldc/main.go — main, joining the two

	v := &shared{art: a, cam: cam}
	cfg.Paced = true
	cfg.Watch = func(w *sim.World) { v.w = w }
	go func() { done <- sim.Run(cfg, stop) }()
	runWindow(v, cam, done, stop, *verify)

Nothing about that is lazy. Draw uses the autotiler from chapter 19, the camera transform from chapter 20, the blitter from chapter 16 and the readout from chapter 21, and it draws a correct picture of the valley on the author's screen at sixty frames a second. The client even shuts down properly: the window closes, close(stop) asks the world to finish, and <-done waits for it to say that it has.

// cmd/worldc/main.go

// frame is one tick of the world as the renderer is allowed to see it:
// numbers copied out of the simulation while the simulation was between
// two ticks, and not one pointer back into it.
type frame struct {
	Tick    uint64
	Water   int
	Pop     int
	Map     *render.TileMap // never written again once it is in here
	Snaps   []render.Snap
	Asked   int      // cells asked for a tile index this tick
	Retiled []Retile // the ones whose answer changed
}

// observer is the client's half of the simulation goroutine. Everything
// it owns is touched by that goroutine and no other, and the only thing
// that leaves is a frame, over a channel.
type observer struct {
	kind   []render.Kind                // this client's own copy of the ground
	tiles  *render.TileMap              // the tile indices that copy produces
	seen   map[sim.EntityID]render.Snap // where each walker stood last tick
	frames chan<- frame
	stop   <-chan struct{}

	asked   int      // cells asked for a tile index on the last tick
	retiled []Retile // of those, the ones whose answer was different
}

// tick is what sim.Run calls when a tick is finished and nothing is
// moving. It reads the world, builds one frame out of copies, and hands
// it over.
func (o *observer) tick(w *sim.World) {
	o.reground(w.Ground)
	fr := frame{
		Tick:    w.Tick(),
		Water:   w.Ground.Count(sim.Water),
		Pop:     w.Population(),
		Map:     o.tiles,
		Snaps:   o.snapshot(w),
		Asked:   o.asked,
		Retiled: o.retiled,
	}
	select {
	case o.frames <- fr:
	case <-o.stop:
	}
}

The Map field is a pointer, and it is the one place the promise in that comment has to be kept by hand. The channel holds a single frame, and that buffer of one is the whole coupling between the two goroutines: the world hands a tick's picture over and goes back to ticking, and if the window is slow the world waits at that send instead of racing ahead into memory somebody is reading. The second case in the select covers shutdown.

// cmd/worldc/main.go

// reground brings the client's copy of the ground up to date and retiles
// what changed. A cell's tile depends on itself and its four neighbours
// and on nothing else, so one flooded cell costs five lookups and the
// other ninety-one entries stay exactly as they were.
func (o *observer) reground(g *sim.Grid) {
	o.asked, o.retiled = 0, nil
	if o.kind == nil {
		o.kind = make([]render.Kind, g.W*g.H)
		for i := range o.kind {
			t, _ := g.At(sim.Coord{X: i % g.W, Y: i / g.W})
			o.kind[i] = kindOf(t)
		}
		o.tiles = render.Autotile(g.W, g.H, o.kind)
		o.asked = g.W * g.H
		return
	}
	var flooded []int
	for i := range o.kind {
		t, _ := g.At(sim.Coord{X: i % g.W, Y: i / g.W})
		if k := kindOf(t); k != o.kind[i] {
			o.kind[i] = k
			flooded = append(flooded, i)
		}
	}
	if len(flooded) == 0 {
		return
	}
	// A published tile map is never written to again: the renderer may
	// still be holding the last one. This one is a copy with five
	// entries recomputed.
	next := &render.TileMap{Cols: o.tiles.Cols, Rows: o.tiles.Rows, Cell: slices.Clone(o.tiles.Cell)}
	for _, i := range flooded {
		cx, cy := i%g.W, i/g.W
		for _, d := range [][2]int{{0, 0}, {0, -1}, {1, 0}, {0, 1}, {-1, 0}} {
			nx, ny := cx+d[0], cy+d[1]
			if nx < 0 || nx >= g.W || ny < 0 || ny >= g.H {
				continue
			}
			o.asked++
			was := next.At(nx, ny)
			now := render.TileOf(g.W, g.H, o.kind, nx, ny)
			next.Cell[ny*next.Cols+nx] = uint8(now)
			if now != was {
				o.retiled = append(o.retiled, Retile{CX: nx, CY: ny, Was: was, Now: now})
			}
		}
	}
	o.tiles = next
}

$ go run ./cmd/worldc -headless -ticks 1 -map
worldc 0.0.5 seed 5: 12x8 cells of 16 = 192x128 world pixels, 192x128 window at camera 0,0, 10 ticks a second

the tile map at tick 1
  row 0  18 18 18 18 18 18 18 18 18 18 18 18
  row 1  18 16 17 16 16 17 16 16 16 16 16 18
  row 2  18 17 17 16 17 16 17 16 17 16 16 18
  row 3  18 16  9  1  1  1  3 17 17 17 17 18
  row 4  18 16 12  4 19  0  0  3 17 17 17 18
  row 5  18 16 16 17  8  4  4  6 16 17 17 18
  row 6  18 16 17 17 14 17 17 16 16 17 17 18
  row 7  18 18 18 18 18 18 18 18 18 18 18 18
  96 cells asked for a tile index on the client's first frame

Read that table against chapter 19's and it is the same eight rows of numbers, down to the 19 sitting at cell (4, 4) where the second open water tile won its coin toss. Chapter 19 computed it from a grid it generated for itself and saved a PNG. This one came out of a running world over a channel, and the two agree because the autotiler is a function of the ground and nothing else. Note the last line: the client's first frame pays the full ninety-six, because a client that has just started has no copy of the ground to compare against.

reground builds a new TileMap instead of editing the one it has because the renderer may still be holding tick 39's frame while tick 40 is being computed. Writing five entries into the map that frame points at would change a picture that has already been handed over, which is the failure box's mistake at a smaller scale.

// cmd/worldc/main.go

// Step is called once per frame by the shell: read the keys, then take
// whatever the world has finished since the last frame.
func (v *view) Step(in *input.State) error {
	if in.Pressed(input.Quit) {
		return shell.ErrQuit
	}
	if in.Down(input.Left) {
		v.cam.X -= Speed
	}
	// ... right, up and down, the same three lines each ...
	v.cam.Clamp(MapW*Tile, MapH*Tile)

	for {
		select {
		case fr := <-v.frames:
			v.cur, v.have, v.arrived = fr, true, time.Now()
			continue
		default:
		}
		break
	}
	return nil
}

// Draw paints the frame. Alpha is how much of a tick has passed since
// the newest one arrived, and it stops at 1: a renderer that ran on
// past the end of the interval would be extrapolating, which is a
// guess about a tick the world has not taken.
func (v *view) Draw(b *render.Buffer) {
	if !v.have {
		b.Fill(render.Void)
		b.DrawTextIn(v.art.font, 4, 4, "WAITING FOR TICK 1", bone)
		return
	}
	alpha := float64(time.Since(v.arrived)) / float64(sim.TickDuration)
	if alpha > 1 {
		alpha = 1
	}
	paint(b, v.art, v.cam, v.cur, alpha)
}

// paint draws one whole frame: the ground through the camera, the
// walkers between two ticks, the readout on top. It reads a frame and
// the art, and nothing else in the program.
func paint(b *render.Buffer, a *art, cam render.Camera, fr frame, alpha float64) int {
	b.Fill(render.Void)
	cells := render.DrawMapVia(b, fr.Map, a.tiles, cam)
	p := float64(fr.Tick) - 1 + alpha
	for _, s := range fr.Snaps {
		wx, wy := s.At(alpha)
		sx, sy := cam.ToScreen(wx, wy)
		b.Blit(a.walk, a.walk.Frame(pose(s, p), 0), sx, sy)
	}
	readout(b, a.font, fr)
	return cells
}

The receive loop is non-blocking on purpose. A window that waited for a tick would refresh ten times a second and throw away the interpolation this volume just built. Where chapter 22's client computed alpha from a clock it was handed, this one measures it from when the newest tick showed up, which is all a receiver knows about a sender's schedule. The clamp at 1 is new: if the next tick is late, the picture holds at the position the world last confirmed instead of walking on into a step nobody has computed.

The first branch is the client's first tenth of a second. sim.Run reports after a tick, never before one, so a window is open and asking for pixels before the world has said anything at all. Then paint, ten lines long, taking no argument that can change under it. That is the payment for the frame type: chapter 19's tile map, chapter 20's camera, chapter 16's blitter, chapter 22's blend and chapter 21's screen-space readout, in the order the layers stack, reading data that stopped moving before the function was called.

One thing inside it did change. Chapter 22 timed a two-frame walk, because two frames were all it needed to show that the timing worked; the sheet has four, drawn as a cycle, so pose now runs through all of them at the same sixty milliseconds each. A whole stride takes 240 milliseconds of presentation time, which is two and two fifths of a tick, so the foot a tick boundary lands on keeps moving instead of repeating.

$ go run ./cmd/worldc -headless -ticks 120 -from 39 -to 41 -shot seep
worldc 0.0.5 seed 5: 12x8 cells of 16 = 192x128 world pixels, 192x128 window at camera 0,0, 10 ticks a second
  tick  39  water 16  pop 3   #2 144, 48  #3   0,  0  3711b1fe2693105b
  tick  40  water 17  pop 3   #2 144, 64  #3  16,  0  d2ac5a5be8e61921
            cell (4,2) asked again: tile 17 became tile 11
            cell (4,3) asked again: tile  1 became tile  0
            5 cells asked, 2 answered differently

763 of 24576 pixels differ between tick 39's frame and tick 40's
   280 in the 2 retiled cells
   410 in the 4 squares a walker stood on in either frame
    73 in the readout's corner {4 4 65 33}
     0 anywhere else on the frame
wrote seep-mask.png: every pixel the two frames disagree about
  tick  41  water 17  pop 3   #2 128, 64  #3  32,  0  1b9dbb29b1811677

120 ticks drawn, one frame each
  tick   1  sha256 d87005a1035991b11534fb5a0b7562dc7488fd28776eb6ec97905ba94c5dea07
  tick  20  sha256 91cee9d8470126deb94fcd12558561a3dfde8a7346263dc48ffd2e605194fe8b
  tick  40  sha256 d2ac5a5be8e61921bff3fb644275d4c7ade2eb430e7119940079be5c5ba4564b
  tick  80  sha256 d671b3b7cb4e33e52f9a4f8b464ee8e3690354ec5288d0d8f305a09d05c79170
  tick 120  sha256 d0509924a32acfc64e24bf4c5ff454e0b7343a0788bb85cfdaf8423d402fd367

Take the two retile lines apart, because they are the shoreline redrawing itself in numbers. Cell (4, 2) was soil and drew tile 17, the second of the two soil tiles chapter 18 drew so a field of them would not read as graph paper. It is water now, and its four neighbours answer land to the north, land to the east, water to the south and land to the west: 1 + 2 + 0 + 8 = 11. Tile 11 is a water cell with a bank on three sides and an opening south, which is exactly what a new square hanging off the top of a pond looks like.

Cell (4, 3) is the one nobody would have thought to redraw. It was already water, it is still water, its own kind did not change at all. What changed is its north neighbour, which used to be soil and gave it a mask of 1, a single dark band along its top edge. Now the north is wet too, its mask is 0, and it draws open water. The waterline that ran along the top of that cell has moved up one square, and no code anywhere decided that. It fell out of five lookups.

The four lines under the hashes are the claim this volume can make and volume 1 could not. 763 pixels of 24,576 changed between one tick and the next, and every one of them has a name. 280 are inside the two cells that were retiled. 410 are inside the four sixteen-by-sixteen squares a walker occupied in one frame or the other. 73 are inside the rectangle the readout writes in, which is the 39 turning into a 40 and the 16 turning into a 17. And the last line reads zero: not one pixel of that frame moved for a reason the client could not account for.

// internal/input/input.go — the table the keys column is printed from

var names = [NumKeys]string{"left", "right", "up", "down", "snap", "quit"}

func (k Key) String() string {
	if k < 0 || k >= NumKeys {
		return "?"
	}
	return names[k]
}

A log of which keys were held wants those keys spelled, and chapter 15 gave Key six constants and no way to print one.

$ go run ./cmd/worldc -pan -from 40 -vw 128 -vh 96
worldc 0.0.5 seed 5: 12x8 cells of 16 = 192x128 world pixels, 128x96 window at camera 32,16, 10 ticks a second
  frame  keys           camera    cells  frame
      1  -               32, 16     48  9918d204dc1f
      9  right           56, 16     54  8bf0e4049a24
     17  right+down      64, 32     48  8f711b5e93f3
     25  down            64, 32     48  8f711b5e93f3
     41  left+up         16,  0     48  3d5c3c1f3185

Four things in five lines. The camera starts centred, so the rock rim falls outside the frame. Eight frames of held right move it 24 pixels and the cell count climbs from 48 to 54, because a camera standing between two cell boundaries needs a partial column at each edge and reaches nine columns to fill eight columns' worth of screen. Frames 17 and 25 have the same hash: the camera hit the map's south-east limit at (64, 32) and holding the key down after that does nothing, because chapter 20's clamp refuses to show ground the map does not have. Then sixteen frames of left and up together, which would put the camera at (16, −16); it lands at (16, 0), stopped by the same clamp at the northern edge.

$ go run ./cmd/worldc -ticks 60 -until 43 -from 39 -to 41 -verify   (wall-clock figures measured on the author's machine; your run will differ)
worldc 0.0.5 seed 5: 12x8 cells of 16 = 192x128 world pixels, 192x128 window at camera 0,0, 10 ticks a second
frame 1: sent 98304 bytes, read back 98304, 0 differ; the screen holds the numbers we handed it
worldc: the world stopped cleanly

the window drew 18 frames while the world went from tick 39 to tick 41
alpha at the first eight: 0.000 0.166 0.340 0.500 0.666 0.833 0.000 0.167
distinct pictures: 18;  frames drawn exactly on a tick boundary: 0

The window is 768 by 512 on the author's screen, four screen pixels to one of ours, and the valley fills it. The readout counts. The two animals cross the soil at a walking pace with their legs going, and they do it on six pictures per tick out of a simulation that decided where anything was three times in that span. The first line is chapter 15's read-back check, still passing: 98,304 bytes went to WritePixels, 98,304 came back, none of them changed on the way.

The last line is chapter 22's awkward arithmetic arriving in a real window. Eighteen distinct pictures, and not one of them is a frame the contract hashes. Landing on a tick means alpha exactly 1, and a display refresh will not coincide with a tick deadline to the nanosecond. So the frames a person watches and the frames a test can name are two sets that never meet, and that is the arrangement rather than a hole in it: what the contract binds is the drawing code, and the drawing code is what made all eighteen.

// cmd/worldc/main_test.go

// TestAPublishedMapIsNeverWrittenAgain checks the promise the renderer
// depends on: a frame handed over stays exactly as it was handed over,
// however many ticks the world takes afterwards.
func TestAPublishedMapIsNeverWrittenAgain(t *testing.T) {
	got := run(t, 45)
	before := append([]uint8(nil), got[38].Map.Cell...) // tick 39's ground
	for i, c := range got[38].Map.Cell {
		if c != before[i] {
			t.Fatalf("tick 39's map changed at cell %d after publication", i)
		}
	}
	if got[38].Map == got[39].Map {
		t.Error("tick 39 and tick 40 share one tile map: the seep wrote into a published one")
	}
	if got[40].Map != got[39].Map {
		t.Error("tick 41 copied a map that did not change; a tick with no seep should share it")
	}
}

$ go test -count=1 -v ./cmd/worldc/
=== RUN   TestTheSeepFrameMatchesItsHash
--- PASS: TestTheSeepFrameMatchesItsHash (0.00s)
=== RUN   TestOneSeepRetilesFiveCells
--- PASS: TestOneSeepRetilesFiveCells (0.00s)
=== RUN   TestAPublishedMapIsNeverWrittenAgain
--- PASS: TestAPublishedMapIsNeverWrittenAgain (0.00s)
=== RUN   TestValleyMatchesItsHash
--- PASS: TestValleyMatchesItsHash (0.00s)
PASS
ok  	theworld/cmd/worldc	0.005s

$ go test -count=1 -race ./...
?   	theworld/cmd/exportart	[no test files]
?   	theworld/cmd/mkatlas	[no test files]
?   	theworld/cmd/mkfont	[no test files]
?   	theworld/cmd/palcheck	[no test files]
ok  	theworld/cmd/worldc	1.045s
ok  	theworld/internal/input	1.014s
ok  	theworld/internal/render	1.978s
?   	theworld/internal/shell	[no test files]
ok  	theworld/internal/sim	1.083s

The last two clauses of that test are the interesting pair. Tick 39 and tick 40 must not share a tile map, because the seep changed the ground and the older frame must keep the ground it was drawn with. Tick 40 and tick 41 must share one, because nothing flooded and copying ninety-six bytes to say so would be work with no question behind it. Sharing is safe precisely when nothing writes, and the two assertions together say when that is.

The fourth test in that listing is chapter 19's, riding along: rewriting the client around a camera meant rewriting the main that used to assert the valley's hash, so the assertion moved into this file and the map seed 5 draws stays pinned to the same sixty-four characters it was pinned to four chapters ago.

The -race line is the failure box's verdict on the finished client. The same two goroutines, the same three counts read out of a world that is still running, and the detector has nothing to report, because the only thing crossing between them is a value that was finished before it was sent.

Add the atlas-path option to the client with the code below. The default remains assets/tiles/valley-tileset.png, preserving the original picture and its hashes.

In cmd/worldc/main.go, replace loadArt with these two functions. Keep the existing fmt and path/filepath imports. The wrapper keeps callers on the default atlas; the second function resolves the selected path and checks its dimensions before loading the unchanged walker and font.

func loadArt(root string) (*art, error) {
	return loadArtWithTiles(root, "assets/tiles/valley-tileset.png")
}

func loadArtWithTiles(root, tileset string) (*art, error) {
	path := tileset
	if !filepath.IsAbs(path) {
		path = filepath.Join(root, path)
	}
	tiles, err := render.LoadSheet(path, render.TileCell)
	if err != nil {
		return nil, err
	}
	if tiles.Pix.W != 4*Tile || tiles.Pix.H != 5*Tile {
		return nil, fmt.Errorf("tileset %s is %dx%d; want 64x80 (four columns, twenty cells)", path, tiles.Pix.W, tiles.Pix.H)
	}
	walk, err := render.LoadSheet(filepath.Join(root, "assets/sprites/walker.png"), Tile)
	if err != nil {
		return nil, err
	}
	font, err := render.LoadFont(filepath.Join(root, "assets/sprites/font6x8.png"), 6, 8, ' ')
	if err != nil {
		return nil, err
	}
	return &art{tiles: tiles, walk: walk, font: font}, nil
}

In main, add this flag beside -replay, before flag.Parse():

tileset := flag.String("tileset", "assets/tiles/valley-tileset.png", "the 64x80 terrain atlas; changes drawing, not the world")

Replace a, err := loadArt(".") with the call below. Keep the following error check unchanged.

a, err := loadArtWithTiles(".", *tileset)

go run ./cmd/worldc -headless -ticks 41 -from 39 -to 40 -shot current
go run ./cmd/worldc -headless -ticks 41 -from 39 -to 40 -tileset assets/studies/quiet-tileset.png -shot quiet
go run ./cmd/worldc -tileset assets/studies/quiet-tileset.png

Compare current-t040.png with quiet-t040.png. Each is the client's 192 by 128 framebuffer at alpha 1, where the interpolated position reaches the current tick. The windowed command uses the same alternate atlas while the world ticks and the walkers animate. Press Escape to close it; use -vw 128 -vh 96 if you want room to pan the camera.

Only the art loader receives the path. loadArtWithTiles loads a sheet with sixteen-pixel cells and checks that it is four columns by five rows before a frame can use it. A walker sheet also has sixteen-pixel cells, but its four columns and one row cannot supply the twenty terrain IDs. The loader rejects that mistake instead of silently drawing missing cells.