# gizgame/scene

```gizlang
import * as Scene from "gizgame/scene";
```

## Types

### `Prefab`

```gizlang
type Prefab = { schema: string; entities: Vec<Entity>; parents: Vec<Entity>; data: Vec<Vec<Data>>; }
```

A captured subtree. Entity references inside its fields are remapped when instantiated.

- `schema`: `string`
- `entities`: `Vec<M186.Entity>`
- `parents`: `Vec<M186.Entity>`
- `data`: `Vec<Vec<M186.Data>>`

### `History`

```gizlang
class History { private undoing: Vec<Revision> = []; private redoing: Vec<Revision> = []; private budget: i64; private used: i64 = 0; private current: string = ""; constructor(budget: i64 = 67108864) { assert(budget> 0); this.budget = budget; } private admit(state: bytes): void throws string { if (this.current !== "" && fingerprint(state) !== this.current) { throw "World changed outside its history; reset history"; } } commit(world: World, label: string, edit: (world: World) => void throws string): void throws string { if (label === "") { throw "An edit needs a label"; } const revision = world.transaction((own: World, before: bytes): Revision throws string => { this.admit(before); edit(own); const after = own.snapshot(); if (before.length+after.length> this.budget) { throw "Edit exceeds history memory budget"; } return { label, before, after }; }); const before = revision.before; const after = revision.after; if (before === after) { return; } for (const undone of this.redoing) { this.used - = undone.before.length + undone.after.length; } this.redoing = []; const size = before.length + after.length; while (this.used + size> this.budget) { const old = this.undoing[0]; this.undoing = this.undoing.slice(1); this.used - = old.before.length + old.after.length; } this.undoing.push(revision); this.used + = size; this.current = fingerprint(after); } undo(world: World): bool throws string { this.admit(world.snapshot()); if (this.undoing.length === 0) { return false; } const revision = this.undoing[this.undoing.length - 1]; world.restore(revision.before); this.undoing.pop(); this.redoing.push(revision); this.current = fingerprint(revision.before); return true; } redo(world: World): bool throws string { this.admit(world.snapshot()); if (this.redoing.length === 0) { return false; } const revision = this.redoing[this.redoing.length - 1]; world.restore(revision.after); this.redoing.pop(); this.undoing.push(revision); this.current = fingerprint(revision.after); return true; } reset(world: World): void { this.undoing = []; this.redoing = []; this.used = 0; this.current = fingerprint(world.snapshot()); } }
```

An editor's bounded history of atomic World edits; no parallel component or inspector model.

- `undoing`: `Vec<M183.Revision>`
- `redoing`: `Vec<M183.Revision>`
- `budget`: `i64`
- `used`: `i64`
- `current`: `string`

### `Scalar`

```gizlang
type Scalar = { component: i64; field: i64; lane: i64; name: string; kind: string; value: string; }
```

One scalar of the World's existing component schema, projected for an editor or debugger. VALUE is exact text.

- `component`: `i64`
- `field`: `i64`
- `lane`: `i64`
- `name`: `string`
- `kind`: `string`
- `value`: `string`

## Functions

### `capture`

```gizlang
function capture(world: World, root: Entity): Prefab throws string
```

Captures ROOT and its descendants in stable entity order. Root's external parent is intentionally omitted.

Effects: fail, read, alloc.

### `instantiate`

```gizlang
function instantiate(world: World, prefab: Prefab, parent: Entity = absent()): Vec<Entity> throws string
```

Instantiates through the World's ordinary validation. Any failure restores the original world atomically.

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

### `serialize`

```gizlang
function serialize(world: World, root: Entity): bytes throws string
```

Stores a subtree with the existing canonical World snapshot format, not another scene wire protocol.

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

### `deserialize`

```gizlang
function deserialize(world: World, data: bytes): Prefab throws string
```

Reads a single-root prefab against the destination schema without mutating the destination World.

Effects: fail, read, write, alloc.

### `constructor`

```gizlang
constructor(budget: i64 = 67108864)
```

The most snapshot bytes retained. One edit larger than the budget is refused before it can commit.

Effects: fail, read, write, alloc.

### `fingerprint`

```gizlang
function fingerprint(state: bytes): string
```

A deterministic state checksum for same-build replay comparisons.

Effects: fail, alloc.

### `inspect`

```gizlang
function inspect(world: World, entity: Entity): Vec<Scalar> throws string
```

Projects a live entity's fields without retaining a second component model.

Effects: fail, read, alloc.

### `edit`

```gizlang
function edit(world: World, entity: Entity, component: i64, field: i64, lane: i64, text: string): void throws string
```

Edits a scalar using its authoritative schema and World's ordinary validation. History.commit supplies undo/redo.

Effects: fail, read, write, alloc.

## Methods

### `History.commit`

```gizlang
commit(world: World, label: string, edit: (world: World) => void throws string): void throws string
```

Runs EDIT as one undoable operation. Failure or budget exhaustion restores the original state.

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

### `History.undo`

```gizlang
undo(world: World): bool throws string
```

Undoes one edit. False means the history is empty, not that validation failed.

Effects: fail, read, write, alloc.

### `History.redo`

```gizlang
redo(world: World): bool throws string
```

Reapplies the most recently undone edit.

Effects: fail, read, write, alloc.

### `History.reset`

```gizlang
reset(world: World): void
```

Starts a new edit history after loading or replacing a scene.

Effects: fail, read, write, alloc.

