# gizgame/procgen

worlds made from one seed. Every part takes its own seed from the world's and its name (seedOf), so a change to one part leaves the others as they were, and the same seed is the same world on every machine: all of it is integer hashing and f64 arithmetic in a fixed order. Terrain is fractal noise (gizlang/math noise2), ridged and warped as its Shape says, then worn by water drops (erode). Biomes come from height, warmth and wetness; scatter places things by Poisson disk. A dungeon is rooms in a binary space partition joined by a spanning tree and a few loops; a town is roads, lots and buildings. A quest is what a language model wrote against the world's facts (QUEST_PROMPT), kept only when every step names a fact (questOf): the model writes, the game checks.

```gizlang
import * as Procgen from "gizgame/procgen";
```

## Types

### `Shape`

```gizlang
type Shape = { scale: f64; height: f64; octaves: i64; ridged: f64; warp: f64; sea: f64; }
```

A terrain's shape: SCALE meters a feature, HEIGHT meters its range, OCTAVES of detail, RIDGED (0 to 1) how much
of it is sharp crests, WARP meters of domain warp (twisted valleys), and the SEA level as a fraction of the range.

- `scale`: `f64`
- `height`: `f64`
- `octaves`: `i64`
- `ridged`: `f64`
- `warp`: `f64`
- `sea`: `f64`

### `Biome`

```gizlang
type Biome = { name: string; low: f64; high: f64; warm: f64; wet: f64; }
```

A biome: its NAME and the warmth and wetness (0 to 1) it takes, at heights between LOW and HIGH meters.

- `name`: `string`
- `low`: `f64`
- `high`: `f64`
- `warm`: `f64`
- `wet`: `f64`

### `Room`

```gizlang
type Room = { x: i64; z: i64; width: i64; depth: i64; }
```

A room of a dungeon: its corner and size in tiles.

- `x`: `i64`
- `z`: `i64`
- `width`: `i64`
- `depth`: `i64`

### `Dungeon`

```gizlang
type Dungeon = { columns: i64; rows: i64; tiles: Vec<i64>; rooms: Vec<Room>; }
```

The tiles of a dungeon, row after row, and its rooms.

- `columns`: `i64`
- `rows`: `i64`
- `tiles`: `Vec<i64>`
- `rooms`: `Vec<M188.Room>`

### `Triangles`

```gizlang
type Triangles = { positions: Vec<f64>; indices: Vec<i64>; }
```

The floor of D as triangles (positions x, y, z and indices) of TILE meters at height 0 and its walls at
HEIGHT (a wall tile is a quad at that height, which navigation cannot climb), for a mesh to draw and for navigation
to build on.

- `positions`: `Vec<f64>`
- `indices`: `Vec<i64>`

### `Road`

```gizlang
type Road = { a: Point3; b: Point3; width: f64; }
```

A town: its roads (each from A to B, WIDTH meters) and its lots, each with a building's footprint (x, z, width,
depth in meters), its floors and its KIND (house, shop, inn, hall, smithy, temple).

- `a`: `gizlang_geometry.Point3`
- `b`: `gizlang_geometry.Point3`
- `width`: `f64`

### `Lot`

```gizlang
type Lot = { x: f64; z: f64; width: f64; depth: f64; floors: i64; kind: string; }
```

A building lot of a town: its center, size, floors and kind.

- `x`: `f64`
- `z`: `f64`
- `width`: `f64`
- `depth`: `f64`
- `floors`: `i64`
- `kind`: `string`

### `Town`

```gizlang
type Town = { roads: Vec<Road>; lots: Vec<Lot>; }
```

The roads and lots of a town.

- `roads`: `Vec<M188.Road>`
- `lots`: `Vec<M188.Lot>`

### `Fact`

```gizlang
type Fact = { id: string; kind: string; about: string; }
```

A fact of the world a quest may name: its ID, its KIND (person, place, item, creature) and a line about it.

- `id`: `string`
- `kind`: `string`
- `about`: `string`

### `Step`

```gizlang
type Step = { kind: string; target: string; to?: string; count?: i64; text: string; }
```

A step of a quest: go to a place, talk to a person, bring an item to a person, or defeat creatures (COUNT).

- `kind`: `string`
- `target`: `string`
- `to`: `_gizlang_sdk_core.Option<string>`
- `count`: `_gizlang_sdk_core.Option<i64>`
- `text`: `string`

### `Quest`

```gizlang
type Quest = { giver: string; title: string; steps: Vec<Step>; reward: string; }
```

A quest: its giver (a person), its title, its steps in order and its reward (an item, or "" none).

- `giver`: `string`
- `title`: `string`
- `steps`: `Vec<M188.Step>`
- `reward`: `string`

## Functions

### `seedOf`

```gizlang
function seedOf(seed: i64, name: string): i64
```

