Something in the World

// internal/sim/entity.go
package sim

// EntityID names one entity for its whole life. IDs are handed
// out once, in order, and never reused, even after a removal.
type EntityID uint64

// EntityKind is what sort of thing an entity is.
type EntityKind uint8

const (
	Shrub EntityKind = iota
	Walker
)

// String makes an EntityKind print as a word.
func (k EntityKind) String() string {
	switch k {
	case Shrub:
		return "shrub"
	case Walker:
		return "walker"
	}
	return "unknown"
}

// Glyph is the one-byte map symbol for an entity kind.
func (k EntityKind) Glyph() byte {
	if k == Walker {
		return '@'
	}
	return 'o'
}

// Entity is one thing standing in the world: what it is, where it
// is, and the ID that stays the same while both of those change.
type Entity struct {
	ID   EntityID
	Kind EntityKind
	At   Coord
}

// cmd/worldd/main.go — a throwaway main: store entities the way
// you already know how, and find one
func main() {
	ents := []sim.Entity{
		{ID: 1, Kind: sim.Shrub, At: sim.Coord{X: 2, Y: 5}},
		{ID: 2, Kind: sim.Shrub, At: sim.Coord{X: 9, Y: 2}},
		{ID: 3, Kind: sim.Walker, At: sim.Coord{X: 10, Y: 6}},
	}
	want := sim.EntityID(3)
	for _, e := range ents {
		if e.ID == want {
			fmt.Println("found:", e.Kind, "at", e.At)
		}
	}
	fmt.Println("looked at", len(ents), "entities to find one")
}

$ go run ./cmd/worldd
found: walker at {10 6}
looked at 3 entities to find one

EntityID is a defined type over uint64 for the same reason Terrain sat over uint8: an ID is not a count, and the compiler should refuse to let one impersonate the other.

Sixty-four bits is deliberate too. IDs are never reused, and at even a million spawns a second a uint64 outlasts any machine you will ever own.

The storage is the honest problem in this stage. A slice answers "find entity 3" by walking every element and comparing. Three entities, three looks, fine.

The valley this book is heading toward holds thousands, and the systems that run it ask "where is entity so-and-so" constantly: every attack names a target, every memory names who it happened with, every log line names its actor.

Answering each by scanning the whole population turns the sim into a search engine for its own contents.

// internal/sim/entity.go — add the placement rule to the kind

// CanStand reports whether this kind of entity may occupy ground of
// kind t. Shrubs root only in soil; a walker stands anywhere dry.
func (k EntityKind) CanStand(t Terrain) bool {
	switch k {
	case Shrub:
		return t == Soil
	case Walker:
		return t != Water
	}
	return false
}

// internal/sim/world.go
package sim

// World owns the ground and everything standing on it.
type World struct {
	Ground *Grid
	ents   map[EntityID]*Entity
	nextID EntityID
}

// NewWorld wraps a terrain grid in a world with nothing standing on it.
func NewWorld(g *Grid) *World {
	return &World{
		Ground: g,
		ents:   make(map[EntityID]*Entity),
		nextID: 1,
	}
}

// Spawn creates an entity of kind k at c and returns its new ID.
// It refuses, returning 0 and false, if c is off the grid or the
// ground there cannot hold this kind of entity.
func (w *World) Spawn(k EntityKind, c Coord) (EntityID, bool) {
	if !w.Ground.In(c) || !k.CanStand(w.Ground.At(c)) {
		return 0, false
	}
	id := w.nextID
	w.nextID++
	w.ents[id] = &Entity{ID: id, Kind: k, At: c}
	return id, true
}

// Get returns the entity with this ID, and whether it exists at all.
func (w *World) Get(id EntityID) (*Entity, bool) {
	e, ok := w.ents[id]
	return e, ok
}

// Remove takes an entity out of the world. Its ID retires with it.
func (w *World) Remove(id EntityID) {
	delete(w.ents, id)
}

// Population is how many entities the world holds right now.
func (w *World) Population() int {
	return len(w.ents)
}

