world

The world

Three coordinate spaces — grid, world, screen — and every operation here is only correct because it knows which one it is in. Game code never converts between them by hand; every conversion is a named function that takes an output parameter.

Two facts that decide most of what follows:

• Tile lookup floors, never rounds. Rounding snaps to the nearest lattice vertex and picks the wrong tile for three quarters of every diamond.
• Elevation lives on grid vertices, not tile centers. Adjacent tiles therefore share their corner values exactly and cannot leave a seam — and once z exists the projection is no longer invertible, so picking has to be terrain-aware. That is the biggest trap in this skill and it has its own section.

Ground, and height on it

import { TileGrid, footprintBase, heightAt, slopeAt, tileSourceOf } from '@latticekit/iso';
import type { Footprint, HeightField } from '@latticekit/iso';
import { fbm2 } from '@latticekit/core';

const W = 96;
const H = 96;

// One value per grid VERTEX, so the grid is one wider than the tile map in each axis.
const heights = new TileGrid(W + 1, H + 1);
heights.fillFrom((gx, gy) => Math.max(0, fbm2(1234, gx * 0.04, gy * 0.04, 4) * 8));

/** `stepPx` is world pixels per height unit — the one conversion between the game's units
 *  and the projection's. 8 means a ridge of 5 units stands 40 world pixels proud. */
const land: HeightField = { heights, stepPx: 8 };

/** The tallest ground on the map, in world pixels. Camera framing and the terrain cull both
 *  need it, and both are silently wrong without it. Compute it once, at generation. */
export const MAX_HEIGHT_PX = 8 * 8;

export function groundUnder(f: Footprint): number {
  // The MAXIMUM vertex height under the footprint, not the mean: a building resting on the mean
  // of a slope has one corner buried in the hill and one floating.
  return footprintBase(land, f);
}

export function walkCost(gx: number, gy: number): number {
  return 1 + slopeAt(land, gx, gy) * 2;      // steeper ground costs more to cross
}

export function surfaceAt(gx: number, gy: number): number {
  return heightAt(land, gx, gy);             // bilinear, in world pixels
}

/** An unbounded world: a function is defined everywhere, so it has no edge and costs no
 *  memory. Everything is a pure function of (seed, gx, gy) — see the warning below. */
export const endless: HeightField = {
  heights: tileSourceOf((gx, gy) => Math.max(0, fbm2(1234, gx * 0.04, gy * 0.04, 4) * 8)),
  stepPx: 8,
};