Numbers With a Direction

// internal/vec/vec.go
// Package vec holds the one type everything in this world that moves is
// described with: two numbers kept together, with arithmetic of their own.
// Nothing in here knows what a tick is or what a pixel is.
package vec

// Vec2 is two numbers treated as one thing: X across and Y down,
// measured in whatever unit the caller is already using.
type Vec2 struct {
	X, Y float64
}

// Add is the two steps taken one after the other.
func (v Vec2) Add(w Vec2) Vec2 { return Vec2{v.X + w.X, v.Y + w.Y} }

// Sub is the step that gets from w to v: subtract the firsts, subtract
// the seconds.
func (v Vec2) Sub(w Vec2) Vec2 { return Vec2{v.X - w.X, v.Y - w.Y} }

// Scale multiplies both numbers by k, which changes how far the step
// goes and never which way it points.
func (v Vec2) Scale(k float64) Vec2 { return Vec2{v.X * k, v.Y * k} }

// cmd/drift/main.go — a bench for one vector at a time: no window, no
// world, just the arithmetic printed while it happens.
package main

import (
	"flag"
	"fmt"

	"theworld/internal/vec"
)

// walk prints where a dot stands after each of n ticks, given a start
// and one step it repeats.
func walk(start, step vec.Vec2, n int) {
	fmt.Printf("start (%.2f, %.2f)   step (%.2f, %.2f)\n", start.X, start.Y, step.X, step.Y)
	fmt.Println("  tick        x        y")
	at := start
	for t := 1; t <= n; t++ {
		at = at.Add(step)
		fmt.Printf("  %4d %8.2f %8.2f\n", t, at.X, at.Y)
	}
	jump := start.Add(step.Scale(float64(n)))
	fmt.Printf("  %-33s (%.2f, %.2f)\n",
		fmt.Sprintf("%d steps taken one at a time:", n), at.X, at.Y)
	fmt.Printf("  %-33s (%.2f, %.2f)\n",
		fmt.Sprintf("the step scaled by %d, added once:", n), jump.X, jump.Y)
}

func main() {
	show := flag.String("show", "add", "which demonstration to run")
	flag.Parse()

	start := vec.Vec2{X: 24, Y: 24}
	switch *show {
	case "add":
		walk(start, vec.Vec2{X: 3, Y: 4}, 10)
	}
}

$ go run ./cmd/drift -show add
start (24.00, 24.00)   step (3.00, 4.00)
  tick        x        y
     1    27.00    28.00
     2    30.00    32.00
     3    33.00    36.00
     4    36.00    40.00
     5    39.00    44.00
     6    42.00    48.00
     7    45.00    52.00
     8    48.00    56.00
     9    51.00    60.00
    10    54.00    64.00
  10 steps taken one at a time:     (54.00, 64.00)
  the step scaled by 10, added once: (54.00, 64.00)

Three choices in that file matter. The methods hang off a Vec2 value and not a pointer to one, and each returns a brand new Vec2 instead of editing the receiver, so a.Add(b) can never change a behind somebody's back. Two bodies handed the same velocity are then two independent facts, not one fact with two owners. The fields are float64 because a step of 2.4 pixels has to survive being stored; integers would round the useful part to zero.

Sub reads in the direction its comment states: target.Sub(here) is the movement from here to the target. That order matters because reversing it points the step back toward where the body already stands.

The last two lines are the table's summary and its first real claim. Ten additions of (3, 4) and one addition of (3, 4) scaled by ten produce the same pair of numbers, digit for digit, so an author who wants a body's position ten ticks from now can take either route to it. Both routes stay in whole numbers here, which is what makes the agreement exact.

// internal/vec/vec.go — one more method, and the import it needs
import "math"

// Len is how far the step actually travels: the straight-line diagonal
// of a rectangle X across and Y down.
func (v Vec2) Len() float64 { return math.Sqrt(v.X*v.X + v.Y*v.Y) }

// cmd/drift/main.go — a second demonstration, and its case in main

// lengths prints the length of each vector beside the arithmetic that
// produced it.
func lengths(vs []vec.Vec2) {
	fmt.Printf("  %-15s %9s %9s %9s %9s\n", "vector", "x·x", "y·y", "x·x + y·y", "length")
	for _, v := range vs {
		fmt.Printf("  (%6.2f,%6.2f) %9.4f %9.4f %9.4f %9.4f\n",
			v.X, v.Y, v.X*v.X, v.Y*v.Y, v.X*v.X+v.Y*v.Y, v.Len())
	}
}

//	case "len":
//		lengths([]vec.Vec2{
//			{X: 3, Y: 4}, {X: 6, Y: 8}, {X: 3, Y: 3},
//			{X: 5, Y: 0}, {X: 0.6, Y: 0.8}, {X: 30, Y: 40},
//		})

