One Action a Tick

// internal/beast/act.go

// Act names one of the six things a creature may do with a tick. The
// order is written down once here and indexed by everything that reads
// the table, so it is fixed the way the five hit codes are fixed.
type Act uint8

const (
	Rest Act = iota
	Walk
	Sprint
	Left
	Right
	Bite
)

// Acts is how many entries the table has. A creature does exactly one
// of them per tick and there is no seventh thing it can do.
const Acts = 6

// Move is one row of the action table: what the action charges the
// store, how many ticks it occupies before the creature may choose
// again, and the test that says whether the ground permits it here this
// tick. Price takes a row and not a creature, because a price is a fact
// about a kind; Allow takes the creature, because permission is a fact
// about where that particular animal is standing.
type Move struct {
	Name  string
	Ticks int
	Price func(k Kind) float64
	Allow func(b *Beast, a Act, v *View) error
	Needs string // the precondition in words, for anything that prints the table
}

// Table is the six, in table order. Nothing outside this file decides
// what a creature can do.
var Table = [Acts]Move{
	Rest:   {Name: "rest", Ticks: 1, Price: nothing, Allow: always, Needs: "nothing"},
	Walk:   {Name: "walk", Ticks: 1, Price: amble, Allow: ground, Needs: "the cell ahead is not open water"},
	Sprint: {Name: "sprint", Ticks: 1, Price: dash, Allow: ground, Needs: "the cell ahead is not open water"},
	Left:   {Name: "turn left", Ticks: 1, Price: Kind.Wheel, Allow: always, Needs: "nothing"},
	Right:  {Name: "turn right", Ticks: 1, Price: Kind.Wheel, Allow: always, Needs: "nothing"},
	Bite:   {Name: "bite", Ticks: 2, Price: Kind.Chew, Allow: mouth, Needs: "tissue standing inside Reach"},
}

The constants run 0 to 5 through iota and the order is a fact other code indexes by, so it is settled here and never re-sorted for tidiness, the same way the five hit codes were settled when the rays learned to report what they met. Acts is the width of the table and Table is an array of exactly that many entries, so a seventh action cannot be added by accident: it fails to compile. Kind.Wheel and Kind.Chew in the price column are methods used as plain functions, which is what a method name without a receiver in front of it means in Go, and it is how a price written as a method on a row ends up sitting in a table of functions.

// internal/beast/act.go, continued

// The three prices that are not one-line methods on Kind. A walk asks
// for half the top speed and a sprint for all of it, so both are the
// travel charge from the movement chapter read at a stated speed.
func nothing(k Kind) float64 { return 0 }
func amble(k Kind) float64   { return k.Travel(k.Top / 2) }
func dash(k Kind) float64    { return k.Travel(k.Top) }

// Wheel is what one turn action costs. Getting the whole body round
// once is priced at one tick of the hardest thing the legs can do,
// because it is the legs that do it; one turn action covers Swing of a
// whole turn and pays Swing of that bill.
func (k Kind) Wheel() float64 { return k.Swing * k.Travel(k.Top) }

// Chew is what one bite costs to take, as opposed to what it is worth
// once it is inside. The mouth carries Bite grams over Reach cells in
// one tick, and this world prices that the way it prices every other
// movement: the mass moved, times the square of the speed it moved at,
// at the row's price for a unit of work.
func (k Kind) Chew() float64 { return k.Work * k.Bite * k.Reach * k.Reach }

// Turn is how far one turn action swings the heading, in radians:
// Swing of a whole turn.
func (k Kind) Turn() float64 { return k.Swing * 2 * math.Pi }

Swing does two jobs and they are the same job seen twice. It says how far one turn action swings the heading, a twelfth of a whole turn for this row, and it says what share of a whole turn's bill that action pays. Getting the whole body round once is priced at one tick of the hardest thing the legs can do, because it is the legs that do it, so a twelfth of a turn costs a twelfth of a sprinting tick.

Reach does the same trick. It is a distance the mouth covers, and pricing that distance needs no new law: the mouth carries Bite grams over Reach cells inside one tick, which is a mass moved at a speed, and this world already knows what a mass moved at a speed costs. The grams are the mouthful and not the body, because a browser reaching for a leaf is not throwing forty grams of itself at it.

// internal/beast/act.go, continued