// cmd/worldd/main.go — rebuild chapter 3's hand-drawn valley
// (the soil loop and the pond literal, unchanged), then populate it
	w := sim.NewWorld(g)
	id1, ok := w.Spawn(sim.Shrub, sim.Coord{X: 2, Y: 5})
	fmt.Println("shrub:", id1, ok)
	id2, ok := w.Spawn(sim.Shrub, sim.Coord{X: 9, Y: 2})
	fmt.Println("shrub:", id2, ok)
	id3, ok := w.Spawn(sim.Walker, sim.Coord{X: 10, Y: 6})
	fmt.Println("walker:", id3, ok)
	id4, ok := w.Spawn(sim.Walker, sim.Coord{X: 5, Y: 3})
	fmt.Println("walker on the pond:", id4, ok)
	fmt.Println("population:", w.Population())

$ go run ./cmd/worldd
shrub: 1 true
shrub: 2 true
walker: 3 true
walker on the pond: 0 false
population: 3

The fourth spawn is the placement rule earning its keep: {5, 3} is open water, a walker cannot stand there, and the world said no.

Nothing panicked and nothing was half-created. Spawn checks before it allocates, so a refused spawn leaves no trace, not even a burned ID.

The rule lives on EntityKind, not buried inside Spawn, because "can this kind occupy that ground" is a question other systems ask about squares nobody is spawning into.

The lowercase fields of World matter too: the map and the counter are private, so no caller can hand out an ID or plant something in the pond by reaching around the methods.

// cmd/worldd/main.go — continue after the population line
	if e, ok := w.Get(id3); ok {
		fmt.Println("id", e.ID, "is a", e.Kind, "at", e.At)
		e.At = e.At.Offset(0, -1)
	}
	if e, ok := w.Get(id3); ok {
		fmt.Println("id", e.ID, "is a", e.Kind, "at", e.At)
	}

	w.Remove(id1)
	_, alive := w.Get(id1)
	fmt.Println("id 1 still in the world:", alive)
	id5, _ := w.Spawn(sim.Shrub, sim.Coord{X: 2, Y: 5})
	fmt.Println("replacement shrub's id:", id5)

$ go run ./cmd/worldd
shrub: 1 true
shrub: 2 true
walker: 3 true
walker on the pond: 0 false
population: 3
id 3 is a walker at {10 6}
id 3 is a walker at {10 5}
id 1 still in the world: false
replacement shrub's id: 4

The walker moved one row north and its ID did not flicker: position changed, identity held.

The mutation landed because the map stores *Entity, pointers. What Get returns is the entity in the world, not a souvenir copy, so e.At = ... writes through: the chapter 2 lesson about addresses, applied to a container.

The shrub that replaced the removed one got ID 4, not a recycled 1. Recycling would save nothing and cost everything: the moment the world keeps records, a reused ID makes old records ambiguous about who they meant. Retired numbers stay retired.

// internal/sim/world.go — add

// Render draws the ground with every entity drawn over its cell.
func (w *World) Render() string {
	rows := []byte(w.Ground.Render())
	for _, e := range w.ents {
		rows[e.At.Y*(w.Ground.W+1)+e.At.X] = e.Kind.Glyph()
	}
	return string(rows)
}

$ go run ./cmd/worldd   (map portion of the output)
############
#..........#
#...~~~~.o.#
#..~~~~~~..#
#...~~~~...#
#.o.......@#
#..........#
############

The W+1 is not a typo: the rendered ground is text, each row W glyphs plus a newline, so a row of the byte slice is one wider than a row of the grid.

The loop is your first iteration over a map: range visits every key-value pair. Here the visiting order cannot matter, since each entity stamps only its own cell.

Where order can matter, Go has an opinion, and it is about to become this chapter's mistake.

// internal/sim/world.go — the fix; add "slices" to the imports

// Roster returns every entity in the world, ordered by ID.
func (w *World) Roster() []*Entity {
	ids := make([]EntityID, 0, len(w.ents))
	for id := range w.ents {
		ids = append(ids, id)
	}
	slices.Sort(ids)
	out := make([]*Entity, 0, len(ids))
	for _, id := range ids {
		out = append(out, w.ents[id])
	}
	return out
}

$ go run ./cmd/worldd   (roster portion — now identical on every run)
roster:
  2 shrub at {9 2}
  3 walker at {10 5}
  4 shrub at {2 5}

range with one variable over a map yields keys only. slices.Sort, from the standard library's slices package, sorts them in place, ascending.

Twelve runs in a row now produce twelve identical rosters, and ID order means something: entities list in the order they entered the world, oldest first, because IDs were issued in that order and never shuffled.

Identity, handed out for one purpose, quietly pays for another.