# gizgame/map3d

a map of a 3D game as data. A game's world (Game.world) lists its maps, each with its file: JSON that declares its ground and the ground's relief, its sky, its eye, its things, its sets, its props and what it strews. The host reads the files from the game's folder at each start, so a map changes, or a new one comes (a mod), with no build. The game's code gives what only code can (Rules3D): what its rules add, what it draws each frame, its HUD. A file's places are [x, z] on the ground, or [x, y, z]; a way is a compass bearing in degrees (180 faces south, +z).

```gizlang
import * as Map3d from "gizgame/map3d";
```

## Types

### `GroundFile`

```gizlang
type GroundFile = { side: f64; samples: i64; materials: Vec<string>; rules: Ground; relief?: Relief; grass?: Grass3D; }
```

A map's ground: SIDE meters a side of SAMPLES points, of the ambientCG MATERIALS blended by RULES (Ground3D), shaped
by its RELIEF (flat without one: the land under the sets), and its GRASS.

- `side`: `f64`
- `samples`: `i64`
- `materials`: `Vec<string>`
- `rules`: `gizlang_meshdraw.Ground`
- `relief`: `_gizlang_sdk_core.Option<M197.Relief>`
- `grass`: `_gizlang_sdk_core.Option<M203.Grass3D>`

### `FixedSky`

```gizlang
type FixedSky = { sun: Vec<f64>; light: Vec<f64>; ambient: Vec<f64>; sky: Vec<f64>; zenith?: Vec<f64>; fog: f64; shadow: f64; bounce?: f64; occlusion?: f64; }
```

A light that does not change: the SUN's direction and the rest of an Environment.

- `sun`: `Vec<f64>`
- `light`: `Vec<f64>`
- `ambient`: `Vec<f64>`
- `sky`: `Vec<f64>`
- `zenith`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `fog`: `f64`
- `shadow`: `f64`
- `bounce`: `_gizlang_sdk_core.Option<f64>`
- `occlusion`: `_gizlang_sdk_core.Option<f64>`

### `SkyFile`

```gizlang
type SkyFile = { fixed?: FixedSky; day?: f64; night?: Dark; shadow?: f64; haze?: f64; dawn?: bool; }
```

A map's sky: FIXED, or a DAY of that many seconds (sunlit) through its NIGHT, SHADOW meters of shadow and a HAZE by
day (thin where the skyline is far); with DAWN the day comes once the game is won.

- `fixed`: `_gizlang_sdk_core.Option<M191.FixedSky>`
- `day`: `_gizlang_sdk_core.Option<f64>`
- `night`: `_gizlang_sdk_core.Option<M203.Dark>`
- `shadow`: `_gizlang_sdk_core.Option<f64>`
- `haze`: `_gizlang_sdk_core.Option<f64>`
- `dawn`: `_gizlang_sdk_core.Option<bool>`

### `EyeFile`

```gizlang
type EyeFile = { follow?: string; rig?: Follow; views?: Vec<Follow>; first?: bool; fov?: f64; title: { center: Vec<f64>; radius: f64; height: f64; speed: f64; }; }
```

A map's eye (Eye3D): on the title it circles CENTER at RADIUS and HEIGHT, a turn in 2 pi / SPEED seconds.

- `follow`: `_gizlang_sdk_core.Option<string>`
- `rig`: `_gizlang_sdk_core.Option<M203.Follow>`
- `views`: `_gizlang_sdk_core.Option<Vec<M203.Follow>>`
- `first`: `_gizlang_sdk_core.Option<bool>`
- `fov`: `_gizlang_sdk_core.Option<f64>`
- `title`: `{ center: Vec<f64>; radius: f64; height: f64; speed: f64; }`

### `ThingFile`

```gizlang
type ThingFile = { name: string; file?: string; polyHaven?: string; skin?: Skin; sphere?: Vec<i64>; material?: Material; glow?: Vec<f64>; thin?: f64; most?: i64; casts?: bool; far?: Vec<f64>; }
```