// The three rules an action can be refused by. They are values and not
// strings so a caller can test which one it hit without reading
// English: errors.Is(err, beast.ErrBroke) is a question about the
// store, whatever the sentence around it says.
var (
	// ErrBroke is the store refusing to pay the price on the table.
	ErrBroke = errors.New("the store cannot pay for it")
	// ErrNoGround is the ground refusing to carry a step.
	ErrNoGround = errors.New("the cell ahead is open water or off the grid")
	// ErrNoReach is a mouth with nothing standing inside its reach.
	ErrNoReach = errors.New("no standing tissue inside reach")
)

// Refusal is one action the check would not let happen. It is an error
// value and not a false, because four things have to reach the log and
// a bool carries none of them: who was refused, what they tried, which
// rule stopped them, and the cell the rule was about. Want and Got are
// the two numbers that rule compared, in whatever unit it works in;
// they are both nothing for a rule that compares no numbers.
type Refusal struct {
	Who  sim.EntityID // the creature the check refused
	Act  Act          // what it tried to do
	Why  error        // ErrBroke, ErrNoGround or ErrNoReach
	At   sim.Coord    // the cell the rule was about
	Want float64      // what the rule asked for
	Got  float64      // what it found there
}

// Error is the one-line sentence the log carries.
func (r *Refusal) Error() string {
	return fmt.Sprintf("creature %d at %d,%d cannot %s: %v",
		r.Who, r.At.X, r.At.Y, r.Act, r.Why)
}

// Unwrap hands out the rule underneath, so errors.Is answers questions
// about which rule fired without anything unpacking the struct.
func (r *Refusal) Unwrap() error { return r.Why }

// Legal is the check, in the order it asks. The store first, because it
// is one subtraction and every one of the six is subject to it; then
// the entry's own test, which is the only part that has to look at the
// world. It hands back nil when the creature may take the action and a
// *Refusal when it may not.
//
// The upkeep is not in this check. A body is charged for standing there
// whatever it does with the tick, so a store that cannot cover the
// upkeep is not something choosing a cheaper action can mend.
func (b *Beast) Legal(a Act, v *View) error {
	m := Table[a]
	if p := m.Price(*b.Kind); p > b.Store {
		return &Refusal{Who: b.ID, Act: a, Why: ErrBroke, At: b.Cell(), Want: p, Got: b.Store}
	}
	return m.Allow(b, a, v)
}

The three sentinels are values and not strings, so a caller asks which rule fired by comparing values: errors.Is(err, beast.ErrBroke) is a question about the store and stays true however the sentence around it is reworded. Refusal wraps one of them and adds the four things the log actually wants, and its Unwrap method is what lets errors.Is see through the struct to the rule inside. So one returned value answers three different questions: print it and you get a sentence, test it with errors.Is and you get the rule, unpack it with errors.As and you get the numbers.

Legal asks the store first on purpose. It is one subtraction, it applies to all six entries, and it needs nothing from the world; the entry's own test is the half that has to go and look. The upkeep is deliberately not part of it. A body is charged for standing there whatever it does, so a store that cannot cover the upkeep is not a situation choosing a cheaper action can mend, and refusing every action on those grounds would only mean the creature could not even rest.

// internal/beast/act.go, continued

// always is the test for an action nothing about the ground can forbid.
func always(b *Beast, a Act, v *View) error { return nil }

// ground refuses a step that would put weight on open water or over the
// rim. It tests the cell ahead and not the cell underfoot, because the
// cell underfoot has already been walked on.
func ground(b *Beast, a Act, v *View) error {
	c := b.Ahead()
	if !v.Valley.Bed.In(c) || v.Valley.Bed.Kind(c) == sim.Water {
		return &Refusal{Who: b.ID, Act: a, Why: ErrNoGround, At: c}
	}
	return nil
}

// mouth refuses a bite with nothing to bite. The two numbers on the
// refusal are the grams the mouth wanted and the grams the richest cell
// inside its reach was holding.
func mouth(b *Beast, a Act, v *View) error {
	st, grams := b.Meal(v)
	if st == nil {
		return &Refusal{Who: b.ID, Act: a, Why: ErrNoReach, At: b.Cell(),
			Want: b.Kind.Bite, Got: grams}
	}
	return nil
}

