demogolf · the verbs

this page as plaintext

The Course Studio and the game: the recipe’s ops, the brush, the editor, the scene’s objects, the round, live tuning, the guide’s voice, the console. 62 verbs in 10 categories: 14 undoable, 14 read-only. The app-verbs protocol (love-shared/docs/app-verbs.md): staros-tap demogolf verbs lists them live, staros-tap demogolf verb <name> '<json>' runs one, activity --since N reads the journal. Loaded headless from demogolf/console by scripts/verb_inventory.lua.

box

box.cmd — medium

Any verb of the file remote (demogolf’s own and the whitelisted starbox ones) by name, with its params object: the escape hatch for what has no typed verb (editor {ow = …}, sound_set, pad_tune, set_render_param, flow, water_src, probe_dump, census …). Captures (shot, screen_grab, burst_grab) answer later and are refused here. Ask before a world-replacing one (scene_load, world_load).

argument type notes
action string required
params object
staros-tap demogolf verb box.cmd '{"action": "…"}'

brush

brush.set — low, palette word brush

The editor’s brush (any subset): tool, r the radius 1-40, strength 1-12, falloff smooth | soft | hard, mat the material (‘own’ = the column’s own). What the keys 1-6, [ ], - =, F and M do. The editor must be open. Not an edit (no undo step).

argument type notes
falloff string one of smooth, soft, hard
mat string one of own, stone, soil, sand, crystal, ice, brick, water, lava
r integer minimum 1; maximum 40
strength integer minimum 1; maximum 12
tool string one of raise, lower, flatten, smooth, noise, paint, tee, core, gate, line, trench
staros-tap demogolf verb brush.set '{}'

brush.state — low, read-only

The brush as it is (tool, r, strength, falloff, mat) and the palette’s allowed values (tools, brushes, mats, falloffs, r_range, strength_range).

staros-tap demogolf verb brush.state '{}'

course

course.build — medium, palette word build

BUILD the course as a cartridge: carts/.cart in the save dir (cart.toml + content/recipe.lua, the reference checker’s report: the recipe, its entities’ scripts and pages, its sound, its library). Refuses while the studio’s PROBLEMS stand. -> { ok, dir, uri, digest, errors }

argument type notes
author string
licence string
name string
source string one of play-only, visible
title string
version string
staros-tap demogolf verb course.build '{}'

course.check — low, read-only

The determinism check: the device’s world against the canvas and a fresh re-bake of the recipe (digests, the probe’s diff); name bakes another course and compares it with the load. Slow (a re-bake).

argument type notes
name string
staros-tap demogolf verb course.check '{}'

course.entities — low, read-only

The course’s entities: each id, class, place, fields and output rows (the course’s own objects marked adapter), the classes’ inputs and outputs, and the PROBLEMS (a bad link, a script that does not parse).

staros-tap demogolf verb course.entities '{}'

course.entity — low, undoable

One gesture on the course’s ENTITIES (one undo step; no bake): add {class, at = [x,y,z] | box = [x0,y0,z0,x1,y1,z1], fields?, id?} -> id; set {id, field, value}; move {id, at | box}; remove {id}; link {id, on, to, input, delay?, args?} (an output row: when id announces on, to is told input); unlink {id, i}; output {id, i, on? | to? | input? | delay?}. Classes: sign, speaker, trigger, relay, counter, page, verb (and the course’s own: tee, hole, gateN, item:ID, region:ID, race, outputs only). course.entities lists them.

argument type notes
action string required; one of add, set, move, remove, link, unlink, output
args object
at any
box any
class string
delay number
field string
fields object
i number
id string
input string
label string
on string
to string
value any
staros-tap demogolf verb course.entity '{"action": "add"}'

course.fire — low

The live logic: entity id announces output now (its output rows queue; the fixed tick delivers them).

argument type notes
args object
id string required
output string required
staros-tap demogolf verb course.fire '{"id": "…", "output": "…"}'

course.inspect — low, read-only

A layer’s ops and their editable fields (what the inspector shows): rows of {kind = op | num | mat | bool, op (the op’s id), of (its kind), path, value}. Default: the active layer.

argument type notes
layer string
staros-tap demogolf verb course.inspect '{}'

course.layer — low, undoable