A thing (Thing3D): a FILE of the lock, or the Poly Haven model POLYHAVEN, or a SPHERE of that many segments and rings
in its MATERIAL (GLOW: a light's color and strength in place of one); its SKIN, THIN, MOST, CASTS and FAR.

- `name`: `string`
- `file`: `_gizlang_sdk_core.Option<string>`
- `polyHaven`: `_gizlang_sdk_core.Option<string>`
- `skin`: `_gizlang_sdk_core.Option<M203.Skin>`
- `sphere`: `_gizlang_sdk_core.Option<Vec<i64>>`
- `material`: `_gizlang_sdk_core.Option<gizlang_meshdraw.Material>`
- `glow`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `thin`: `_gizlang_sdk_core.Option<f64>`
- `most`: `_gizlang_sdk_core.Option<i64>`
- `casts`: `_gizlang_sdk_core.Option<bool>`
- `far`: `_gizlang_sdk_core.Option<Vec<f64>>`

### `SetFile`

```gizlang
type SetFile = { file: string; at?: Vec<f64>; facing?: f64; size?: f64; far?: Vec<f64>; ground?: bool; }
```

A set (Set3D) AT a place, its front FACING a bearing.

- `file`: `string`
- `at`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `facing`: `_gizlang_sdk_core.Option<f64>`
- `size`: `_gizlang_sdk_core.Option<f64>`
- `far`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `ground`: `_gizlang_sdk_core.Option<bool>`

### `PropFile`

```gizlang
type PropFile = { kind: string; at: Vec<f64>; size?: f64; facing?: f64; lying?: bool; solid?: f64; sway?: f64; round?: bool; }
```

A prop (Prop3D) AT a place, its front FACING a bearing.

- `kind`: `string`
- `at`: `Vec<f64>`
- `size`: `_gizlang_sdk_core.Option<f64>`
- `facing`: `_gizlang_sdk_core.Option<f64>`
- `lying`: `_gizlang_sdk_core.Option<bool>`
- `solid`: `_gizlang_sdk_core.Option<f64>`
- `sway`: `_gizlang_sdk_core.Option<f64>`
- `round`: `_gizlang_sdk_core.Option<bool>`

### `MapFile`

```gizlang
type MapFile = { ground?: GroundFile; sea?: Vec<f64>; sky: SkyFile; eye: EyeFile; far?: f64; things?: Vec<ThingFile>; sets?: Vec<SetFile>; props?: Vec<PropFile>; strew?: Vec<Strew>; start?: Vec<f64>; }
```

A map's file: its GROUND, SEA, SKY, EYE, FAR, THINGS, SETS, PROPS and what it STREWs (Scene3D), and where the
game's player STARTs. A game reads its own fields of the same file (text).

- `ground`: `_gizlang_sdk_core.Option<M191.GroundFile>`
- `sea`: `_gizlang_sdk_core.Option<Vec<f64>>`
- `sky`: `M191.SkyFile`
- `eye`: `M191.EyeFile`
- `far`: `_gizlang_sdk_core.Option<f64>`
- `things`: `_gizlang_sdk_core.Option<Vec<M191.ThingFile>>`
- `sets`: `_gizlang_sdk_core.Option<Vec<M191.SetFile>>`
- `props`: `_gizlang_sdk_core.Option<Vec<M191.PropFile>>`
- `strew`: `_gizlang_sdk_core.Option<Vec<M203.Strew>>`
- `start`: `_gizlang_sdk_core.Option<Vec<f64>>`

### `Rules3D`

```gizlang
type Rules3D = { things?: Vec<Thing3D>; props?: (game: Game) => Vec<Prop3D> throws string; under?: (picture: Picture, scene: Scene) => void throws string; hud?: Vec<Widget>; sky?: (game: Game, time: f64) => Environment; }
```

What a game's code gives a map (scene): its THINGS and PROPS beside the file's, what it draws of its own each frame
(UNDER), its HUD's widgets, and a SKY in place of the file's.

- `things`: `_gizlang_sdk_core.Option<Vec<M203.Thing3D>>`
- `props`: `_gizlang_sdk_core.Option<(arg0: Ref<M189.Game>) => Vec<M203.Prop3D> throws string>`
- `under`: `_gizlang_sdk_core.Option<(arg0: Ref<M203.Picture>, arg1: Ref<M203.Scene>) => void throws string>`
- `hud`: `_gizlang_sdk_core.Option<Vec<(arg0: Ref<M203.Hud>) => void throws string>>`
- `sky`: `_gizlang_sdk_core.Option<(arg0: Ref<M189.Game>, arg1: f64) => gizlang_meshdraw.Environment>`

## Functions

### `bearing`

```gizlang
function bearing(degrees: f64): f64
```

The yaw that turns a model, whose front faces +z, to face the compass BEARING in degrees (180: south, +z).

Effects: fail.

### `placeOf`

```gizlang
function placeOf(at: Vec<f64>, height: (x: f64, z: f64) => f64): Point3
```

The place AT of a file: [x, z] at HEIGHT's ground, or [x, y, z].

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

### `files`

```gizlang
function files(game: Game): Vec<string> throws string
```

Every file of GAME's world (Game.world): its own, and each map's with what it extends. A host gives them to a page.

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

### `text`

```gizlang
function text(game: Game, map: i64): string throws string
```

The file of map MAP of GAME's world, with what it extends (JSON): a game reads its own fields of it.

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

### `mapOf`

```gizlang
function mapOf(game: Game, map: i64): MapFile throws string
```

Map MAP of GAME's world, read.

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

### `heightOf`

```gizlang
function heightOf(m: MapFile, x: f64, z: f64): f64
```

The height of the ground of the map M at X, Z: its relief, 0 without one.

Effects: fail, alloc.

### `startOf`

```gizlang
function startOf(game: Game, map: i64): Point3 throws string
```

Where the player starts on map MAP of GAME (MapFile start), at the origin without one.

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

### `scene`

```gizlang
function scene(m: MapFile, rules: Rules3D): Scene3D
```

The world (Scene3D) of the map file M with the game's RULES.

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

### `charted`

```gizlang
function charted(game: Game, rules: (map: i64) => Rules3D throws string): (map: i64) => Scene3D throws string
```

The worlds of GAME's maps (play3D): each map's file with the RULES the game gives it.

Effects: fail, alloc.

