singe/docs/ForgeVocabulary.adoc
2026-09-14 14:20:17 -05:00

687 lines
21 KiB
Text

// Generated by util/forgeVocabulary.lua from assets/Forge/Author.singe. Do not edit.
=== Layers
[cols="1,3,2"]
|===
| Name | What it does | Parameters
| `bezel`
| The arcade score panel around the picture, showing the vars score (and score2), lives (and lives2), and credits as they change.
| `twin` (boolean)
| `disc`
| The video the game is played over. The file is what the editor scrubs; games.dat names it when the game runs.
| `file` (file), `start` (number)
| `hud`
| An RmlUi document over everything. bind maps element ids to game vars, refreshed as they change.
| `bind` (table), `document` (file)
| `music`
| A track that plays from the start, looping.
| `file` (file), `volume` (number)
| `overlay`
| Flat drawing over everything: sprites, scores, prompts.
| --
| `parser`
| A text parser, the Sierra way: a prompt the player types at, and words the game knows. What is typed raises the said event.
| `ignore` (table), `prompt` (string), `words` (table)
| `scene3d`
| The 3D scene: physics in three axes, a sun, a sky, fog. Positions are world units.
| `ambient` (table), `exposure` (number), `fog` (table), `fov` (number), `gravity` (number), `sky` (file), `sun` (table)
| `world2d`
| A flat world with gravity: physics in the XY plane, drawn into the overlay.
| `gravity` (number)
|===
=== Looks
[cols="1,3,2"]
|===
| Name | What it does | Parameters
| `billboard`
| A sprite in the scene, always facing the camera: a tree, a puff, a health bar.
| `d` (number), `file` (file), `h` (number), `height` (number), `w` (number)
| `box`
| A filled rectangle, centred on the instance -- or standing on it, with anchor feet.
| `anchor` (string), `b` (number), `g` (number), `h` (number), `r` (number), `w` (number)
| `grid`
| A map of tiles from a sheet, its top left at the instance: columns is the sheet's width in tiles, tile the tile's size, map the rows of tile numbers (1 is the first; 0 is empty), rows separated by semicolons.
| `columns` (number), `file` (file), `map` (string), `tile` (number)
| `light`
| A point or spot light, or a sun, on the instance.
| `b` (number), `g` (number), `intensity` (number), `r` (number), `range` (number), `shadow` (boolean), `type` (string)
| `mesh`
| A box, sphere, cylinder, or plane with a colour or a texture. Floors, walls, crates, targets. An occluder is not seen but hides what is behind it: a pillar that is only in the painting.
| `b` (number), `d` (number), `g` (number), `h` (number), `metallic` (number), `occluder` (boolean), `r` (number), `roughness` (number), `shape` (string), `texture` (file), `unlit` (boolean), `w` (number)
| `model`
| A glTF model under the instance, scaled and turned, playing a clip. w, h, d say how big it counts as.
| `clip` (string), `d` (number), `file` (file), `h` (number), `rx` (number), `ry` (number), `rz` (number), `scale` (number), `w` (number)
| `none`
| Nothing drawn: a trigger, a spawner, a hitbox over video, a camera.
| `d` (number), `h` (number), `w` (number)
| `particles`
| A steady stream of particles from the instance: a fire, smoke, a thruster, rain. Colour, size, speed, and life as an emitter takes them.
| `b` (number), `g` (number), `gravity` (number), `life` (number), `r` (number), `rate` (number), `size` (number), `speed` (number), `spread` (number)
| `sprite`
| An image, centred on the instance -- or standing on it, with anchor feet. frames splits a sheet into that many columns; the var frame picks one. The var angle turns it, starting from the entity's rz. faces says which way the art looks (right unless said, or none): while the var facing is the other way the image is mirrored, so art drawn one way walks both.
| `anchor` (string), `faces` (string), `file` (file), `frames` (number)
| `text`
| A line of text, its top left at the instance. The var text is what it says.
| `b` (number), `g` (number), `r` (number), `text` (string)
| `text3d`
| A line of text standing in the scene. The var text is what it says.
| `height` (number), `text` (string)
|===
=== Behaviours
[cols="1,3,2"]
|===
| Name | What it does | Parameters
| `animator`
| A clip per state: idle, walk, attack, hit, dead, or any state a rule sets. A clip that does not loop raises animationDone when it ends.
| `attack` (string), `dead` (string), `fade` (number), `hit` (string), `idle` (string), `loop` (string), `walk` (string)
| `body`
| A thing physics moves: a crate, a ball, debris. Mass, bounce, friction, and buoyancy as Jolt takes them.
| `bounce` (number), `buoyancy` (number), `friction` (number), `mass` (number), `shape` (string)
| `branching`
| Dragon's Lair: a track of branches, each a disc frame window, the move it wants, and where the disc goes on success and on failure. Raises branchTaken and branchMissed.
| `track` (track)
| `camera`
| The scene is drawn from this instance. fixed looks at a point; follow keeps an offset from a target; first sits on a target's eyes and the mouse looks; orbit circles a target; rail rides a track of points with stops.
| `eye` (number), `lag` (number), `lookX` (number), `lookY` (number), `lookZ` (number), `mode` (string), `target` (string), `track` (track), `x` (number), `y` (number), `z` (number)
| `character`
| Walks, falls, and jumps in the scene: the engine's character controller. Moves by the vars dx and dy, relative to the camera.
| `height` (number), `jump` (number), `radius` (number), `speed` (number)
| `drift`
| Moves steadily, for a cloud, a platform, or a target.
| `vx` (number), `vy` (number)
| `frames`
| Steps a sprite look's frame: a range of frames per state, as "idle=1-1, walk=2-5", at a rate a second. A sheet drawn facing both ways names the other way's frames stateLeft or stateRight (walkLeft), used while the var facing is that way instead of mirroring the look.
| `fps` (number), `states` (string)
| `gun`
| The pointer as a gun for one player: a press of the trigger raises hit on what is under it, or miss. Ammo counts down; a shot off the screen reloads. With aim centre it fires from the middle of the picture -- a first-person gun.
| `aim` (string), `ammo` (number), `player` (number), `reload` (string), `trigger` (switch)
| `health`
| The var health; the damage action lowers it, and at zero the instance raises death and is destroyed unless keep is set. With ragdoll, a model falls limp instead and goes after linger seconds.
| `keep` (boolean), `linger` (number), `max` (number), `ragdoll` (boolean)
| `hitbox`
| The instance's hit shape comes from a track of boxes keyed by disc frame or time; between keys it is interpolated, outside them there is none.
| `track` (track)
| `hotspot`
| Something a verb can be used on: a name for the sentence line, a place to walk to first, and a polygon (x,y pairs) when its look's box will not do.
| `name` (string), `polygon` (table), `walkX` (number), `walkY` (number), `walkZ` (number)
| `joint`
| Joins this body to another's -- or to the world, with no other -- by a hinge, a ball, or a slider through a world point along an axis.
| `ax` (number), `ay` (number), `az` (number), `dx` (number), `dy` (number), `dz` (number), `other` (string), `type` (string)
| `keys`
| Reads a player's keys into the vars dx and dy (-1 to 1) and fire, so rules and movers read intent rather than hardware.
| `down` (scancode), `fire` (scancode), `left` (scancode), `player` (number), `right` (scancode), `up` (scancode)
| `mover`
| Moves by the vars dx and dy at a speed, kept on the screen when clamp is set. Pair it with keys.
| `clamp` (boolean), `speed` (number)
| `patrol`
| Walks a list of points in turn -- a creep's lane, a guard's round -- looping or stopping, and raises patrolEnd at the last.
| `loop` (boolean), `points` (table)
| `platformer`
| Runs, falls, and jumps: the engine's character controller in 2D. Rules say which way with run and jump.
| `jump` (number), `speed` (number)
| `projectile`
| Flies at a velocity and is dropped past the edge (or far away, in 3D) or after life seconds. With aim, a sprite turns to point the way it flies.
| `aim` (boolean), `life` (number), `vx` (number), `vy` (number), `vz` (number)
| `racer`
| Drives a vehicle round a track of points on its own: steering toward the next, throttling by how straight the road is.
| `reach` (number), `throttle` (number), `track` (track)
| `seek`
| Moves straight toward a target -- an entity's id, or "camera" -- and raises arrived within stopAt of it.
| `fly` (boolean), `speed` (number), `stopAt` (number), `target` (string)
| `shooter`
| Spawns a kind from an offset while the var fire is set (or always, with auto), no faster than the rate.
| `auto` (boolean), `offsetX` (number), `offsetY` (number), `rate` (number), `spawns` (kind)
| `soft`
| A mesh look made soft: a cloth, or a body inflated to a pressure.
| `mass` (number), `pressure` (number), `stiffness` (number), `type` (string)
| `solid`
| Immovable ground or a wall, in a world2d or a scene3d room. With moving, a body that follows wherever the instance is moved -- a paddle, a lift.
| `moving` (boolean)
| `sound`
| A clip per event: spawn, hit, death, or any event the instance sees. Values are file names. volume is the clips' own, 0 to 100, under the game's.
| `death` (file), `hit` (file), `pressed` (file), `spawn` (file), `volume` (number)
| `spawner`
| Makes instances of a kind every so many seconds at its own position or at one of its points, up to max alive at once and total in all.
| `every` (number), `max` (number), `pick` (string), `points` (table), `spawns` (kind), `total` (number)
| `spin`
| Turns steadily: the var angle in 2D (a sprite turns with it), the node about Y in 3D, in degrees a second.
| `rate` (number)
| `target`
| Something a gun can hit. In 2D its look's box; in 3D a body the size of its look, plus zones -- boxes on named bones, so a shot says which part it hit.
| `zones` (table)
| `thrust`
| A body pushed along its nose by the var dy and turned by dx: a hovercraft, a ship, a plane without lift.
| `force` (number), `turn` (number)
| `timer`
| Raises the timer event with its name after some seconds, or every so many. start false waits for timerStart.
| `after` (number), `every` (number), `name` (string), `start` (boolean)
| `trigger`
| A volume that reports what enters and leaves it, as the enter and leave events. A checkpoint, a doorway, a prize.
| --
| `turret`
| Fires at the nearest instance of a kind within range, no faster than the rate: spawns a projectile aimed at it, or, with no projectile, does the damage itself.
| `damage` (number), `range` (number), `rate` (number), `spawns` (kind), `speed` (number), `targets` (kind)
| `vehicle`
| A car, motorcycle, tank, or boat on the engine's vehicle physics, driven by the vars dy (throttle, up is forward) and dx (steering) from keys. Wheels hang at the four corners the sizes say; a boat needs none.
| `mass` (number), `radius` (number), `suspension` (number), `thrust` (number), `torque` (number), `type` (string), `wheelX` (number), `wheelZ` (number), `width` (number)
| `walker`
| Walks the room's walk areas (2D) or its floors (3D) on the navigation mesh: walkTo sends it, a click on the floor can, follow keeps it after an entity (or the camera), and it raises arrived. Its state is walk or idle as it goes.
| `every` (number), `follow` (string), `radius` (number), `speed` (number), `stopAt` (number)
| `water`
| Fills a mesh look with water: its top is the surface, and bodies inside float or sink by their buoyancy.
| `density` (number), `drag` (number)
|===
=== Events
[cols="1,3,2"]
|===
| Name | What it does | Parameters
| `animationDone`
| A clip that does not loop ended on self; event.state says which state it was for.
| `kind` (kind), `state` (state)
| `arrived`
| A seeking instance reached its target.
| `kind` (kind)
| `branchMissed`
| The window closed without the move and the disc went to the fail frame.
| --
| `branchOpen`
| A branch's window opened; event.move says what it wants.
| --
| `branchTaken`
| The move was made in time and the disc went to the success frame.
| --
| `collision`
| An instance of kind a began touching one of kind b (self is a, other is b).
| `a` (kind), `b` (kind)
| `death`
| self's health reached zero.
| `kind` (kind)
| `enter`
| An instance of kind b entered a trigger of kind a (self is the trigger, other what entered).
| `a` (kind), `b` (kind)
| `frame`
| Every frame.
| --
| `frameReached`
| The disc passed a frame.
| `frame` (number)
| `gameOver`
| The game ended.
| --
| `hit`
| A gun shot landed on self; other is the gun.
| `kind` (kind), `player` (number)
| `leave`
| An instance of kind b left a trigger of kind a.
| `a` (kind), `b` (kind)
| `midi`
| A MIDI note came in on the port the game opened; event.pitch and event.velocity say which and how hard. (pitch, since note is what a rule's comment is called.)
| `pitch` (number)
| `miss`
| A gun shot hit nothing; self is the gun. event.offscreen says whether it left the screen.
| `player` (number)
| `patrolEnd`
| A patrolling instance reached the last of its points.
| `kind` (kind)
| `pressed`
| A key or a switch went down.
| `key` (scancode), `player` (number), `switch` (switch)
| `railEnd`
| A rail camera reached the end of its track.
| --
| `released`
| A key or a switch came up.
| `key` (scancode), `player` (number), `switch` (switch)
| `roomEnd`
| A room is about to be left.
| `room` (room)
| `roomStart`
| A room has been entered.
| `room` (room)
| `said`
| A line was typed at the parser: its verb, noun, and second noun as the words table knows them, or unknown for a word it does not. The most specific rule wins.
| `noun` (string), `second` (string), `verb` (string)
| `spawn`
| self has just been made.
| `kind` (kind)
| `stopped`
| A rail camera reached a stop; event.name says which. pathNext moves it on.
| `name` (string)
| `timer`
| A timer on self went off; event.name says which.
| `kind` (kind), `name` (string)
| `verb`
| A verb was used on a hotspot (self), with an item or not: "use key on door". The most specific rule wins.
| `item` (string), `target` (string), `verb` (string)
|===
=== Conditions
[cols="1,3,2"]
|===
| Name | What it does | Parameters
| `below`
| An instance has fallen past a line -- a pit, or the bottom of the screen.
| `entity` (entity), `y` (number)
| `chance`
| True with a probability, 0 to 1.
| `p` (number)
| `discBetween`
| The disc is between two frames -- the window a QTE is answered in.
| `from` (number), `to` (number)
| `every`
| True once every so many seconds, for a rule that fires steadily.
| `seconds` (number), `tag` (string)
| `has`
| The inventory holds an item.
| `item` (string)
| `hitPart`
| The shot landed on a named zone of the target: head, weakspot.
| `part` (string)
| `hover`
| A player's pointer is over the named hotspot.
| `player` (number), `target` (string)
| `inState`
| An instance's state is this.
| `entity` (entity), `state` (state)
| `keyHeld`
| A key is down.
| `key` (scancode)
| `keyPressed`
| A key went down this frame.
| `key` (scancode)
| `onGround`
| A platformer has ground under it.
| `entity` (entity)
| `onScreen`
| An instance's box is at least partly on the overlay.
| `entity` (entity)
| `once`
| Only the first time this rule would run -- per instance and per room unless scope is "game".
| `scope` (string), `tag` (string)
| `pointerIn`
| A player's pointer is over an instance.
| `entity` (entity), `player` (number)
| `pointerOffscreen`
| A player's pointer is off the picture, which is how a light gun reloads.
| `player` (number)
| `switchHeld`
| A pad, gun, or mouse switch is down.
| `switch` (switch)
| `test`
| An expression is true: self.health <= 0, count("zombie") == 0, score > 1000.
| `expr` (expression)
| `timeBetween`
| The game is between two moments, in seconds.
| `from` (number), `to` (number)
| `touching`
| Two instances overlap.
| `entity` (entity), `other` (entity)
| `waiting`
| A rail camera is held at a stop.
| `entity` (entity)
|===
=== Actions
[cols="1,3,2,1"]
|===
| Name | What it does | Parameters | Waits
| `addScore`
| Add to the score.
| `amount` (number)
|
| `addVar`
| Add to a var on an instance, or on the game with no entity.
| `amount` (number), `entity` (entity), `name` (string)
|
| `cameraCut`
| Draw the scene from another camera instance.
| `entity` (entity)
|
| `credit`
| A coin: one more credit.
| --
|
| `damage`
| Take from an instance's health; at zero it dies.
| `amount` (number), `entity` (entity)
|
| `destroy`
| Remove an instance.
| `entity` (entity)
|
| `die`
| The Sierra death: a message, then the game starts over.
| `text` (expression)
| yes
| `discTo`
| Send the disc to a frame -- the branch a QTE takes.
| `frame` (number)
|
| `emit`
| A burst of particles at an instance: an explosion, sparks, a puff.
| `b` (number), `count` (number), `entity` (entity), `g` (number), `r` (number), `speed` (number)
|
| `face`
| Turn a walker to face left or right, or toward an instance.
| `direction` (string), `entity` (entity), `target` (entity)
|
| `fade`
| Fade the picture to black, or back (with out false), and wait.
| `out` (boolean), `seconds` (number)
| yes
| `flash`
| Flash the screen a colour.
| `b` (number), `g` (number), `r` (number), `seconds` (number)
|
| `gameOver`
| End the game: rules stop, the gameOver event fires, restart begins again.
| --
|
| `give`
| Put an item in the inventory.
| `item` (string)
|
| `goTo`
| Go to a room, taking the named entity along and placing it at a point there -- or where the entity called at stands in that room.
| `at` (string), `entity` (entity), `room` (room), `x` (number), `y` (number), `z` (number)
|
| `jump`
| Ask a platformer to jump.
| `entity` (entity)
|
| `loadGame`
| Bring a slot back.
| `slot` (number)
|
| `lookAt`
| Turn an instance toward another.
| `entity` (entity), `target` (entity)
|
| `lua`
| Anything the vocabulary cannot say. The way out, and it is meant to be used.
| `code` (lua)
|
| `moveTo`
| Put an instance somewhere.
| `entity` (entity), `x` (number), `y` (number), `z` (number)
|
| `nextVerb`
| Cycle to the next verb in the game's list.
| --
|
| `pathNext`
| Send a rail camera on from its stop.
| `entity` (entity)
|
| `playAnimation`
| Play a model's clip, once or looping.
| `clip` (string), `entity` (entity), `loop` (boolean)
|
| `playMusic`
| Play a track, looping.
| `file` (file)
|
| `playSound`
| Play a clip, at a volume of its own (0 to 100) under the game's.
| `file` (file), `volume` (number)
|
| `push`
| Shove a body, or a ragdoll's bone, along a direction.
| `bone` (string), `entity` (entity), `x` (number), `y` (number), `z` (number)
|
| `reload`
| Fill a gun's ammo.
| `entity` (entity)
|
| `restart`
| Begin the game again from its first room.
| --
|
| `run`
| Drive a platformer left (-1) or right (1) this frame.
| `direction` (number), `entity` (entity)
|
| `saveGame`
| Keep the whole game -- room, positions, vars, inventory -- in a numbered slot.
| `slot` (number)
|
| `say`
| Show a line for a while, and wait for it. With a hud it goes in the element called say; otherwise it is drawn.
| `seconds` (number), `text` (expression)
| yes
| `setState`
| Change an instance's state.
| `entity` (entity), `state` (state)
|
| `setText`
| Change what a text instance says.
| `entity` (entity), `text` (expression)
|
| `setVar`
| Set a var on an instance, or on the game with no entity.
| `entity` (entity), `name` (string), `value` (expression)
|
| `setVerb`
| Choose the verb the next click uses.
| `verb` (string)
|
| `shake`
| Shake the camera for a moment.
| `amount` (number), `seconds` (number)
|
| `show`
| Show or hide an instance.
| `entity` (entity), `visible` (boolean)
|
| `spawn`
| Make an instance of a kind at a point.
| `kind` (kind), `x` (number), `y` (number), `z` (number)
|
| `spawnAtPointer`
| Make an instance of a kind where the player's pointer is: on the overlay in 2D, on the floor the ray meets in 3D.
| `kind` (kind), `player` (number)
|
| `stopMusic`
| Stop the track that is playing.
| --
|
| `submitScore`
| Send the score to the master service's board for this game, queued until it can go.
| `board` (string)
|
| `take`
| Take an item out of the inventory.
| `item` (string)
|
| `talk`
| Run a dialogue from the game's dialogues, and wait for it to end.
| `dialogue` (string)
| yes
| `timerStart`
| Start a named timer on an instance.
| `after` (number), `entity` (entity), `name` (string)
|
| `useItem`
| Choose an inventory item for the next click: "use key on ...".
| `item` (string)
|
| `wait`
| Wait some seconds before the next action.
| `seconds` (number)
| yes
| `walkTo`
| Send a walker to a point, and wait until it gets there.
| `entity` (entity), `x` (number), `y` (number), `z` (number)
| yes
| `walkToHotspot`
| Send a walker to a hotspot's walk point (the one the verb was used on, with self), and wait.
| `entity` (entity), `target` (entity)
| yes
| `walkToPointer`
| Send a walker where the player's pointer is, and wait.
| `entity` (entity), `player` (number)
| yes
|===