A Place on the Grid

// internal/sim/coord.go
// Package sim holds the simulation's own types. Nothing in here
// prints, listens, or knows that a command called worldd exists.
package sim

// Coord is a place on the world grid: column X, row Y.
type Coord struct {
	X int
	Y int
}

// cmd/worldd/main.go
package main

import (
	"fmt"

	"theworld/internal/sim"
)

func main() {
	var origin sim.Coord
	spring := sim.Coord{X: 12, Y: 7}
	fmt.Println("origin:", origin)
	fmt.Println("spring:", spring)
	fmt.Println("spring column:", spring.X)
}

$ go run ./cmd/worldd
origin: {0 0}
spring: {12 7}
spring column: 12

type Coord struct { ... } teaches Go a new noun. From that line on, Coord is as real to the compiler as int: you can declare variables of it, pass it, return it.

The import path theworld/internal/sim is the module name from last chapter plus the directory. Inside main, the package's names arrive with a sim. prefix.

Capitalized names like Coord and X are the ones a package makes visible outside itself.

var origin sim.Coord got the zero value with no assignment anywhere. A struct's zero value is every field at its own zero, so an unset place is {0 0}, the top-left corner, never garbage.

The struct literal sim.Coord{X: 12, Y: 7} builds a value with the fields named, so the reader of the call site knows which 12 is which. The dot in spring.X reaches into the value for one field.

// internal/sim/coord.go — add below the type

// Offset returns the coordinate dx columns and dy rows away.
func (c Coord) Offset(dx, dy int) Coord {
	return Coord{X: c.X + dx, Y: c.Y + dy}
}

// Dist returns the number of grid steps between two coordinates,
// counting only moves along a row or a column.
func (c Coord) Dist(o Coord) int {
	dx := c.X - o.X
	if dx < 0 {
		dx = -dx
	}
	dy := c.Y - o.Y
	if dy < 0 {
		dy = -dy
	}
	return dx + dy
}

// cmd/worldd/main.go — the new body of main
	var origin sim.Coord
	spring := sim.Coord{X: 12, Y: 7}
	east := spring.Offset(1, 0)
	fmt.Println("east of spring:", east)
	fmt.Println("origin to spring:", origin.Dist(spring), "steps")
	fmt.Println("spring to origin:", spring.Dist(origin), "steps")

$ go run ./cmd/worldd
east of spring: {13 7}
origin to spring: 19 steps
spring to origin: 19 steps

The part in parentheses before the name, (c Coord), is the receiver. It declares that Offset belongs to Coord, and inside the method c is the coordinate the call happened on.

You call it with the same dot that reads a field. spring.Offset(1, 0) asks the spring for the square one column east.

Dist counts steps the way something walking the grid would, no diagonals: from the origin to the spring is 12 columns plus 7 rows, 19 steps. The two if blocks flip negative differences positive, so the answer comes out the same from either end, as the run confirms.

Offset never touches c. It builds and returns a new Coord, and spring is still {12 7} afterwards. That choice turns into this chapter's worked failure.

// internal/sim/cell.go
package sim

// Cell is one square of ground: where it sits, how high the ground
// is, and how deep the water standing on it runs. Heights and depths
// are in meters.
type Cell struct {
	At        Coord
	Elevation float64
	Water     float64
}

// Wet reports whether any water stands on the cell.
func (c Cell) Wet() bool {
	return c.Water > 0
}

// Surface returns the height of the cell's top: ground plus water.
func (c Cell) Surface() float64 {
	return c.Elevation + c.Water
}

// cmd/worldd/main.go — the new body of main
	spring := sim.Coord{X: 12, Y: 7}
	pool := sim.Cell{At: spring, Elevation: 1.0, Water: 0.4}
	bank := sim.Cell{At: spring.Offset(1, 0), Elevation: 2.5}
	fmt.Println("pool:", pool.At, "wet:", pool.Wet(), "surface:", pool.Surface())
	fmt.Println("bank:", bank.At, "wet:", bank.Wet(), "surface:", bank.Surface())

$ go run ./cmd/worldd
pool: {12 7} wet: true surface: 1.4
bank: {13 7} wet: false surface: 2.5

The bank literal names only two of the three fields, and Water quietly takes its zero: dry, exactly as a field left unsaid should be.

Both methods answer questions any part of the server might ask, and both answer them in one place. If the definition of wet ever grows a threshold, the code that changes is one line in sim, not a comparison copied through the codebase.

That is the case for methods in one sentence: the type carries its own vocabulary, so the rest of the program asks instead of assuming.

// internal/sim/cell.go — the obvious attempt
// Flood adds depth meters of standing water to the cell.
func (c Cell) Flood(depth float64) {
	c.Water += depth
}

// cmd/worldd/main.go — the new body of main
	spring := sim.Coord{X: 12, Y: 7}
	bank := sim.Cell{At: spring.Offset(1, 0), Elevation: 2.5}
	fmt.Println("before:", "wet:", bank.Wet(), "water:", bank.Water)
	bank.Flood(0.3)
	fmt.Println("after: ", "wet:", bank.Wet(), "water:", bank.Water)

$ go run ./cmd/worldd
before: wet: false water: 0
after:  wet: false water: 0

// internal/sim/cell.go — the fix: *Cell, not Cell
// Flood adds depth meters of standing water to the cell.
func (c *Cell) Flood(depth float64) {
	c.Water += depth
}

$ go run ./cmd/worldd
before: wet: false water: 0
after:  wet: true water: 0.3

One character changed. *Cell means the method receives not a copy of the cell but its address: a pointer, a value that says where the original lives in memory.

Through the pointer, c.Water += depth reaches the actual bank, and the run shows the water arriving and staying.

The call site did not change at all. bank.Flood(0.3) still reads the same, because Go sees a pointer receiver and passes the address for you.

The receiver declaration is where the choice lives, and it is a one-word answer to one question: does this method change the thing it belongs to? No: value receiver. Yes: pointer receiver.