A layer: toggle it off or on, move it up (earlier) or down (later). Structural (re-bakes).

argument type notes
action string required; one of toggle, up, down
id string required
staros-tap demogolf verb course.layer '{"id": "…", "action": "toggle"}'

course.library — low, undoable

The course’s LIBRARY of stamps (a box of cells captured) and prefabs (ops grouped in a local frame, every instance linked): list; stamp {box = [x0,y0,z0,x1,y1,z1], name?} captures; group {ops = [op ids] | ids = [[layer, op]…], name?} groups them into ONE prefab op; remove {kind, name}; place {kind, name, at = [x,y,z], opaque?} (or course.op {op = {op = ‘stamp’ | ‘prefab’, name, at}}). Each is one undo step (a re-bake).

argument type notes
action string required; one of list, stamp, group, remove, place
at any
box any
ids any
kind string one of stamp, prefab
name string
opaque boolean
ops any
staros-tap demogolf verb course.library '{"action": "list"}'

course.logic — low

The live logic’s state (the tick, the pending deliveries, the running scripts, the last says, the page showing, the question pending); tick = N steps it N ticks by hand (a paused box), reset re-arms it.

argument type notes
reset boolean
tick number minimum 0; maximum 3600
staros-tap demogolf verb course.logic '{}'

course.op — low, undoable

Apply one op to the active layer as one undo step: {op = {op = , …}}. Primitives: fill {box = [x0,y0,z0,x1,y1,z1], mat}, erase {box}, sphere {c = [x,y,z], r, mat}, stroke {tool, r, strength, falloff, mat, dabs = [x1,z1,x2,z2,…]}, trench {a, b, width, depth}. Generators (ground, wall, ramp, plateau, mound, lake {c, rx, rz, depth, freeboard, bed}, rocks, border, markers, valley) are STRUCTURAL: the whole course re-bakes (hundreds of ms). Coordinates are cells; y grows DOWN (0 is the sky). The op’s id comes back.

argument type notes
op object required
staros-tap demogolf verb course.op '{"op": {}}'

course.param — low, undoable

Set one field of an op in place (a generator’s parameter, a stroke’s radius): op the op’s id, path the field (‘depth’, or ‘c.2’ for an array element), value a number, a material name or a boolean; layer the layer’s id (default: the active layer). Structural: the course re-bakes; changes to one field within 0.8 s merge into one undo step. course.inspect lists the fields.

argument type notes
layer string
op integer required
path string required
value any
staros-tap demogolf verb course.param '{"op": 0, "path": "…"}'

course.recipe — low, read-only

The recipe (the course as data): text the canonical Lua text with its sha1 (what course.save writes), scene the scene block (tee, hole, race, water, overworld, sound), layers the layers with their ops in full, grid the grid only. Default: grid, scene and the layers’ ids and op counts.

argument type notes
part string one of text, scene, layers, grid
staros-tap demogolf verb course.recipe '{}'

course.redo — low, palette word redo

Redo the last n undone edits (default 1).

argument type notes
n integer minimum 1; maximum 200
staros-tap demogolf verb course.redo '{}'

course.run — medium, palette word run

RUN a built cart: open cart://demogolf.recipe/ (the course’s name by default) as a player would (the editor closes; the round starts at the tee; the logic runs). build = true builds it first.

argument type notes
build boolean
name string
staros-tap demogolf verb course.run '{}'

course.save — medium, palette word save