// Ahead is the cell one cell along the heading from where the body is
// standing: the ground a step would put weight on.
func (b *Beast) Ahead() sim.Coord {
	p := b.Pos.Scale(1.0 / terra.Tile)
	return sim.Coord{
		X: int(math.Floor(p.X + math.Cos(b.Face))),
		Y: int(math.Floor(p.Y + math.Sin(b.Face))),
	}
}

// Meal is the stand this creature's mouth can get to and the grams
// standing on it: of every cell inside Reach, the one holding the most
// tissue. Reach is counted in cells crossed in the worse of the two
// directions, so a reach of one cell is the cell underfoot and the
// eight touching it, and the diagonal neighbours are as close to a
// mouth as the orthogonal ones. Nothing about the answer depends on
// which way the creature is facing: a mouth on a body a cell wide can
// reach round it.
//
// Ties go to the first cell in row order, so two cells holding exactly
// the same grams are settled the same way on every machine.
func (b *Beast) Meal(v *View) (*terra.Stand, float64) {
	n := int(b.Kind.Reach)
	here := b.Cell()
	var best *terra.Stand
	most := 0.0
	for dy := -n; dy <= n; dy++ {
		for dx := -n; dx <= n; dx++ {
			st, ok := v.Stand(here.Offset(dx, dy))
			if !ok || st.Plant.Mass <= most {
				continue
			}
			best, most = st, st.Plant.Mass
		}
	}
	return best, most
}

Ahead is the body's position in cells plus one cell along the heading, floored. Note the 1.0 in the division. Writing 1 / terra.Tile with two whole numbers is a constant division that Go does in whole numbers, and it comes out as nothing at all, so every creature reports the cell ahead of the top left corner of the valley and no test fails anywhere.

Meal reads Reach as a ring rather than a straight line. A reach of one cell is the cell underfoot and the eight touching it, so a mouth does not have to be pointed at its dinner and a plant on the diagonal is no further away than a plant to the east. That choice is what makes the rule at the end of this chapter safe: a ray sample sitting less than one cell out has landed either underfoot or in one of those eight, so a bite asked for on the strength of a near sample is a bite the check allows. It also picks the richest cell inside the ring, which costs nine map lookups and settles ties by row order, so two identical cells are resolved the same way on every machine that ever runs it.

// internal/beast/body.go

type Beast struct {
	ID    sim.EntityID // what the log calls it, for as long as it lives
	Name  string
	Kind  *Kind
	Store float64 // energy units in the store right now
	Born  int     // the tick it was born on
	Ate   float64 // grams it has taken off the valley since it was born
	Dead  bool    // its store reached nothing and it stopped
	Last  Ledger

	field.Body         // where it is and how fast, in world pixels
	Face       float64 // the heading its eyes look along, radians clockwise of east

	// The action under way and the ticks it still owes. While Owed is
	// above nothing the creature is not asked what it wants to do: the
	// action it is part-way through takes the tick.
	Busy Act
	Owed int

	// Greedy is the bite as it was first written: a whole mouthful
	// taken whether or not the plant has one to give. Blind is the
	// caster without the line that lets a ray leave the cell it starts
	// on. Both are kept behind flags so the failures can be run instead
	// of described, and both are false in every creature this book
	// ships.
	Greedy bool
	Blind  bool

	// Unpaid is the bite with the repayment switched off: the grams
	// still leave the plant, but the minerals they were holding go
	// nowhere instead of landing on the cell that lent them. It is
	// named for the ground's books and not for the animal, because a
	// creature carrying it eats exactly as it always did and the whole
	// of the loss is the bed's. It is kept behind a flag so what that
	// missing line costs can be run instead of described, and it is
	// false in every creature this book ships.
	Unpaid bool
}

// internal/beast/act.go, continued

// Tag hands out the identities a roster of creatures is known by: one
// each, in founding order, never reused, skipping anything already
// carrying one. It hands back the next free identity so a population
// that grows later goes on counting from where this one stopped.
//
// Identities are handed out here and not in Spawn because being
// somebody is a fact about a population, not about a body: two
// creatures made by two different benches would both be number one
// until something put them in the same valley.
func Tag(herd []*Beast, next sim.EntityID) sim.EntityID {
	for _, b := range herd {
		if b.ID == 0 {
			b.ID = next
			next++
		}
	}
	return next
}

