GizStackGizStack
View .mdOpen in ChatGPTOpen in Claude

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

PartTypeSays
The worldAtlas (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 kindKindIts 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 mapMap3D (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 rulesRules (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
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
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 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) 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.