$ go run ./cmd/drift -show len
  vector                x·x       y·y x·x + y·y    length
  (  3.00,  4.00)    9.0000   16.0000   25.0000    5.0000
  (  6.00,  8.00)   36.0000   64.0000  100.0000   10.0000
  (  3.00,  3.00)    9.0000    9.0000   18.0000    4.2426
  (  5.00,  0.00)   25.0000    0.0000   25.0000    5.0000
  (  0.60,  0.80)    0.3600    0.6400    1.0000    1.0000
  ( 30.00, 40.00)  900.0000 1600.0000 2500.0000   50.0000

Every row of that table was predicted on paper before the machine printed it, including the ugly one: 4.2426 is the squeeze between 4.2 and 4.25 carried four decimal places further. Two rows are doing extra work. The fourth shows what happens when one of the numbers is zero, and the answer is the other number, since a rectangle with no height is just its own side; a length is never negative, and a step of (−5, 0) would print 5.0000 too. The last row closes the hole this section opened. Ten steps of length 5 is 50 pixels of travel, and the straight-line distance from start to finish, |(30, 40)|, is also 50, because the mote never turned. When a body's steps do turn, those two numbers part company: the road it walked gets longer while the gap between its first position and its last one does not.

// internal/vec/vec.go — the fourth operation

// Unit is the same direction at a length of exactly one. A step of no
// length points nowhere, so it is handed back unchanged rather than
// divided by zero.
func (v Vec2) Unit() Vec2 {
	n := v.Len()
	if n == 0 {
		return Vec2{}
	}
	return Vec2{v.X / n, v.Y / n}
}

// cmd/drift/main.go — aiming, and its case in main

// aim prints the step that carries a dot from one point toward another
// at a fixed speed, whichever way the target lies.
func aim(from vec.Vec2, targets []vec.Vec2, speed float64) {
	fmt.Printf("  from (%.2f, %.2f) at %.2f pixels a tick\n", from.X, from.Y, speed)
	fmt.Printf("  %-16s %-17s %9s  %-13s %8s %7s\n",
		"target", "offset", "distance", "step", "length", "ticks")
	for _, t := range targets {
		off := t.Sub(from)
		step := off.Unit().Scale(speed)
		fmt.Printf("  (%6.2f,%7.2f) (%7.2f,%7.2f) %9.2f  (%5.2f,%5.2f) %8.4f %7.2f\n",
			t.X, t.Y, off.X, off.Y, off.Len(), step.X, step.Y, step.Len(), off.Len()/speed)
	}
}

//	case "aim":
//		aim(start, []vec.Vec2{
//			{X: 144, Y: 114}, {X: 144, Y: 24}, {X: 24, Y: 114}, {X: 0, Y: 0},
//		}, 3)

$ go run ./cmd/drift -show aim
  from (24.00, 24.00) at 3.00 pixels a tick
  target           offset             distance  step            length   ticks
  (144.00, 114.00) ( 120.00,  90.00)    150.00  ( 2.40, 1.80)   3.0000   50.00
  (144.00,  24.00) ( 120.00,   0.00)    120.00  ( 3.00, 0.00)   3.0000   40.00
  ( 24.00, 114.00) (   0.00,  90.00)     90.00  ( 0.00, 3.00)   3.0000   30.00
  (  0.00,   0.00) ( -24.00, -24.00)     33.94  (-2.12,-2.12)   3.0000   11.31

One column is the point of the whole table: every step, in every direction, has length 3.0000. Follow the first row through by hand. The offset is (120, 90), whose length is √(14400 + 8100) = √22500 = 150. Dividing both numbers by 150 gives (0.8, 0.6), the hat from the interlude. Multiplying by 3 gives (2.40, 1.80), and 5.76 + 3.24 = 9, whose square root is 3 exactly. The last row is the same three operations on an offset that points up and to the left, and negative numbers need no special handling anywhere: a negative multiplied by itself is positive, so the length comes out 33.94 either way, and dividing negatives by a positive length keeps them negative, which is what pointing northwest means.

The zero case in Unit is not defensive clutter. A body sitting exactly where it wants to be produces an offset of (0, 0), whose length is 0, and dividing by 0 in floating-point arithmetic gives NaN, "not a number", which then poisons every sum it touches: a position added to NaN is NaN, and a mote whose position is NaN vanishes from the screen with no error printed anywhere. Returning the zero vector says the honest thing, which is that a step of no length has no direction to preserve.

// cmd/worldc/main.go — one vector a tick

// Mote is the first thing in this world that moves without the grid's
// permission: a position in world pixels, and the step added to it once
// every tick.
type Mote struct {
	Pos, Step vec.Vec2
}

// mote is the amber the dot is painted in, palette entry 15.
const mote render.Color = 0xFFF0BE35

// dot paints a four-pixel square centred on a position given in world
// pixels. A screen holds whole pixels only, so the position is rounded
// on the way in and the fraction stays in the mote.
func dot(b *render.Buffer, cam render.Camera, p vec.Vec2, c render.Color) {
	sx, sy := cam.ToScreen(int(math.Round(p.X)), int(math.Round(p.Y)))
	b.FillRect(render.Rect{X0: sx - 2, Y0: sy - 2, X1: sx + 2, Y1: sy + 2}, c)
}

// What the run reports: every tenth tick, plus the first and the last,
// and one pair of consecutive frames compared pixel by pixel.
const (
	driftEvery = 10
	driftMark  = 20
)