ID is the same sim.EntityID the world has handed out to everything it has ever needed to name: a number given once, in order, never reused after a death. It is handed out by Tag and not by Spawn, because being somebody is a fact about a population and not about a body. Two creatures stamped by two different benches would both be number one until something put them in the same valley, and Tag is that something.

// internal/beast/act.go, continued

// Tally is one creature's tick under the table, in the order the
// numbers are worked out.
type Tally struct {
	Act    Act     // what the creature actually did with the tick
	Held   bool    // the tick went to an action already under way
	Grams  float64 // grams taken off a stand
	Gained float64 // energy units those grams were worth
	Spilt  float64 // energy units of that the store had no room for
	Price  float64 // energy units the action itself charged
	Rent   float64 // energy units the standing body charged
	Haul   float64 // energy units the tick's actual travel charged
	Left   float64 // what is in the store when the tick closes
}

// Do is one creature's whole tick: the action it was asked for, if the
// check allows it and the creature is free to choose, and then the same
// Step every creature takes whatever it did.
//
// Three things happen in a fixed order, and the order is the design. A
// creature part-way through an action it took earlier is not asked
// again: the action under way gets the tick and the choice is dropped.
// A choice the check refuses costs the creature its tick and nothing
// else, and the refusal comes back as an error so the caller can put it
// in the log instead of losing it. And every path ends in Step, so the
// movement charge is not something an action can dodge: a creature that
// rests while still moving is charged for the moving.
func (b *Beast) Do(a Act, v *View) (Tally, error) {
	var t Tally
	var err error
	if b.Owed > 0 {
		b.Owed--
		t = Tally{Act: b.Busy, Held: true}
		b.aim(0)
	} else {
		if err = b.Legal(a, v); err != nil {
			a = Rest
		}
		t = b.apply(a, v)
		b.Busy, b.Owed = a, Table[a].Ticks-1
	}
	toll := b.Step()
	t.Rent, t.Haul = toll.Rent, toll.Haul
	t.Left = b.Store
	return t, err
}

Every path through Do ends in Step, and that is the load bearing line. Step is the movement chapter's: it moves the body by whatever went into the accumulator and then charges the store for being a body and for moving one, at the speed the body actually reached. Putting it at the bottom of every branch means the travel charge is not something an action can dodge. A creature that chooses to rest while it is still gliding is charged for the gliding, which is the same fact the movement chapter printed when a walker's store emptied and the drift went on being charged past nothing.

The refusal branch is three lines and carries the boundary. The action becomes Rest, the tick proceeds, and the error is carried out of the function beside a perfectly valid Tally. Nothing is rolled back, because nothing was done. The creature really did spend the tick, and the caller really does get told why.

// internal/beast/act.go, continued

// apply is the effect of one action and the charge that goes with it.
// The two travelling entries are the exception: the table quotes what
// they will cost at the speed they ask for, and Step charges the speed
// the body actually reached, which is never more than the speed it was
// asked for. Everything else is charged here, because nothing else in
// the tick would.
func (b *Beast) apply(a Act, v *View) Tally {
	k := b.Kind
	t := Tally{Act: a}
	switch a {
	case Walk:
		b.aim(k.Top / 2)
	case Sprint:
		b.aim(k.Top)
	case Left:
		t.Price = k.Wheel()
		b.Face = wrap(b.Face - k.Turn())
		b.aim(0)
	case Right:
		t.Price = k.Wheel()
		b.Face = wrap(b.Face + k.Turn())
		b.aim(0)
	case Bite:
		t.Price = k.Chew()
		if st, _ := b.Meal(v); st != nil {
			t.Grams = b.Graze(st, v.Valley.Bed)
			t.Gained = t.Grams * k.Convert
			b.Store += t.Gained
			if b.Store > k.Full {
				t.Spilt = b.Store - k.Full
				b.Store = k.Full
			}
		}
		b.aim(0)
	default:
		b.aim(0)
	}
	b.Store -= t.Price
	return t
}

// aim puts one tick of legs into the accumulator: the force that steers
// the body toward travelling at speed cells a tick along the heading.
// A speed of nothing is a real request and the one four of the six
// entries make: it asks the legs to stop the body, which takes them the
// same handful of ticks that starting it did.
func (b *Beast) aim(speed float64) {
	want := field.Vec2{
		X: math.Cos(b.Face) * speed * terra.Tile,
		Y: math.Sin(b.Face) * speed * terra.Tile,
	}
	b.Body.ApplyForce(b.Push(want))
}

