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, Nebula, Skyshard and 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 and Outpost, online worlds, use this form.
The game package's README 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
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.jsonThe program names the world file and the type of the game's own fields:
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
extendsone 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'sdefaultsgive 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).--checkchecks 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 eachlocales/TAG.jsonof the game's folder to the game, which speaks it.
Gizlang values
The program writes the same Atlas, Map3D and Rules and declares them:
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.groundsgives an online world each map's solid world and navigation mesh;shotsdraws a first-person shooter's shots. Outpost declares seven arenas this way.- A kind may hold code beside its data: its
hiteffects run before itscues.hit. - The rules given to
Rules.ruledhold 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) 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) 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.