GridPoint interface ↳ src/projection.ts:39

interface GridPoint {

2 members

gx: number

gy: number

Tile type ↳ src/projection.ts:51

type Tile = GridPoint

Rect interface ↳ src/projection.ts:75

interface Rect {

4 members

minX: number

minY: number

maxX: number

maxY: number

TileRange interface ↳ src/projection.ts:89

interface TileRange {

4 members

gx0: number

gy0: number

gx1: number

gy1: number

TILE_W const ↳ src/projection.ts:111

const TILE_W = 64

TILE_H const ↳ src/projection.ts:115

const TILE_H = 32

HALF_W const ↳ src/projection.ts:119

const HALF_W = 32

HALF_H const ↳ src/projection.ts:122

const HALF_H = 16

gridToWorldX function ↳ src/projection.ts:145

function gridToWorldX(gx: number, gy: number): number

gridToWorldY function ↳ src/projection.ts:151

function gridToWorldY(gx: number, gy: number): number

gridToWorld function ↳ src/projection.ts:157

function gridToWorld(gx: number, gy: number, out: Vec2): Vec2

worldToGridX function ↳ src/projection.ts:172

function worldToGridX(wx: number, wy: number): number

worldToGridY function ↳ src/projection.ts:177

function worldToGridY(wx: number, wy: number): number

worldToGrid function ↳ src/projection.ts:183

function worldToGrid(wx: number, wy: number, out: GridPoint): GridPoint

worldToTile function ↳ src/projection.ts:204

function worldToTile(wx: number, wy: number, out: Tile): Tile

depthOf function ↳ src/projection.ts:227

function depthOf(gx: number, gy: number, w?: number, d?: number): number

isEdgeOn function ↳ src/projection.ts:257

function isEdgeOn(gx0: number, gy0: number, gx1: number, gy1: number): boolean

tileDiamond function ↳ src/projection.ts:277

function tileDiamond(gx: number, gy: number, out: Float64Array): Float64Array

Parameters

footprintBounds function ↳ src/projection.ts:306

function footprintBounds(gx: number, gy: number, w: number, d: number, heightPx: number, out: Rect): Rect

Parameters

tileBounds function ↳ src/projection.ts:341

function tileBounds(gx: number, gy: number, w: number, d: number, heightPx: number, out: Rect): Rect

Parameters

rectSet function ↳ src/projection.ts:355

function rectSet(out: Rect, minX: number, minY: number, maxX: number, maxY: number): Rect

rectFromSize function ↳ src/projection.ts:365

function rectFromSize(out: Rect, x: number, y: number, w: number, h: number): Rect

rectWidth function ↳ src/projection.ts:375

function rectWidth(r: Readonly<Rect>): number

rectHeight function ↳ src/projection.ts:380

function rectHeight(r: Readonly<Rect>): number

rectCenterX function ↳ src/projection.ts:388

function rectCenterX(r: Readonly<Rect>): number

rectCenterY function ↳ src/projection.ts:393

function rectCenterY(r: Readonly<Rect>): number

rectContains function ↳ src/projection.ts:399

function rectContains(r: Readonly<Rect>, x: number, y: number): boolean

rectIntersects function ↳ src/projection.ts:406

function rectIntersects(a: Readonly<Rect>, b: Readonly<Rect>): boolean

rectExpand function ↳ src/projection.ts:413

function rectExpand(out: Rect, margin: number): Rect

rectUnion function ↳ src/projection.ts:424

function rectUnion(out: Rect, a: Readonly<Rect>, b: Readonly<Rect>): Rect

rectMakeEmpty function ↳ src/projection.ts:445

function rectMakeEmpty(out: Rect): Rect

rectIsEmpty function ↳ src/projection.ts:457

function rectIsEmpty(r: Readonly<Rect>): boolean

CameraOptions interface ↳ src/camera.ts:69

interface CameraOptions {

5 members

readonly minZoom?: number

How far out you may pull. Below this the art stops being readable and the depth sort starts costing more than the pixels are worth. Default 0.5.

readonly maxZoom?: number

How far in you may push. Default 4; vector art costs nothing to magnify.

readonly zoom?: number

Starting zoom. Default 1. Clamped into [minZoom, maxZoom] at construction rather than rejected, because a saved zoom outliving a change to the limits is a migration problem and not a reason to refuse to open the game — and Camera.setZoomLimits applies that same rule for the rest of the camera's life.

readonly bounds?: Readonly<Rect>

The world rectangle the player is allowed to look at. Default ±DEFAULT_EXTENT.

Copied at construction, so a caller may reuse the rectangle it passed in — this is the one place in the package where an input rectangle is retained, and retaining the caller's object would make every later rectSet on it move the camera's world.

readonly keepVisible?: number

The fraction of the viewport that must still show bounds on each axis after any gesture. Default 0.35.

0 lets a player strand themselves on empty ground with nothing to tap and no idea which way is back; 1 requires the viewport to lie entirely inside the bounds, which pins the map rigidly and feels stuck — and, on a map smaller than the viewport, is unsatisfiable, which is the case Camera.clamp has to detect rather than hand to a min > max comparison.

Camera interface ↳ src/camera.ts:105

interface Camera {

29 members

readonly x: number

World x at the center of the viewport. Read-only, and not merely by convention — see the module header for why the field is unavailable rather than discouraged.

readonly y: number

World y at the center of the viewport. See Camera.x.

readonly zoom: number

World pixels per CSS pixel. Moved only by Camera.zoomAt, so the pointer anchor cannot be skipped.

readonly viewW: number

Viewport width in CSS pixels — never device pixels, never a canvas.

readonly viewH: number

Viewport height in CSS pixels. See Camera.viewW.

readonly bounds: Readonly<Rect>

The reachable world rectangle. The camera's own copy; mutating it does nothing until Camera.setBounds is called, which is the honest half of that trade.

readonly minZoom: number

The zoom-out limit in force — CameraOptions.minZoom, or the default 0.5, or whatever Camera.setZoomLimits last set.

It exists so that nobody has to keep a second copy. A settings panel that draws the zoom slider needs the range the slider is allowed to span; a "zoom out" button needs to know whether it should be disabled; a save file needs to record the policy it was played under. Each of those, given no reader, keeps its own copy of a number this object already holds — and the copies drift the first time anything else moves the limits.

readonly maxZoom: number

The zoom-in limit in force. See Camera.minZoom.

readonly keepVisible: number

The fraction of the viewport that must still show Camera.bounds after any gesture — CameraOptions.keepVisible, or the default 0.35, or whatever Camera.setKeepVisible last set. Read it to show the clamp you are subject to: it is the one number that explains why a pan stopped where it did.

resize(viewW: number, viewH: number): void

Re-clamps against a new viewport size. Call it on every viewport change including an orientation flip: the clamp depends on the half-viewport in world units, so a camera that is not told the window shrank keeps letting the player look outside the map.

Throws

RangeError if either dimension is not a finite number greater than zero.

setBounds(bounds: Readonly<Rect>): void

Replace the reachable rectangle — the island grew, the level loaded — and re-clamp at once, so no frame is ever drawn against bounds the camera has not been checked against.

setZoomLimits(minZoom: number, maxZoom: number): void

Replace the zoom limits — a settings change, a difficulty tier, an accessibility option — and re-clamp at once.

Why this exists beside a zoom that is deliberately unassignable. They are not the same kind of thing. zoom is a position: it moves under a pointer, and the rule zoomAt enforces is that no path may move it without deciding what stays put — origin- anchored zoom is the single most common reason a tile-game camera feels broken, and a set zoom accessor is precisely a path that decides nothing. The limits are policy: they say what the player is allowed to do, they are set by configuration rather than by a gesture, and this method does decide what stays put — the viewport center, exactly as fitBounds decides on the rectangle's center. The invariant was never "zoom is immutable"; it was "nothing changes zoom without naming an anchor", and this names one.

The escape it opens is real and worth stating rather than hiding: setZoomLimits(2, 2) does force zoom to 2 with no pointer involved. It also freezes the zoom permanently, which is a loud symptom and useless as a way to sneak a gesture through. The rule makes the common mistake unrepresentable; it is not a security boundary and was never sold as one.

If the current zoom falls outside the new range it is clamped on the spot, and that can move the view. Raising minZoom past the current zoom pushes the camera in; lowering maxZoom below it pulls the camera out; and either can then move x/y, because the half-viewport in world units changed and the Camera.keepVisible clamp is computed from it. So a minZoom slider dragged live rescales the world under the finger. That is the correct behavior — the alternative is a camera sitting outside its own declared limits until the player's next wheel notch snaps it, at a moment they did not cause and cannot connect to anything — but a panel that does not want the view moving mid-drag should commit on release. It is the same rule CameraOptions.zoom already applies to a stale saved zoom at construction, applied for the rest of the camera's life.

Both limits are taken together, not one at a time, because minZoom <= maxZoom is a relation between them: a single-field setter would have to either reject the halfway state of a slider drag that crosses the other limit, or silently reorder the pair. Taking both makes the invariant a thing the caller states and this method checks.

Throws

RangeError if either limit is not a finite number greater than zero, or if minZoom > maxZoom. The message shape is createCamera's, with this method's name.

setKeepVisible(keepVisible: number): void

Replace the fraction of the viewport that must keep showing Camera.bounds, and re-clamp at once.

Re-clamping is the point, and it means this call can move the camera. Raising the fraction while the player is near a map edge pulls them back toward it in the same statement — with nothing in flight, no animation, no next frame required. Deferring instead would leave a camera showing a view its own policy forbids until the next pan, which is the failure Camera.setBounds already refuses for the same reason.

Throws

RangeError if keepVisible is outside [0, 1] — NaN included, which is what an unparsed slider value arrives as and which would otherwise turn the clamp into NaN on both axes and put the camera nowhere.

toScreenX(wx: number): number

world → screen x. Takes wx alone, because screen x depends on world x alone.

This is the form that writes into a Float64Array: pen[i] = cam.toScreenX(wx); pen[i + 1] = cam.toScreenY(wy); — no intermediate object at any point. A caller projecting the eight corners of a box projects four x values, not eight, which is the whole reason the two axes are separate functions.

toScreenY(wy: number): number

world → screen y. See Camera.toScreenX.

toScreen(wx: number, wy: number, out: Vec2): Vec2

world → screen, both axes, into a caller-owned Vec2. Returns out so calls chain.

normalizedX(wx: number): number

Where a world x sits across the viewport: -1 at the left edge, 0 at the center, +1 at the right, continuing past them rather than clamping.

The third member of the projection family, and it exists because @latticekit/audio needs it and may not depend on this package: a sound's stereo pan is the normalizedX of the thing that made it. Unclamped on purpose — how far a pan may go is a mixing policy (audio caps at ±0.6, because full-width panning is unpleasant on headphones and inaudible on a phone speaker) and a policy does not belong in a projection.

There is no normalizedY. Stereo has one axis.

toWorldX(sx: number): number

screen → world x. The exact inverse of Camera.toScreenX.

toWorldY(sy: number): number

screen → world y.

toWorld(sx: number, sy: number, out: Vec2): Vec2

screen → world, both axes, into a caller-owned Vec2.

panByScreen(dxScreen: number, dyScreen: number): void

Pan by a screen-space delta — a drag.

Divided by zoom internally so the world tracks the finger exactly at any scale. Multiplying instead of dividing is the bug where a zoomed-in map slides at a crawl and a zoomed-out one bolts, and it looks like a tuning problem rather than a sign error.

zoomAt(factor: number, sx: number, sy: number): void

Zoom, keeping the world point under (sx, sy) pinned to that screen pixel.

centerOn(wx: number, wy: number): void

Put a world point at the center of the viewport immediately, then clamp.

fitBounds(worldRect: Readonly<Rect>, marginPx?: number): void

Frame a world rectangle: the zoom that makes it fit, then the center that shows it.

The first thing every game does, and the one thing Camera.zoomAt cannot do. zoomAt takes a factor and a required anchor because that is what a wheel notch and a pinch are. Framing a generated world is the other problem: the caller knows the rectangle it wants on screen and does not know — must not have to compute — the ratio between that and the zoom it happens to be at. Written against zoomAt it comes out as zoomAt(want / camera.zoom, viewW / 2, viewH / 2), and that division is this method's absence rather than anyone's style.

Content height enters through the rectangle, and there is nowhere else it can. A rectangle is the whole of what this method knows, so a caller that frames tileBounds(0, 0, w, d, 0, out) frames the ground plane and a 440-pixel summit lands off the top of the screen on the first frame. Pass the map's tallest elevation as tileBounds's heightPx — it extends minY upward, which is exactly the extra span the fit has to pay for — or union in the boxes of whatever stands on the map. There is deliberately no separate height parameter: two ways to say the same thing is how one of them gets passed twice.

The final center is the rectangle's center after the bounds clamp, so on a map smaller than keepVisible demands the two differ, and the clamp wins. Frame first, then read Camera.x if you need to know where it settled.

Zoom is written directly here, and that is not a hole in the anchoring rule. zoomAt exists so that a gesture cannot skip pinning the world point under the pointer; a fit has no pointer and pins the rectangle's center instead. The invariant is "no path changes zoom without deciding what stays put", and this path decides.

Throws

RangeError if any edge is not finite — including the rectMakeEmpty state, which is what an accumulator loop that unioned nothing leaves behind — if the rectangle is inverted, or if marginPx is negative or not finite.

centerOnTile(gx: number, gy: number): void

Put a tile at the center. The form callers actually want after loading a save, and the one that stops every game writing gridToWorld into a scratch vector to do it.

clamp(): void

Re-apply the clamp. Every mutator calls it already; it is exposed for a caller who changed the bounds rectangle by some other route, and for tests asserting idempotence — clamp(); clamp() must be a no-op, and the version that oscillates between two positions is the one that fed min > max to a two-sided clamp.

isVisible(minX: number, minY: number, maxX: number, maxY: number): boolean

Is this world box worth drawing? A cheap AABB reject, generous by one tile on each axis so that geometry poking outside its declared box does not flicker at the edge of the screen.

visibleTileBounds(out: TileRange, marginTiles?: number): TileRange

The conservative grid rectangle covering the viewport — the terrain loop's bounds.

Computed by projecting the four screen corners into grid space and taking the min/max, because the visible region is a diamond in grid space, not a rectangle. A loop derived from a grid-space rectangle silently misses the two side corners of the screen and leaves triangular holes of unpainted ground. The returned range over-covers by roughly 2×, and that is the correct trade against a per-tile diamond intersection test.

visibleWorldBounds(out: Rect, marginPx?: number): Rect

The world rectangle covering the viewport, for culling anything not on the tile lattice — a backdrop gradient, a light pool, a cached scenery chunk.

The Rect-shaped counterpart to Camera.isVisible: that one asks about a box you have, this one hands over the box to test against.

createCamera functionstart here ↳ src/camera.ts:407

function createCamera(viewW: number, viewH: number, options?: CameraOptions): Camera

gridToScreen function ↳ src/camera.ts:684

function gridToScreen(camera: Camera, gx: number, gy: number, zPx: number, out: Vec2): Vec2

DepthSorter classstart here ↳ src/depth.ts:101

class DepthSorter {

8 members

#private

get count(): number

Items surviving the cull. Before DepthSorter.sort this is everything added.

get sorted(): boolean

Whether the permutation is currently valid for the contents — the only question a reader of DepthSorter.indexAt needs answered, and the reason it is phrased that way.

Not "has sort ever been called". DepthSorter.add, addPoint and DepthSorter.clear lower it, because they change the set the permutation is a permutation of, and those three are the only ways the contents can move. So the honest question and the cheap flag are the same bit, and the name is about the order rather than about a call in the past.

It exists because nothing else on this surface can tell the two states apart. Before a sort, count is the fill count and indexAt(i) is i — and an unculled frame whose items happened to arrive in depth order is bit-identical to that. Every detector assembled from count and indexAt is therefore a false alarm on a real frame, which is why the frame bucket above this package shipped no detector at all and routed the gap back here: one bit that only this class can set closes it, and nothing outside could.

What it deliberately does not claim is that the cull still matches the camera. A camera that pans after sort() leaves the survivor set stale, and that is not this flag's business: paint and pick read the same stale set from the same instance, so they still agree with each other, and agreement is the property the contract with @latticekit/draw actually rests on.

clear(): void

Drop every item, keeping the buffers. Call it once at the top of the frame — a sorter that is not cleared paints last frame's world underneath this one's.

add(gx: number, gy: number, w: number, d: number, heightPx: number): number

Add a footprint.

Throws

RangeError if w or d is not a positive finite number. A zero-extent footprint is incomparable with everything that shares either of its spans, which is not a corner case but the exact condition the readiness test in this module's header relies on being impossible.

addPoint(gx: number, gy: number, heightPx: number, radius?: number): number

Add a point-like thing — a walker, a floating number's origin, a dropped resource.

Given a small square footprint rather than zero extent, so it can be strictly beside a wall instead of forever ambiguous with it. A true point shares a span with every footprint it stands near and is therefore incomparable with all of them, which is how pedestrians end up drawn through a wall at second-storey height.

Throws

RangeError if radius is not a positive finite number.

sort(camera?: Camera): void

Cull against the camera, then order back-to-front. Allocation-free after warm-up.

Culling lives here rather than in draw because it is a camera-geometry question, not a rendering one — it is Camera.isVisible applied to a footprint's world bounds, extended upward by the height. Every consumer would otherwise write the same six lines and one of them would forget the height, which pops skylines in and out along the bottom edge.

indexAt(i: number): number

The insertion index at sorted position i, 0 ≤ i < count, back to front.

This is the whole output: for (let i = 0; i < s.count; i++) paint(items[s.indexAt(i)]) is the painter's algorithm, correctly.

Throws

TypeError if DepthSorter.sorted is false — before the first sort(), or after an add or a clear invalidated the permutation. This used to return insertion order, "a defined answer rather than a useful one", and defined was the problem: it is indistinguishable from a sorted, unculled frame, so the caller got a plausible integer, painted a plausible-looking frame in fill order, and picked from a permutation that no longer described their items. There is no longer any expression that yields an index from an invalid permutation — this method and pickSorted are the only two readers, and both refuse. A TypeError rather than a RangeError because i is not the wrong value: the receiver is in the wrong state, the same kind of mistake as releasing a pooled instance twice.

Throws

RangeError outside [0, count). Checked second, because before a sort count is the fill count rather than the survivor count, and a range reported against it would name a bound that the caller's next correct step is about to change. An out-of-range read would return undefined from the typed array, and the ! someone would reach for to silence that is how a renderer ships a black screen.

pickSorted function ↳ src/depth.ts:499

function pickSorted(order: DepthSorter, test: (index: number) => boolean): number

Parameters

TileSource interface ↳ src/tilemap.ts:55

interface TileSource {

2 members

get(gx: number, gy: number): number

Value at (gx, gy). Out of bounds returns the source's out-of-bounds value; never throws, because this is read inside pathfinding loops that scan past the edge by design.

has(gx: number, gy: number): boolean

Is this tile inside the map's defined region? Always true for an infinite source, which has no outside. Distinguishing "empty" from "absent" is what lets terrain-aware picking report that the ray left the map instead of returning a plausible tile.

MutableTileSource interface ↳ src/tilemap.ts:66

interface MutableTileSource extends TileSource {

4 members

set(gx: number, gy: number, value: number): void

Throws

RangeError out of bounds, naming the coordinate and the map's extent.

fill(value: number): void

Every tile to one value.

fillFrom(get: (gx: number, gy: number) => number): void

Fill from a function — a seeded heightfield through core.hash2, a river mask, a noise field. It saves every game the same nested loop, and it is the seam where determinism enters a map: the function sees only coordinates, so the result cannot depend on the order tiles were visited.

readonly version: number

Bumped on every mutation that changes a value.

This is the whole of the cheap-recompute answer. A caller holding a path, a flow field or a cached arc length compares against the version it was built from; when the rockfall is cleared one set bumps this, everything downstream recomputes exactly once, and nothing has to be told what changed. Comparing map contents to detect a change costs more than replanning.

TileGridOptions interface ↳ src/tilemap.ts:96

interface TileGridOptions {

5 members

readonly originGx?: number

Grid origin in tiles. Default 0, 0. Lets an island sit at negative coordinates without every consumer subtracting an offset it might get the sign of wrong.

readonly originGy?: number

See TileGridOptions.originGx.

readonly bits?: 8 | 16 | 32

Storage width per tile. Default 8. Pick the smallest that holds your value set: values wider than the store wrap silently, because that is what a typed array does.

readonly fill?: number

Initial value everywhere. Default 0.

readonly outOfBounds?: number

What TileSource.get returns outside the grid. Default 0. Set it to whatever your cost function reads as impassable and the pathfinder stops at the shore for free.

TileGrid class ↳ src/tilemap.ts:129

class TileGrid implements MutableTileSource {

13 members

#private

readonly w: number

Width in tiles.

readonly h: number

Height in tiles.

readonly originGx: number

Grid x of the first column.

readonly originGy: number

Grid y of the first row.

readonly data: Uint8Array | Uint16Array | Uint32Array

The backing store, exposed on purpose so saves and workers can take it whole. Row-major from the origin corner: index (gy - originGy) * w + (gx - originGx).

get version(): number

Bumped whenever a write changed a stored value. Compared, never interpreted: the number itself means nothing and only its inequality with a cached copy does.

get(gx: number, gy: number): number

Value at (gx, gy), or the grid's out-of-bounds value outside it and for any coordinate that is not a whole number.

has(gx: number, gy: number): boolean

Is (gx, gy) a tile of this grid? False for fractional coordinates: a tile address with a fraction in it is a world pixel that forgot to be converted.

set(gx: number, gy: number, value: number): void

Write one tile.

Bumps TileGrid.version only when the stored value actually changed — compared after the store truncated it, so writing 300 into an 8-bit grid that already holds 44 correctly counts as no change rather than as one. Callers use the version to decide whether to rebuild a flow field, and a spurious bump costs a Dijkstra sweep.

Throws

RangeError outside the grid, naming the coordinate and the extent.

fill(value: number): void

Every tile to one value, bumping the version once.

fillFrom(get: (gx: number, gy: number) => number): void

Every tile from a function of its coordinates, row-major, bumping the version once.

forEach(range: Readonly<TileRange>, fn: (gx: number, gy: number, value: number) => void): void

Iterate a sub-rectangle, clipped to the grid. The terrain draw loop.

Clipped rather than throwing, because the range this is called with comes from Camera.visibleTileBounds, which deliberately over-covers and will therefore routinely name tiles that are off the map. Half-open on gx1/gy1, like every range in this kit.

tileSourceOf function ↳ src/tilemap.ts:273

function tileSourceOf(get: (gx: number, gy: number) => number): TileSource

HeightField interface ↳ src/height.ts:34

interface HeightField {

2 members

readonly heights: TileSource

The layer. Values are height units, whatever the game decided those are — the conversion to pixels lives in HeightField.stepPx so an 8-bit grid can hold a useful range.

readonly stepPx: number

World pixels per height unit. An art constant the game chooses.

TILE_H / 4 is a good first guess, because four steps of rise per tile is where a 2:1 slope stops reading as a slope and starts reading as a wall.

unitsToPx function ↳ src/height.ts:55

function unitsToPx(field: HeightField, units: number): number

pxToUnits function ↳ src/height.ts:89

function pxToUnits(field: HeightField, px: number): number

const cost = 1 + (pxToUnits(field, slopeAt(field, gx, gy)) | 0);

heightAt function ↳ src/height.ts:110

function heightAt(field: HeightField, gx: number, gy: number): number

worldToTileOnHeights function ↳ src/height.ts:191

function worldToTileOnHeights(field: HeightField, wx: number, wy: number, maxHeightPx: number, out: Tile): boolean

Parameters

slopeAt function ↳ src/height.ts:264

function slopeAt(field: HeightField, gx: number, gy: number): number

Footprint interface ↳ src/footprint.ts:26

interface Footprint {

4 members

readonly gx: number

Grid x of the north corner.

readonly gy: number

Grid y of the north corner.

readonly w: number

Extent along +gx, in tiles.

readonly d: number

Extent along +gy, in tiles.

footprintContains function ↳ src/footprint.ts:39

function footprintContains(f: Footprint, gx: number, gy: number): boolean

footprintOverlaps function ↳ src/footprint.ts:45

function footprintOverlaps(a: Footprint, b: Footprint): boolean

forEachFootprintTile function ↳ src/footprint.ts:60

function forEachFootprintTile(f: Footprint, fn: (gx: number, gy: number) => void): void

footprintFlatness function ↳ src/footprint.ts:83

function footprintFlatness(field: HeightField, f: Footprint): number

footprintBase function ↳ src/footprint.ts:109

function footprintBase(field: HeightField, f: Footprint): number

footprintAnchor function ↳ src/footprint.ts:134

function footprintAnchor(f: Footprint, heightPx: number, out: Anchor): Anchor

Anchor interface ↳ src/anchor.ts:36

interface Anchor extends GridPoint {

1 member

zPx: number

Height above the z = 0 plane in world pixels, not tiles and not storeys. On terrain this is heightAt(field, gx, gy) plus however far up the thing hangs.

anchorToScreen function ↳ src/anchor.ts:51

function anchorToScreen(camera: Camera, a: Readonly<Anchor>, out: Vec2): Vec2

anchorVisible function ↳ src/anchor.ts:67

function anchorVisible(camera: Camera, a: Readonly<Anchor>, marginPx?: number): boolean

Parameters

anchorPan function ↳ src/anchor.ts:90

function anchorPan(camera: Camera, a: Readonly<Anchor>): number

screenToTile functionstart here ↳ src/hittest.ts:59

function screenToTile(camera: Camera, sx: number, sy: number, out: Tile): Tile

screenToTileOnHeights function ↳ src/hittest.ts:95

function screenToTileOnHeights(camera: Camera, sx: number, sy: number, field: HeightField, maxHeightPx: number, out: Tile): boolean

Parameters

Volume interface ↳ src/hittest.ts:121

interface Volume {

6 members

readonly ox: number

Offset of the volume's north corner from the anchor tile, along +gx, in tiles.

readonly oy: number

Offset along +gy, in tiles.

readonly w: number

Extent along +gx, in tiles.

readonly d: number

Extent along +gy, in tiles.

readonly zPx: number

Elevation of the volume's base above the z = 0 plane, in world pixels.

readonly hPx: number

Height of the volume itself, in world pixels.

boxSilhouette function ↳ src/hittest.ts:156

function boxSilhouette(camera: Camera, gx: number, gy: number, volume: Volume, out: Float64Array): Float64Array

Parameters

pointInPolygon function ↳ src/hittest.ts:213

function pointInPolygon(sx: number, sy: number, poly: Float64Array, count: number): boolean

Parameters

pointInTile function ↳ src/hittest.ts:252

function pointInTile(camera: Camera, sx: number, sy: number, gx: number, gy: number): boolean

TileCost type ↳ src/path.ts:54

type TileCost = (gx: number, gy: number) => number

STEP_ORTHO const ↳ src/path.ts:57

const STEP_ORTHO = 10

STEP_DIAG const ↳ src/path.ts:61

const STEP_DIAG = 14

DIR_DX const ↳ src/path.ts:75

const DIR_DX: readonly number[]

DIR_DY const ↳ src/path.ts:78

const DIR_DY: readonly number[]

PathOptions interface ↳ src/path.ts:97

interface PathOptions {

5 members

readonly diagonals?: boolean

Allow 8-way movement. Default true.

readonly cutCorners?: boolean

Allow a diagonal step when a shared orthogonal neighbor is blocked. Default false, and leave it false: true walks agents through the corner where two walls meet, which looks exactly like clipping through the building.

readonly maxNodes?: number

Hard ceiling on expanded nodes. Default 20000.

Not a performance knob — a determinism and liveness one. A TileSource need not have an edge: tileSourceOf answers has with true everywhere, so on a procedural world an unreachable goal otherwise searches until the tab dies. Nothing else stops it — a bounded grid stops a search by running out of tiles, and an unbounded source never does. The ceiling has to be a node count rather than a time limit so that the same query gives the same answer on a slow phone as on a desktop.

readonly bounds?: Readonly<TileRange>

Confine the search to a tile rectangle, half-open. Cheaper than making the cost function say so, and it is the difference between a failed search that stops and one that explores the whole world first.

readonly minWeight?: number

The smallest weight the cost function will return for any passable tile this search can reach. A positive integer, default 1, and the one number that lets a weighted map keep A\*'s heuristic instead of sliding into Dijkstra.

What it buys

The heuristic is the integer octile metric, which is the true cost of crossing an offset over ground that weighs 1. Tell the searcher the ground weighs at least 3 and the estimate can be three times larger and still never overestimate — see the admissibility argument in PathFinder.find. An estimate that is wMin times too small is an estimate A\* has to buy back by expanding nodes, and the bill is exponential in the gap:

ground	minWeight	what the frontier does
every passable tile weighs 1	1	nothing changes — this is the shipped behavior, to the bit
every passable tile weighs 3 to 8	3	the estimate is three times tighter; the expanded set collapses towards the corridor
tiles weigh 1 to 8	1	nothing changes, and nothing can: one tile of weight 1 anywhere on a cheaper route is enough to make any larger estimate a lie

The third row is the honest limit and is why this is an option rather than a fix. This number is a property of the whole cost function, not of the route, so a single cheap tile holds it down for the entire map. A cost function that returns 1 + roughness gets nothing here; one that returns 2 + roughness — the same ordering, the same ratios, one unit of floor — gets a heuristic twice as tight, for free, forever.

Why the caller declares it rather than the searcher deriving it

It is a property of the cost function, and the cost function is the caller's. Scanning the map for it costs a pass over every tile per search, needs a bound to scan (a TileCost over seeded noise has no edge), and is stale the instant a brush moves the ground — which is the case this exists for. Caching it on the PathFinder would be worse still: one finder serves many cost functions, so the cache would be keyed on nothing. Declaring it beside the cost function it describes also satisfies non-negotiable 11 without a line of code: PathOptions is a plain object the caller built and still holds, so every field is readable back off it and there is nothing to shadow-copy.

Declare it wrong and you get an error, not a wrong road

A minimum higher than the truth makes the heuristic overestimate, and an overestimating A\* returns a route that is merely good while reporting it as cheapest — a wrong answer with no crash behind it, which is the worst failure this module has. So PathFinder.find throws the moment the cost function contradicts the declaration, naming the tile and both numbers. It is one comparison per examined neighbor, on the same line as the integer check that is already there for the same class of bug.

That check covers every tile the search paid to look at, which is a superset of the route it returns and a subset of the map. A tile cheaper than the declaration that the search never reaches at all cannot be caught, and in the rare shape where such a tile sits one step beyond the frontier it can still cost optimality — so the declaration is a promise about the cost function, and the check is the net under it, not a substitute for meaning it.

An integer, and that is not tidiness: octile × minWeight becomes the heap key, and this module's determinism rests on those keys being exact integers (see the file header). minWeight: 1.5 would put a float in the frontier's ordering and hand two engines two different roads.

Path class ↳ src/path.ts:197

class Path {

12 members

#private

get nodeCount(): number

Number of nodes, including both endpoints. 0 for an empty path.

get arcLength(): number

Total length in world pixels, and the domain of every s parameter in this module. 0 for an empty or single-node path.

get version(): number

Bumped on every mutation. Cache anything derived from the path against it — a crowd's spacing, a reach, a set of lamp offsets — and the recompute happens exactly once.

get searchFailure(): string | undefined

Why the last PathFinder.find writing into this path found nothing — a clause naming the two tiles — or undefined if the last thing to touch it was a successful search, a Path.push or a Path.clear.

This is the boot-time check that the boolean from find cannot be, because the search and the sampling are usually in different modules. A failed search clears its out path, an empty path throws from pathSample and pathProject, and a generated world puts a river across the gate on roughly one seed in fifty — so the first anyone hears of it is a white screen on somebody else's machine, thrown from the render loop, a long way from the search that caused it. A world builder that hands out a Path should either check the boolean where it searched or leave this for whoever receives the path:

if (road.searchFailure !== undefined) {
  // no route, and the clause says between which two tiles. Author a fallback, pick another
  // seed, or refuse to start — but do it here, not sixty frames later.
}

A string rather than a boolean so the reason survives the trip: pathSample quotes it, and "no route from (25, 9) to (7, 22)" is the difference between a bug report and a bug.

noteSearchFailed(fromGx: number, fromGy: number, toGx: number, toGy: number): void

Record that a search found no route, so an empty path can say why instead of only that it is empty.

Called by PathFinder.find on every failing return. Public because a game that authors its routes some other way — a flow field walk, a hand-written spline generator — has the same gap and the same need to say so; harmless to call, and cleared by the next Path.push or Path.clear.

gxAt(i: number): number

Grid x of node i. @throws RangeError when i is out of range, rather than returning undefined for a caller to trip over three systems away.

gyAt(i: number): number

Grid y of node i. @throws RangeError when i is out of range.

sAt(i: number): number

Arc length in world pixels from the start to node i; sAt(nodeCount - 1) is Path.arcLength. @throws RangeError when i is out of range.

push(gx: number, gy: number): void

Append a node, extending Path.arcLength by the world distance from the previous one.

Fractional coordinates are allowed and are how a game hands in an authored road spline: a valley road that is generated rather than searched still needs to be sampled, and it would be a strange API that could only sample the routes it found itself.

clear(): void

Drop every node, keeping the buffers, and bump Path.version. Also forgets any Path.searchFailure: a deliberate clear is not a failed search, and a path that reported one after being emptied on purpose would cry wolf.

compactTo(keep: Int32Array, kept: number): void

Keep the nodes whose index appears in keep[0 .. kept), in order, then reindex. The one mutation pathSimplify needs and the only reason this method exists.

pathSample functionstart here ↳ src/path.ts:407

function pathSample(path: Path, sPx: number, out: GridPoint): GridPoint

pathDirAt function ↳ src/path.ts:464

function pathDirAt(path: Path, sPx: number): number

pathProject function ↳ src/path.ts:517

function pathProject(path: Path, gx: number, gy: number): number

pathSimplify function ↳ src/path.ts:624

function pathSimplify(path: Path, cost?: TileCost): void

Parameters

PathFinder class ↳ src/path.ts:822

class PathFinder {

2 members

#private

find(cost: TileCost, fromGx: number, fromGy: number, toGx: number, toGy: number, out: Path, options?: PathOptions): boolean

Search.

Throws

RangeError if the cost function returns a non-integer weight for a passable tile. Float costs are the replay divergence this module's header is about, and one comparison per examined neighbor is a cheap price for a bug whose only symptom is two players seeing different roads.

Throws

RangeError if options.minWeight is not an integer >= 1, or if the cost function returns a passable weight below it. The second is the caller's declaration being wrong, and it is thrown rather than tolerated because the symptom of tolerating it is a route that is not the cheapest one with nothing at all to say so.

FlowField class ↳ src/path.ts:1150

class FlowField {

9 members

#private

get range(): Readonly<TileRange>

The rectangle this field covers, half-open. The field's own object: read it, do not keep it and mutate it.

get builtAtVersion(): number

The map version the last FlowField.build was told about; -1 before the first build and after any build that was not told one.

-1 and not 0, so that an untold field always compares unequal to a real map's version and therefore rebuilds. Failing towards a spare Dijkstra sweep is the right direction to fail: the other way round, the crowd walks the old road for ever.

clearGoals(): void

Forget the previous goals. Cheap; the buffers stay.

addGoal(gx: number, gy: number): void

Add a destination. Tiles outside FlowField.range are ignored rather than an error — a warehouse can legitimately sit off the edge of the field, and refusing to build because of one would take the whole crowd down with it.

build(cost: TileCost, options?: PathOptions, sourceVersion?: number): void

Integrate: one Dijkstra sweep outward from every goal at once.

Deterministic — the frontier is ordered by accumulated cost with ties broken by tile index, which is a total order over the field, so the same map and the same goals give the same field on every engine.

*(The RFC sketched a bucket queue. A binary heap is used instead because the largest edge weight is whatever the caller's cost function returns, and a bucket queue sized for an unknown maximum is either wrong or unbounded. The ordering guarantee is identical, and it is the ordering that the determinism rests on.)*

Throws

RangeError if the cost function returns a non-integer weight, for the reason PathFinder.find gives.

dirAt(gx: number, gy: number): number

Direction code 1..8 to step next, or 0 for "no route from here" — which is also what a goal tile returns, because there is nowhere left to step. FlowField.costAt tells the two apart: a goal is 0 and no route is -1.

costAt(gx: number, gy: number): number

Accumulated cost to the nearest goal in STEP_ORTHO units, or -1 when the tile is unreachable or outside the field.

step(gx: number, gy: number, out: GridPoint): boolean

Sugar over FlowField.dirAt: writes the next tile into out and returns true, or returns false leaving out untouched when there is no route.

VERSION const ↳ src/index.ts:69

const VERSION = "0.1.1"