Four of the six ask the legs for no velocity at all, and that is a real request rather than an absence of one. Nothing in this world slows a body down by itself, so a creature that stopped asking to travel would carry on travelling for ever; asking for zero puts a braking force into the accumulator through the same steering the walking entries use, and the body sheds its speed over the same handful of ticks it took to build it.

The two travelling entries charge nothing in apply, and that is not an oversight. Their price on the table is a quote, used by the check to ask whether the store could stand the tick; the money actually leaves in Step, priced off the speed the body reached. A creature that asks for a walk from a standstill does not reach a walk on the first tick and is not charged for one. The quote is an upper bound and the charge is the truth.

The bite is the only entry that moves grams, and it moves them through Graze, unchanged since the chapter that wrote it: no bite is bigger than the plant it comes off, the grams leave the stand's standing mass, and the store has a ceiling that anything past it spills over. What is new is the second argument. The benches that priced a bite had one plant and no valley under it, so they passed nil and there was no ground for the minerals in a mouthful to go back to. Here there is: v.Valley.Bed is the real one, and the nutrient the eaten tissue was holding lands on the cell the plant is standing on as the bite is taken.

// internal/beast/act.go, continued

// Mind is anything that can look at one reading of the world and name
// one of the six. Twenty-four numbers in, one action out, and nothing
// else crosses: a Mind cannot see the valley, cannot reach a plant, and
// cannot spend anything. Everything that ever drives a creature in this
// world goes through this one method.
type Mind interface {
	Pick(row *Senses) Act
}

// Hunt is the rule this chapter drives its creatures with, written out
// by hand. Find the ray that stopped nearest on a plant. If it is off
// to one side, turn that way. If it is ahead and the plant is further
// off than Near, walk. Otherwise bite.
//
// Near is in cells, and half a cell is the value that makes the bite
// safe rather than lucky: a sample sitting less than one cell from the
// body is inside the cell underfoot or one of the eight touching it,
// and every one of those is inside a reach of one cell. A bite this
// rule asks for is a bite the check allows.
//
// Front is how many rays count as straight ahead, and it is three and
// not one for a reason that is arithmetic rather than taste. The rays
// are Gap apart and one turn action swings the heading by Swing of a
// whole turn, which for this row is two rays' worth. A target one ray
// left of the middle would be turned to one ray right of it, then back
// again, for as long as the creature lived. Aiming can only ever be as
// fine as the coarser of the two steps.
//
// Sight is the span the row's ray distances were divided by, and it is
// on the rule because a Mind is handed shares of a span and never the
// span itself. A rule that wants to think in cells has to be told what
// a whole one was.
//
// Blind is what to do on a tick where no ray found a plant at all. A
// Mind that reads nothing but the row cannot invent a direction, and
// the one this package ships turns right until something shows up;
// anything better belongs to the caller, which is why it is a field.
type Hunt struct {
	Near  float64
	Sight float64
	Front int
	Blind Mind
}

// Pick reads the fan out of the row and returns one of the six.
func (h Hunt) Pick(row *Senses) Act {
	mid, half := (Fan-1)/2, h.Front/2
	best, near := -1, math.Inf(1)
	for i := 0; i < Fan; i++ {
		if row[Eye(i)+1] != Worth[Plant] {
			continue
		}
		if d := row[Eye(i)]; d < near {
			best, near = i, d
		}
	}
	switch {
	case best < 0:
		if h.Blind != nil {
			return h.Blind.Pick(row)
		}
		return Right
	case best < mid-half:
		return Left
	case best > mid+half:
		return Right
	case near*h.Sight <= h.Near:
		return Bite
	}
	return Walk
}

Pick reads eighteen of the twenty-four slots and ignores the rest. It looks for the ray whose code says plant, takes the nearest of them, and answers with a turn, a walk or a bite. It cannot see the valley, cannot follow a pointer to a plant, and cannot spend anything, because the only argument it has is an array of numbers.

Front is the detail that took a run to find. The rays sit fifteen degrees apart and one turn action swings the heading thirty, so a turn moves the target two rays. A rule that insisted on the middle ray would push a target one ray left over to one ray right, then back, for as long as the creature lived. Aiming is only ever as fine as the coarser of the two steps, so the middle three rays count as ahead.