# Games

A game on `gizgame` is a declaration: what its world holds, what its kinds of actors are and do, and its rules. The
engine runs the declaration in fixed ticks, the same in a window and in a page. A game writes the declaration in one of
two forms. Both forms are the same Gizlang types, so the type checker reads both, and the engine applies both by one
path (`Game.declare`):

- **Data files**: JSON files in the game's folder. The host reads and checks them at each start, so a change, or a
  new map (a mod), needs no build. [Village](https://github.com/gizai/gizlang/tree/main/examples/games/village/),
  [Nebula](https://github.com/gizai/gizlang/tree/main/examples/games/nebula/), [Skyshard](https://github.com/gizai/gizlang/tree/main/examples/games/skyshard/) and
  [Emberwood](https://github.com/gizai/gizlang/tree/main/examples/games/emberwood/) use this form.
- **Gizlang values**: the same records written in the program. A value may compute (a function makes one kind of being
  for each rig) and may hold code (an effect that no data can say). A change needs a build.
  [Hollowmere](https://github.com/gizai/gizlang/tree/main/examples/games/hollowmere/) and [Outpost](https://github.com/gizai/gizlang/tree/main/examples/games/outpost/), online worlds, use this form.

The [game package's README](https://github.com/gizai/gizlang/blob/main/game/README.md) lists the modules. Each type's doc comment says each of its fields.

## The declaration

| Part | Type | Says |
| --- | --- | --- |
| The world | `Atlas` (gizgame) | The title, the maps, the help, the settings, the controls (`sticks`, `actions`, `buttons`), the particles, the sounds, the soundtrack, the kinds, a 2D `arena`, the 2D `picture` (`Picture2D`: images, a crosshair, a `backdrop` of tiles, each map's clouds, stars and a grid) and the `flow` |
| A kind | `Kind` | Its body, its team, its look (2D) or figure (3D), its speeds, its brain, its `moves` (acts: `twinStick`, `topDown`, `steer`, `spin`, `gun`) and its `cues` (effects as data: a sound, a shake, a burst, a recoil, a stun, a score, a split, the end) |
| A 3D map | `Map3D` (gizgame/maps) | The ground and its `relief` or eroded `land`, the sky, the eye, the models, the sets, the props, the plants a `strew` grows (in a biome), a `town` or a `plan` of tiles (an arena's walls by a Procgen `Layout`), named `spots` and the props `placings` put there, the `lamps` and the `ambient` motes (`when` "night" or "day"), the `gravity`. The kind the eye follows starts at the map's `start` |
| The rules | `Rules` (gizgame/rules) | Counters, a haul of items to carry to one of the map's spots, spawners, waves, actors kept (`keeps`), `sites` that light (on a ring about a spot or scattered; lit by paying a value or by the haul), with flames, light and sparks, a `glow` over an actor, the match (combo, lose, win), triggers, the HUD and the end's words |

Rules have no expression language. A value is a name (`Game.value`): a counter, `score`, `wave`, `combo`, `#KIND`
(the actors of a kind) or `ready:KIND` (how ready its dash or gun is). A value that changes is a `Grows`: from a
start, by an amount for each unit of a value (a kind's brain `pace` is one), up to a most. Triggers run in the file's
order, and each trigger's actions run in their order. What data
cannot say is a hook: the program registers an effect by name (`Game.hook`), and an action names it. A name that no
program registered stops the load.

## Data files

```text
examples/games/village/
  game.giz            the program: the game, its host, and code for what data cannot say
  world.json          an Atlas, and the game's own fields that hold for every map (its rules, for one)
  maps/NAME.json      a Map3D, and the map's own fields (its rules)
  mixins/NAME.json    what maps share
  locales/TAG.json    the translations (each English text to its translation)
  world.schema.json   the schemas that an editor reads ($schema), written at each start (not in git)
  maps.schema.json
```

The program names the world file and the type of the game's own fields:

```typescript gizlang
import {Game, Maps, Rules, play3D} from "gizgame";
import {schema} from "gizlang/json";

const village: Game=Rules.ruled(new Game(60,20261120).world("world.json",schema<Rules.Fields>()).solid(110).mouseLook(),["goblin"]);
export const play=play3D(village,Maps.charted(village,Rules.scene(village)));
```

- A map's file `extends` one file or a list of mixins, in order: its own fields go over theirs. Objects merge, and
  lists of named items merge by name. A file's `defaults` give each item of a list what the item does not say.
- Points are `[x, y, z]` in meters. A record of plain numbers may be written as an array of its fields.
- The host checks every file against its type at each start and stops at the first file that breaks it, with the
  place (`maps/court.json: $.sets[0].fiel: no such field`). `--check` checks and stops. Each start writes the two
  schema files from the types where they changed; git keeps neither, so they never go stale.
- The title is the world file's `title`. The host gives each `locales/TAG.json` of the game's folder to the game,
  which speaks it.

## Gizlang values

The program writes the same `Atlas`, `Map3D` and `Rules` and declares them:

```typescript gizlang
import {Game, Atlas, Map3D, Scene3D, Rules, Settings, play3D} from "gizgame";

const SEED: i64=20261118;
const WORLD: Atlas={ title: "Hollowmere", maps: [], settings: [...Settings.COMMON,"Day and night"] };
const VALLEY: Map3D={ sky: { day: 360 }, ground: { side: 256, samples: 129, materials: ["Ground054","Ground037","Rock030"],
        rules: { sand: 0.3, rock: 14, slope: 0.3, blend: 0.8 }, land: { seed: SEED, size: 256, spacing: 2, erode: 4000, flat: 48 } },
    town: { seed: SEED, models: { house: ["building_home_A_blue"], hall: ["building_castle_blue"] }, road: "road" },
    spots: { square: { at: [0,6] }, hall: { before: "building_castle_blue" }, graves: { rings: { count: 12, per: 4, radius: 72, step: 5 } } },
    placings: [{ kind: "grave", spot: "graves", solid: 1 }] };
const RULES: Rules.Rules={ triggers: [{ name: "horn", when: { start: true }, do: [{ play: "start" }] }] };
const hollowmere=Rules.ruled(new Game(30,SEED).declare(WORLD),[],RULES);
export const play=play3D(hollowmere,(map): Scene3D => ({ map: VALLEY }));
```

- A point is `point3(x, y, z)`, not an array.
- `spotsOf(map)` gives a map's named spots (a plan's rooms are "rooms"), so the code puts its beings where the map says. `grounds`
  gives an online world each map's solid world and navigation mesh; `shots` draws a first-person shooter's
  shots. [Outpost](https://github.com/gizai/gizlang/tree/main/examples/games/outpost/) declares seven arenas this way.
- A kind may hold code beside its data: its `hit` effects run before its `cues.hit`.
- The rules given to `Rules.ruled` hold for each map whose files give none.
- An online world (gizgame/online) builds its realm on the room's thread from the program's values, so its
  declaration is in the program.

## Which form

Use data files for what a designer or a modder changes: maps, kinds, numbers, sounds, words. Use Gizlang values when the
declaration computes, or when the game is online. A game may use both: its world file, and a kind's code in the
program under the same name (`Game.kinds`). The file's data joins the program's kind field by field, and the program's
effects run before the file's cues.

## Serving

A game's program serves itself: `--web` serves its page and its room on its port. A server of several games
([arcade](https://github.com/gizai/gizlang/tree/main/examples/games/arcade/)) serves each game on its own host name, and a cluster of such servers serves
any number of games from any number of workers and hosts:
`giz games deploy CLUSTER.json` ([gizgame/cluster](https://github.com/gizai/gizlang/blob/main/game/cluster.giz)) reads a cluster file (its hosts, its workers with the games
and rooms of each, and its gateway), builds one release, starts it beside the live one, switches the gateway
(gizlang/gateway) to it once every worker answers, and keeps the one before for `rollback`. A game's room runs on one
worker; its pages come from every worker that serves it.