Write the recipe, canonically, to its source file (golf/courses//recipe.lua) or path: a file write over the tracked course. Ask first.

argument type notes
path string
staros-tap demogolf verb course.save '{}'

course.state — low, read-only

The loaded course’s edit state: its name, the layers (id, op count, off), unsaved, can_undo / can_redo, the open stroke, ops applied, the last flush and re-bake. Cheap (no digest): read it after every edit.

staros-tap demogolf verb course.state '{}'

course.stroke — low, undoable

A whole brush stroke as one undo step: tool (raise lower flatten smooth noise paint), dabs = [x1, z1, x2, z2, …] the cursor’s path in cells (one dab per point), r the radius (1-40), strength (1-12), falloff, mat (paint’s material; ‘own’ = the column’s), y flatten’s level (default: the first dab’s ground), depth paint’s depth. The same path a hand’s drag takes (begin, dab, end).

argument type notes
dabs array required
depth integer minimum 1; maximum 16
falloff string one of smooth, soft, hard
floor number
mat string one of own, stone, soil, sand, crystal, ice, brick, water, lava
r integer minimum 1; maximum 40
seed integer
strength integer minimum 1; maximum 12
tool string required; one of flatten, lower, noise, paint, raise, smooth
y number
staros-tap demogolf verb course.stroke '{"tool": "flatten", "dabs": []}'

course.tell — low

The live logic: tell entity id its input now (say, fire, enable, start, next, pick {n}, answer {text}, …).

argument type notes
args object
id string required
input string required
staros-tap demogolf verb course.tell '{"id": "…", "input": "…"}'

course.trench — low, undoable

Cut a banked ditch along the line from a = [x, z] to b = [x, z]: width its bed (cells, 0..), depth below the ground (1..), bank how far the banks ease back (default 2.2 x the depth, under the buggy’s grade). One undo step in the active layer (what shift+6’s drag does).

argument type notes
a array required
b array required
bank integer minimum 0; maximum 64
depth integer minimum 1; maximum 64
width integer minimum 0; maximum 64
staros-tap demogolf verb course.trench '{"a": [], "b": []}'

course.undo — low, palette word undo

Undo the last n edits (default 1): the agent’s or the hand’s, one step each.

argument type notes
n integer minimum 1; maximum 200
staros-tap demogolf verb course.undo '{}'

editor

editor.cam — low

The editor’s camera: mode top | fly, frame = true frames the whole course from above, pose = [x, y, z, tx, ty, tz] puts the FLY camera there looking at the target, lens the map lens on or off.

argument type notes
frame boolean
lens boolean
mode string one of top, fly, front, side
pose array
staros-tap demogolf verb editor.cam '{}'

editor.close — low

Leave the editor (F4): the played world catches up with the edits (the settle wake, the skin rescan, every actor reseated).

staros-tap demogolf verb editor.close '{}'

editor.ghost — low

Run the ghost validator over the course now (G): a bot drives the race line; the report card comes back (verdict, time, laps, respawns, flips, where it stuck). Synchronous: seconds of compute.

argument type notes
max_s number minimum 10; maximum 3600
staros-tap demogolf verb editor.ghost '{}'

editor.input — medium

Raw input into the editor’s own handlers, as a bot’s: events = [{key, shift?, ctrl?} | {press | release | click = [x, z, y?], with shift? ctrl? alt? double? (BLOB: the whole body) face? (‘+x’: the face to pick; default the top) and at = [px, py]? (the window point) beside it} | {move = [x, z, y?]} (the cursor alone) | {drag = {handle = ‘-y’, n = 3}} (a handle of the tool in hand, by its count: BLOB’s face arrow pulls / pushes) | {wheel = 1, ctrl?, at?} | {hover = true} (what a click would pick: editor.state’s hover)]. BLOB is in hand at open: a click takes the face patch under the cursor. Reaches every hand path (P digs a pool, ctrl+R reloads). Prefer the typed verbs; use this only when asked.

argument type notes
events array required
staros-tap demogolf verb editor.input '{"events": []}'

editor.keys — low, read-only

What the keys do NOW in the Course Studio: the legend’s sections for the present tool (the active tool’s first, then the tools, the course, the camera, history), each row its keys, its words, its live value and whether it is the present state, and the strip’s few rows. The same data the person’s H card and the strip draw (golf/editor/keys.lua + the shared tools’ own).

staros-tap demogolf verb editor.keys '{}'

editor.layer — low

Select the layer edits land in (id; PgUp / PgDn’s) and open or close the op inspector (inspect).

argument type notes
id string
inspect boolean
staros-tap demogolf verb editor.layer '{}'

editor.open — low, palette word editor

Open the Course Studio over the loaded course (F4): the CA and the golf tick hold, the editor’s camera takes the view. Refused in the lockstep lane and without a course.

staros-tap demogolf verb editor.open '{}'

editor.pick — low, read-only

The cell under a WINDOW point (the pixels editor.input’s {project} answers as last_px), as the studio’s own pick takes it there: the pane under the point and its camera, renderer 4 as drawn. {hit, cell = {x, y, z}, mat, normal, pane}; nothing moves (the cursor, the hover). A view’s pick checked over the tap (box.cmd pick answers no hit on renderer 4’s lane).

argument type notes
sx number required
sy number required
staros-tap demogolf verb editor.pick '{"sx": 0, "sy": 0}'

editor.playtest — low

Play-test: leave the editor and drive from the tee (P) or from the cursor (shift+P). F4 returns.

argument type notes
from string one of tee, cursor
staros-tap demogolf verb editor.playtest '{}'

editor.state — low, read-only

The editor’s state: active, the brush, the camera mode, the cursor’s cell, the active layer, the sync chip (pending | synced), the overworld and sound tools’ summaries, the last ghost report; {active = false} when it is closed. Read this first.

staros-tap demogolf verb editor.state '{}'

game

game.drive — low

Drive the vehicle for ticks (default 60): throttle -1..1, steer -1..1, or a world direction dir_x, dir_z (the camera-relative lane); handbrake, catch (hold the flip), allow_flip.

argument type notes
allow_flip boolean
catch boolean
dir_x number
dir_z number
handbrake boolean
steer number minimum -1; maximum 1
throttle number minimum -1; maximum 1
ticks integer minimum 1; maximum 3600
staros-tap demogolf verb game.drive '{}'

game.place — low

Set the vehicle down on the ground at x, z (level, motionless; yaw radians).

argument type notes
x number required
yaw number
z number required
staros-tap demogolf verb game.place '{"x": 0, "z": 0}'

game.plant — low

Plant a grenade at x, z (kind frag | heavy, fuse ticks): a throw from the vehicle, armed at the swing.

argument type notes
fuse integer minimum 1; maximum 600
kind string one of frag, heavy
x number required
z number required
staros-tap demogolf verb game.plant '{"x": 0, "z": 0}'

game.round — low, read-only

The round: its state (plan | swing | live | done), strokes, the distance to the core, the clock, the planted grenades; tuned when a tune.* overlay is in force.

staros-tap demogolf verb game.round '{}'

game.scene — medium

Load a scene or a course (course:<name>): replaces the whole world and DROPS an unsaved edit. seed, paused, vehicle (a def name) as the launch takes them. Ask first.

argument type notes
name string required
paused boolean
seed integer
vehicle string one of boulder, buggy, crate, egg, golem, latcher
staros-tap demogolf verb game.scene '{"name": "…"}'

game.settings — low

The settings (the pause card’s page): bare, every value; with key and value, set one live and persisted. Keys: scheme (fused | classic), look_return (stay | spring), look_speed (0.5..2), invert_x / invert_y (off | on), frame_rate (120 | 60). The value must be one the setting lists.

argument type notes
key string one of scheme, look_return, look_speed, invert_x, invert_y, frame_rate
value any
staros-tap demogolf verb game.settings '{}'

game.swing — low, palette word swing

Swing: arm every planted grenade (one stroke). Refused outside the plan phase.

staros-tap demogolf verb game.swing '{}'

game.view — low

The view: chase | fps | garage; chase takes yaw, pitch (radians) and spin (rad/s; 0 stops).

argument type notes
mode string required; one of chase, fps, garage
pitch number
spin number
yaw number
staros-tap demogolf verb game.view '{"mode": "chase"}'

guide

guide.clear — low

Take the guide’s line away, its pointing, or both (what: line | points; both by default).

argument type notes
what string one of line, points
staros-tap demogolf verb guide.clear '{}'

guide.point — low, palette word point

Make something on screen pulse for a few seconds, so the person sees where to look or click. target: tool: (a row of the tool column), layer: (the layer panel), bar (the top bar), brush (the ring at the cursor), world:, (a cell of the course; works with the editor closed), tee, core, gate:. label: a few words beside it. secs 1-60 (default 6).

argument type notes
label string
secs number minimum 1; maximum 60
target string required
staros-tap demogolf verb guide.point '{"target": "…"}'

guide.say — low, palette word say

Say one line to the person, in the app: a strip under the Course Studio’s bar (the HUD’s toasts with the editor closed). Short (at most 240 characters): what to do next, or a question. tone: info (default), ask (waiting on the person: it stays until guide.clear), done (a step finished). secs overrides how long it stays. Never an undo step.

argument type notes
secs number minimum 1; maximum 3600
text string required
tone string one of info, ask, done
staros-tap demogolf verb guide.say '{"text": "…"}'

guide.state — low, read-only

What the guide is saying and pointing at now, and whether the target is on screen.

staros-tap demogolf verb guide.state '{}'

scene

scene.core — low, undoable

Place the core (the hole) at x, z with radius r (default 5). One undo step.

argument type notes
r number minimum 1; maximum 40
x number required
z number required
staros-tap demogolf verb scene.core '{"x": 0, "z": 0}'

scene.gate — low, undoable

A race gate: add one at x, z (radius r, default 10), move gate i there, or remove gate i. The race line runs through the gates in order.

argument type notes
i integer minimum 1; maximum 64
r number minimum 1; maximum 60
remove integer minimum 1; maximum 64
x number
z number
staros-tap demogolf verb scene.gate '{}'

scene.race — low, undoable

The race’s shape: laps, point_to_point (a stage: no laps), or the whole line as knots = [[x, z], …] (an empty list goes back to the gates).

argument type notes
knots array
laps integer minimum 1; maximum 20
point_to_point boolean
staros-tap demogolf verb scene.race '{}'

scene.tee — low, undoable

Place the tee at x, z (cells); yaw radians (default: facing the second gate or the hole). One undo step.

argument type notes
x number required
yaw number
z number required
staros-tap demogolf verb scene.tee '{"x": 0, "z": 0}'

scene.water — low, undoable

The overworld’s water sources (a falls): add one at x, z with w, h (its sheet’s size), move source id to x, z, height sets its drop d, delete it. (Regions, links and items: box.cmd editor {ow = …}.)

argument type notes
d number
h number
id integer
op string required; one of add, move, height, delete
w number
x number
z number
staros-tap demogolf verb scene.water '{"op": "add"}'

sound

sound.add — low, undoable

Add a sound node: node = {kind = emitter | zone | cue, voice, x, z, r?, gain?, …} (sound.state’s voices list the voices). One undo step.

argument type notes
node object required
staros-tap demogolf verb sound.add '{"node": {}}'

sound.remove — low, undoable

Remove a sound node by id. One undo step.

argument type notes
id any required
staros-tap demogolf verb sound.remove '{"id": "…"}'

sound.state — low, read-only

The course’s sound document (emitters, zones, cues on the shared sound layer’s voices) and the host’s state.

staros-tap demogolf verb sound.state '{}'

terminal

terminal.focus — low

Move keyboard focus to the terminal (showing it) or back to the app; toggles with no to.

argument type notes
to string one of terminal, app
staros-tap demogolf verb terminal.focus '{}'

terminal.hide — low

Hide the drawer; the session stays attached and the agent keeps streaming.

staros-tap demogolf verb terminal.hide '{}'

terminal.open — low, palette word term

Show the task’s terminal (the drawer) and start an agent in it on first creation: claude, code (starsage) or shell.

argument type notes
agent string one of claude, guide, code, shell, greenkeeper, warden, stoker, scribe, herald, busker, porter
staros-tap demogolf verb terminal.open '{}'

terminal.screen — low, read-only

What the task’s terminal shows now: its visible lines, title, size, the link’s state.

staros-tap demogolf verb terminal.screen '{}'

terminal.send — low, palette word ask

Type a line into the task’s terminal and press Enter (enter=false types without it): hand the agent there a request.

argument type notes
enter boolean
text string required
staros-tap demogolf verb terminal.send '{"text": "…"}'

tune

tune.effect — medium

Tune an explosion def LIVE: kind (frag, heavy, booster), path a numeric field (kick, up_bias, r_min, r_max, chain_radius, crater.radius, crater.depth, crater.budget, camera.trauma …), value. The next detonation of that kind uses it. Marks the run as tuned; tune.reset puts it back.

argument type notes
kind string required; one of booster, frag, heavy
path string required
value number required
staros-tap demogolf verb tune.effect '{"kind": "booster", "path": "…", "value": 0}'

tune.reset — low

Put the authored values back: everything, one kind (vehicle | effect), or one def of it.

argument type notes
def string
kind string one of vehicle, effect
staros-tap demogolf verb tune.reset '{}'

tune.state — low, read-only

Every tune in force (live and authored values) and the overlay’s sha; with def (a vehicle’s or an effect’s name) the tunable paths of that def with their current values.

argument type notes
def string
staros-tap demogolf verb tune.state '{}'

tune.vehicle — medium

Tune a vehicle def LIVE: def (buggy, golem, …), path a numeric field by its dotted path (contact_pull, gravity_scale, moment_scale, points.3.kp, water.buoyancy …; tune.state lists them), value. Applies at once to every vehicle of that def (mass, extent and moment_scale re-seat its body). Not an undo step; marks the run as tuned (the round’s fingerprint, no oracle tapes). tune.reset puts the authored value back.

argument type notes
def string required; one of boulder, buggy, crate, egg, golem, latcher
path string required
value number required
staros-tap demogolf verb tune.vehicle '{"def": "boulder", "path": "…", "value": 0}'
The work on this page: the commits of the last 30 days on its sources, the work open against them, its checks

  • love-shared 35ad16d verb sheets: demogolf's regenerated (editor.pick)

  • love-shared f769134 the verb sheet: demogolf's editor.input names BLOB's double and face, and the modifiers beside the cell (2026-11-04, the M2)
  • love-shared f339443 the verb sheet: demogolf's editor.input names the controls' events (move, drag by a handle's count, wheel, hover, modifiers and the window point on a click) (2026-11-04, the M2)

  • love-shared 5d99e8e cart: the demogolf.recipe/1 kind reads the course's scene (entities, scripts, pages, sound) and its library (stamps, prefabs); six conformance cases; the verb sheet (2026-11-03, the M2)
  • love-shared dc2e17c verb sheets: demogolf's course.library and the five primitive kinds (2026-11-03, the M2)
  • love-shared 9cd25b4 dialogue_sim: opts.on_pass (pass <event> hands the event to the host: the Course Studio's entities); verb sheets: demogolf's course.entity / entities / fire / tell / logic (2026-11-03, the M2)

  • love-shared b7ceb84 docs/verbs: demogolf's sheet regenerated (terminal.open's agents: scribe, herald, busker and porter, the worlding launchers, were not on it), so lint/verb-sheets reads green (2026-11-02 night, the M2)

  • love-shared 8109b86 the keepers, K4-K6 (2026-10-31 night, the M2): agents/worlding.lua (the stoker and the scribe in the registry: eight launchers), scripts/tap_conformance.py (the bare `open`, the links' verb every app answers, admitted by name: the one undotted verb; the scribe's finding task://staros/the-bare-link-verb-open-…), scripts/verb_inventory.lua (StarLore's editor verbs join on attach, so the sheet lists note.*, play.*, guide.*, feed.*, media.* as the running app answers), docs/verbs/ regenerated (StarLore 95 verbs with note.new; StarBoard with card.add and link.add)
  • love-shared 3cfe044 docs/verbs: demogolf's sheet regenerated (editor.cam takes front and side; 2026-10-31, the tower)
  • love-shared a430264 docs/verbs: demogolf's sheet regenerated (53 verbs: editor.keys, 2026-10-31, the tower)

  • love-shared ddf655c input/tap_wait: the tap's wait kind as a shared module (2026-10-22, the tower) — startune's daw/tap_wait.lua lifted whole (an agent watches an app without polling: answered the frame the journal has a line after since, others = not the asker's own, a timeout with next; staros-tap.py watch loops on it); demogolf's Course Studio is its second host. scripts/verb_inventory.lua + verb_sheet.py: the demogolf branch and the sheet docs/verbs/demogolf.{md,html} (52 verbs; on the tower from course_test.py --verbs-json through VERB_INVENTORY_DIR); docs/app-verbs.md names the implementers. _tap_wait_test 14/0

The work record as of , from the fold on tower.

Nothing open against these sources.

  • FAILlint/web-reference 12 Nov on tower
  • NOT RUNlint/verb-sheets 12 Nov on tower

Generated by tools/reference_pages.py from love-shared/docs/verbs/demogolf.md; the twin bfaad079a7ce (434093 bytes). The words are a draft.