// drift holds seed's valley perfectly still and carries one mote across
// it, adding the same vector once per tick and hashing the frame at
// every tick boundary. Nothing else on the frame is allowed to move, so
// a hash that changes is the mote and only the mote.
func drift(a *art, cam render.Camera, seed uint64, ticks int, from, to vec.Vec2, speed float64, shot string) {
	g := sim.Generate(MapW, MapH, seed)
	kind := make([]render.Kind, MapW*MapH)
	for i := range kind {
		t, _ := g.At(sim.Coord{X: i % MapW, Y: i / MapW})
		kind[i] = kindOf(t)
	}
	tiles := render.Autotile(MapW, MapH, kind)

	off := to.Sub(from)
	m := Mote{Pos: from, Step: off.Unit().Scale(speed)}
	fmt.Printf("drift: (%.0f,%.0f) to (%.0f,%.0f) is (%.0f,%.0f), %.2f pixels; at %.2f a tick the step is (%.2f,%.2f)\n",
		from.X, from.Y, to.X, to.Y, off.X, off.Y, off.Len(), speed, m.Step.X, m.Step.Y)

	b := render.NewBuffer(cam.W, cam.H)
	var prev *render.Buffer
	fmt.Printf("  %4s %9s %9s %9s  %s\n", "tick", "x", "y", "travelled", "frame")
	for n := 1; n <= ticks; n++ {
		m.Pos = m.Pos.Add(m.Step) // the whole of this chapter, once a tick

		// Nothing on this frame moves but the mote: the ground was
		// tiled once, before the loop, and is drawn from the same tile
		// map every time.
		b.Fill(render.Void)
		render.DrawMapVia(b, tiles, a.tiles, cam)
		dot(b, cam, m.Pos, mote)
		h := b.Hash()

		if n == driftMark {
			prev = clone(b)
		} else if n == driftMark+1 && prev != nil {
			d := render.Diff(prev, b)
			fmt.Printf("  ticks %d and %d differ in %d of %d pixels, the first at %v\n",
				driftMark, n, d.Count, b.W*b.H, d.At)
		}
		if n%driftEvery != 0 && n != 1 && n != ticks {
			continue
		}
		fmt.Printf("  %4d %9.2f %9.2f %9.2f  %s\n",
			n, m.Pos.X, m.Pos.Y, m.Pos.Sub(from).Len(), h[:16])
		if shot != "" {
			if err := b.SavePNG(fmt.Sprintf("%s-t%03d.png", shot, n)); err != nil {
				die(err)
			}
		}
	}
	fmt.Printf("  the target was (%.2f,%.2f); the mote missed it by %e pixels\n",
		to.X, to.Y, m.Pos.Sub(to).Len())
}

// cmd/worldc/main.go — two flags, and the branch that takes them
	drifting := flag.Bool("drift", false, "carry one mote across a still valley, a vector a tick")
	speed := flag.Float64("speed", 3, "how many world pixels the mote covers in a tick")

	// ... after the art is loaded and the camera is placed:
	if *drifting {
		drift(a, cam, *seed, int(*ticks), vec.Vec2{X: 24, Y: 24}, vec.Vec2{X: 144, Y: 114},
			*speed, *shot)
		return
	}

$ go run ./cmd/worldc -drift -ticks 50
drift: (24,24) to (144,114) is (120,90), 150.00 pixels; at 3.00 a tick the step is (2.40,1.80)
  tick         x         y travelled  frame
     1     26.40     25.80      3.00  842c3957b3d8dd5f
    10     48.00     42.00     30.00  09f620c978221335
    20     72.00     60.00     60.00  31234d5faab466aa
  ticks 20 and 21 differ in 24 of 24576 pixels, the first at (70,58)
    30     96.00     78.00     90.00  81c0bb4536f11241
    40    120.00     96.00    120.00  3e7d20b626119ebb
    50    144.00    114.00    150.00  bd95bacaf123b4cc
  the target was (144.00,114.00); the mote missed it by 2.131628e-13 pixels

The amber square sets off from the soil inside the northwest rim, crosses the pond without noticing that it is water, and comes to rest on the rock of the southern rim on tick 50, the arrival the aiming table predicted from 150 pixels at 3 a tick. The travelled column climbs by exactly 30 every ten ticks, so the speed the code promised is the speed the mote kept the whole way. Nothing in this world has an opinion about the mote yet: the ground does not stop it, the water does not slow it, and the run would sail off the edge of the map if it kept going.

The comparison line is the proof the frozen ground bought. Between tick 20 and tick 21, 24 pixels of 24,576 changed, and 24 is exactly what the arithmetic predicts: the mote occupies sixteen pixels, it moved by (2.4, 1.8) which rounds to a shift of two across and two down, the old square and the new square overlap in four pixels, so twelve pixels were vacated and twelve were newly covered. The first disagreement is at (70, 58), the top-left corner of where the square used to be. A hash that changes and a pixel count that matches the prediction are two different kinds of evidence, and together they leave nowhere for a silent drawing bug to hide.