# gizapp/play

a surface program in a window of the desktop. It is the native twin of the page's <giz-surface> (app/components/src/surface.js): the same exports (initialize, frame, snapshot, restore, cues) get the same JSON and give the same gizlang/render packets, which gizlang/webgpu runs on the machine's GPU straight into the window. So one game module plays in a browser as WebAssembly and here as a native program, with no change. As in a browser, a frame is drawn each time the display refreshes: the wait for the display (FIFO) paces the loop, so no frame is shown twice or skipped against the screen.

Keys reach the program by the web's KeyboardEvent.code (gizlang/window keyCode), the pointer as pointer events at coordinates from 0 to 1, as a page gives them. F5 saves the program's snapshot in its application folder and F9 loads it back, as the page's Save and Load do in the browser's storage.

```gizlang
import * as Play from "gizapp/play";
```

## Types

### `Program`

```gizlang
type Program = { initialize: (input: bytes) => bytes; frame: (input: bytes) => bytes; snapshot: (input: bytes) => bytes; restore: (input: bytes) => bytes; cues?: (input: bytes) => bytes; file?: (input: bytes) => bytes; }
```

A surface program: its exports, as the page's surface calls them. CUES is optional: the sounds a frame asks for.

- `initialize`: `(arg0: bytes) => bytes`
- `frame`: `(arg0: bytes) => bytes`
- `snapshot`: `(arg0: bytes) => bytes`
- `restore`: `(arg0: bytes) => bytes`
- `cues`: `_gizlang_sdk_core.Option<(arg0: bytes) => bytes>`
- `file`: `_gizlang_sdk_core.Option<(arg0: bytes) => bytes>`

### `Options`

```gizlang
type Options = { title: string; app: string; width: i64; height: i64; sounds: Vec<File>; files?: Vec<File>; }
```

The window: its title, the application's name (its desktop file and its folder of saves), its first size, the
program's sounds and its files.

- `title`: `string`
- `app`: `string`
- `width`: `i64`
- `height`: `i64`
- `sounds`: `Vec<M128.File>`
- `files`: `_gizlang_sdk_core.Option<Vec<M128.File>>`

### `Game`

```gizlang
type Game = { title: string; app: string; port: i64; color: string; label: string; help: string; lock: string; sounds: Vec<File>; program: Program; }
```

A game as one host runs it: its TITLE, its APP name (the folder of its files and the name of its save), the PORT
and theme COLOR of its page, the LABEL of its surface, the HELP its page shows, the text of its assets LOCK, its SOUNDS (made
once) and its PROGRAM.

- `title`: `string`
- `app`: `string`
- `port`: `i64`
- `color`: `string`
- `label`: `string`
- `help`: `string`
- `lock`: `string`
- `sounds`: `Vec<M128.File>`
- `program`: `M133.Program`

## Functions

### `locked`

```gizlang
function locked(text: string): Vec<File> throws string
```

The files of the assets lock TEXT (gizlang/catalog), from the shared cache: fetched once, checked by hash. A game
imports its lock as text (`import {text as lock} from "./assets.lock"`), so it runs from any folder.

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

### `play`

```gizlang
function play(program: Program, options: Options): i64
```

Runs PROGRAM in a window until it closes: 0, or 1 after saying why it could not run.

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

### `shot`

```gizlang
function shot(program: Program, files: Vec<File>, frames: i64, keys: Vec<string>, width: i64, height: i64): bytes throws string
```

A picture of PROGRAM after FRAMES frames at WIDTH x HEIGHT with KEYS held, drawn with no window: a PNG. The frames
are 1/60 s apart whatever the GPU's speed, so one shot of one build is the same picture each time. An agent that
builds a game looks at it this way, and so does a test.

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

### `host`

```gizlang
function host(game: Game): i64
```

Runs GAME in a window of the desktop on this machine's GPU or, with --web, serves its page (gizapp/surface serve) on
its port or `--port N`.
With `--shot PATH` it writes a PNG of its frame instead (shot), after `--frames N` (60), with `--keys K,K` held (the
web's key codes) at `--size WxH` (1280x720).

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