The seed of the part NAME of the world SEED (FNV-1a over the name, mixed with the seed).

Effects: fail.

### `hills`

```gizlang
function hills(): Shape
```

Rolling hills, 30 m high, with no sea.

### `mountains`

```gizlang
function mountains(): Shape
```

Ridged mountains, 180 m high, with valleys under a sea.

### `heightOf`

```gizlang
function heightOf(shape: Shape, seed: i64, x: f64, z: f64): f64
```

The height of the terrain SHAPE of SEED at X, Z in meters.

Effects: fail.

### `terrain`

```gizlang
function terrain(shape: Shape, seed: i64, columns: i64, rows: i64, spacing: f64, origin: Point3): Field
```

The terrain SHAPE of SEED as a field of COLUMNS by ROWS samples SPACING meters apart, from ORIGIN.

Effects: fail, alloc.

### `erode`

```gizlang
function erode(f: Field, seed: i64, drops: i64): Field
```

F worn by DROPS water drops of SEED: each runs downhill, takes soil where it speeds up and drops it where it slows
(hydraulic erosion as Beyer's 2015 thesis gives it, with its constants).

Effects: fail, read, write, alloc.

### `biomeAt`

```gizlang
function biomeAt(biomes: Vec<Biome>, seed: i64, x: f64, z: f64, height: f64): string
```

The biome of the point X, Z at HEIGHT of SEED among BIOMES: the nearest in warmth and wetness of those its
height allows (warmth falls 0.6 every 100 m).

Effects: fail.

### `scatter`

```gizlang
function scatter(seed: i64, low: Point3, high: Point3, spacing: f64, allows: (x: f64, z: f64) => bool): Vec<Point3>
```

Points of SEED in the rectangle from LOW to HIGH (x, z), each at least SPACING from every other and kept by
ALLOWS (Bridson's Poisson disk sampling, 30 tries a point).

Effects: fail, read, write, console, io, alloc.

### `dungeon`

```gizlang
function dungeon(seed: i64, columns: i64, rows: i64, least: i64 = 8, loops: i64 = 4): Dungeon
```

A dungeon of SEED on COLUMNS by ROWS tiles: the space split in two again and again (never below LEAST tiles a
side), a room in each leaf, the rooms joined by a minimum spanning tree of their centers and a loop for about one
room in LOOPS more, each joint an L-shaped corridor with a door where it meets a room.

Effects: fail, read, write, alloc.

### `floorOf`

```gizlang
function floorOf(d: Dungeon, tile: f64, height: f64): Triangles
```

The floor and walls of D as triangles: TILE meters a tile, walls HEIGHT meters high.

Effects: fail, read, write, alloc.

### `surfaceOf`

```gizlang
function surfaceOf(f: Field): Triangles
```

The ground of F as triangles, two a cell, for navigation to build on (as floorOf gives a dungeon's).

Effects: fail, alloc.

### `town`

```gizlang
function town(seed: i64, center: Point3, blocks: i64 = 4, block: f64 = 40.0): Town
```

A town of SEED of BLOCKS by BLOCKS blocks of BLOCK meters around CENTER: a road grid bent by noise, each block cut
into lots along its roads, the hall and the temple near the middle.

Effects: fail, alloc.

### `questPrompt`

```gizlang
function questPrompt(facts: Vec<Fact>): string
```

The prompt of FACTS: QUEST_PROMPT and one line a fact.

Effects: fail, read, write, console, io, alloc.

### `questOf`

```gizlang
function questOf(text: string, facts: Vec<Fact>): Quest throws string
```

The quest in TEXT (a model's answer: its first `{` to its last `}`), when every ID names a fact of the kind its
place asks; else why not, for the model to try again.

Effects: fail, alloc.

## Constants

### `WALL`

```gizlang
const WALL: i64 = 0
```

A dungeon: a grid of COLUMNS by ROWS tiles (WALL, FLOOR or DOOR) and its rooms (x, z, width, depth in tiles).

### `FLOOR`

```gizlang
const FLOOR: i64 = 1
```

A dungeon tile one walks on.

### `DOOR`

```gizlang
const DOOR: i64 = 2
```

A dungeon tile where a corridor enters a room.

### `QUEST_PROMPT`

```gizlang
const QUEST_PROMPT = "You write one quest for a game. Answer with JSON only: {\"giver\":ID,\"title\":TEXT," + "\"steps\":[{\"kind\":\"go|talk|bring|defeat\",\"target\":ID,\"to\":ID,\"count\":N,\"text\":TEXT}],\"reward\":ID}. " + "Every ID is one of the facts below: giver a person, go a place, talk a person, bring an item (to a person), " + "defeat a creature (count 1 to 10), reward an item or \"\". Use 1 to 5 steps that tell one small story.\nFacts:\n"
```

What a language model is told before the facts, to answer with one Quest.

