Hazel reports · ^report(33) · Messed Up Dress Up's scripts · 2026-10-25 · work in progress

Game Scripts in Hazel, a Case Study

This is written for readers who know Hazel and want to see what writing a game's rules in it involves. Part 1 shows the rules and their types as they run today, in the game at eee9446 (0.0.429); Part 2 tells how they came to be that way; Part 3 proposes what to change, in Hazel. The game's own guide for its young players is a different document.

Part 1 How it works today

Piecemeal: each part works on its own terms, and they do not yet share a model.

A rule, today#copy link

The game is plain JS. Five of its rooms can hand an event to a rule written in Hazel (or Fumola, or left to the game's own JS), chosen room by room in its 📜 Scripting tab. The Hazel program is one file of modules: Common (shared helpers) and one module per room, each with an on_event. The game loads Hazel's JS library (hazelgrove/hazel#2711), builds the program once per edit, and calls a room's function when its event happens (scriptEvent).

The types, as the game declares them at the top of the program (25-scripting.js:98-102), and one room's whole rule:

type Event =
  + Pull(Side) + PullBoulder(Side) + PullHatch(Int) + PullThing(Int)
  + FallPit(Int) + WayOut(Int) + Way(Dir)

type Cmd =
  + Done + Flip(Side, Cmd) + Say(String, Cmd) + SetPit(Int, Bool, Cmd)
  + DropBoulder(Int, Cmd) + LiftBoulder(Int, Cmd) + SetHatch(Int, Bool, Cmd)
  + OpenDoor(Int, Bool, Cmd) + DropRock(Int, Bool, Cmd) + Wait(Int, Cmd)
  + GoRoom(Int, Cmd) + GoSquare(Int, Int, Dir, Cmd)

type Thing = (at = Int, uid = String, kind = String, on = Bool, works = [String],
              does = String, open = Bool, boulder = Bool)
type Cell = (col = Int, row = Int, kind = Place, ways = [Dir])

type Globals = (lever_L = Bool, lever_R = Bool, wiring = Wiring, draws = [Float],
                pits_on = [Bool], covered = [Bool], hatch = Bool, things = [Thing],
                rooms = [Room], exits = [Exit], out = Out, at_col = Int,
                at_row = Int, cols = Int, rows = Int, cells = [Cell])

# the tree room's rule, whole #
module TreeRoom = {
  let on_event = fun (g : Globals, e : Event) : Cmd ->
    case e
    | PullHatch(n) => SetHatch(n, !g.hatch, Done)
    | _ => Done
    end
}

A few things a Hazel reader should know about how these meet the game:

• A Cmd is a list spelled as a sum: every command carries the rest, ending in Done. The game walks it (scriptRun); Wait(ms, rest) holds the rest for later, so a rule can describe a timed sequence without a clock of its own. An unknown command stops the walk.
• The boundary is typed both ways. The game's state is JS text and numbers; scriptTypedGlobals turns strings into the sums (Wiring, Room, Out, Place, Dir), and scriptUntypedCmd turns commands back. So the JS object has 17 fields and the rule sees 16: out and out_room become one Out.
• A rule has no randomness or clock: the trap room's two random draws come in as draws, drawn by the game from a seed it keeps.
• One error anywhere sends every Hazel room back to the JS (the program must be whole to run), and a rule that throws is said in the game and skipped.

Globals is a per-rule view#copy link

Each room registers three functions (SCRIPT_ACTS): here (is this event mine?), globals (build my view) and act (how my commands change the game). The view is a Globals with the room's own fields filled from the game and every other field at a default (scriptNoGlobals):

The tree room shows it best. A tree has up to six houses and a round room at the top, each with its own trap door (hatchShut1 to hatchShut6, hatchShutTop). The rule gets one hatch : Bool: the door of the house the friend is in, picked by the game (hatchHouse). The event carries the house's number, PullHatch(1), and the command repeats it, SetHatch(1, false, Done), but the state does not: the game checks the number matches and refuses the command if not. So the rule's hatch is "this hatch", resolved by context, and a rule cannot ask about any other.

The other rooms work the same way. The trap room's levers are the trap room of the castle shown; the square's things are the list of the place the friend is in, each known by its index in that list (at); the castle's out is the way out of the room the friend is in. Nothing in Globals says which castle, square or house: the game knows, and the rule is written as if there were only one.

Two things the game's own guide says otherwise: pits_on is whether each pit is there at all, not whether it is open (that the rule works out from the levers and the wiring), and "17 fields" counts the JS object, not what the rule sees.

Where, today: eleven words, and numbers for names#copy link

Read from the game itself (its default world and its tables of insides, castles and room styles, in node at eee9446), with every trap door, hatch and passage open:

"Place" is the code's word and never the UI's; the UI says background, square and room. And the ids are positions: a placed thing is its index in its place's list (and only a trap door or a cave passage has a uid, a random string); a pit is 0 or 1; a house is 1 to 6; a castle room 1 to 13; a square is "c,r" in code and D4 on screen. A 1 in a command can be a house, a pit, a room or a list index, depending on the command. Several keys already work like addresses, spelled differently each time: placeKey is castleroom:N:3, worldHome is off:w1:tent:2, a person's place is {world, key} with no room part, and a setting's key spells its owner into its name (castleLeverL_3N).

Part 2 How it got this way

Waves of features and game experiences, each with its own words and keys.

Waves of features#copy link

Messed Up Dress Up was made with M and N, a feature at a time, each released the day it worked, as they asked for it (the game's own rule: features first, released at once). Each wave brought its own experience and, with it, its own way to say where the friend is, and none went back to rework the ones before:

1. Dressing up, in front of a picture. The first game was a friend to dress; state.background.kind was the picture behind them, one of a list (PLACES, its group chips kind of place). A place was a picture, and a picture had no inside.
2. Places you can walk into. Doors came next, each door a data-to naming a kind: the house's living room, the witch's room, the cave. An inside was just another kind, reached by a door; "back" was a stack of where you had been (trips).
3. Castles and their rooms, for N's and M's castle designs: three castles by whose they are, rooms by number (1 to 13) with styles (ROOM_KINDS), and each room's settings spelled into its keys (castleLeverL_3N). The trap room's levers and pits came with them, numbered 0 and 1.
4. Tree houses: up to six houses by number, a round room on top, bridges, ladders and hatches; B.inside became "which house".
5. A world to walk: a grid of squares, each a place kind (W.cells["c,r"], D4 on screen), ways between squares, then other worlds, insides kept "off the grid", cave passages that link any two places, and people placed in squares (person.place {world, key}, no room).
6. Things placed in places: rocks, levers, trap doors, each an entry in its place's list, known by its index; a trap door and a passage got a random uid so a lever and its twin could find them.
7. Rules in Hazel and Fumola, for five rooms: each rule needed some of the game's state, and the simplest thing that worked was one record type with every room's fields, filled per room. That is Globals.

Each step was the right size for its day, and the game kept working. The cost is what Part 1 shows: eleven overlapping words, ids that are positions, and a rule's state that is shaped for the game's convenience rather than the rule's. Nothing in it is wrong for one room; it does not add up for a game that a rule, a log, or a second game should be able to read as a whole.

Part 3 A more holistic approach

One model of where everything is, and rule types built on it.

RuleState, and a real Globals#copy link

The fix the view asks for is to say what it is. Each room's rule takes its own state type, named for it: the tree room a hatch, the trap room its levers and pits, the world its squares. No default fields, nothing for a rule to misread, and a rule's type says what it depends on. Matthew's name for the sum of them is RuleState.

A real Globals is then the whole game, read-only to rules. For a rule that wants to look further (is the other castle's trap set? where is the friend?), for diagnostics, and for the log: the same addresses in every rule's state and in Globals let a tool show a change anywhere. Rules still change the game only through commands, so the game stays the one place state changes.

Both need a way to say which hatch, lever or room, in one keyspace. That is the next three sections.

Every place, as a path#copy link

Every move between places the game allows is a move along this tree or across it: the ways between squares; a door to an inside and back; a ladder, bridge or hatch between tree houses; a pit from the trap room to a dungeon; a cave passage, which may lead to any place in any world; a picture you step into. Each lands in exactly one node, so one path from the world down names any place a walk can reach:

Names that can't collide#copy link

In Fumola, the same symbol, as it stands (its Call):

`world(`start)(`square(`E4))(`castle(`N))(`room(3))(`lever(`L))

In Hazel, a symbol is written as that text and parsed to the tree: parentheses, names and numbers, nothing else, and no constructor names in a rule:

let lever_L = parse_sym("world(start)(square(E4))(castle(N))(room(3))(lever(L))") in
let room_3 = parse_sym("world(start)(square(E4))(castle(N))(room(3))") in
print_sym(lever_L) == "world(start)(square(E4))(castle(N))(room(3))(lever(L))"

Human readable: as text, each step is a word and a name a player would use (square(E4), castle(N), lever(L)). Unambiguous: the kind is part of every step (the first half of its call), and a name only has to be unique among its owner's children of that kind, so places, things and people share one keyspace with no global counter.

This is Fumola's symbol, as it stands. In Fumola, names are values: an identifier is a symbol, a number is a symbol, and symbols compose by application and nest, `adapton(`settings); Fumola's Symbol has exactly these cases (Id, Nat, Call, and others besides); a game symbol needs only those three: names, numbers and parentheses. And its space is the same move an address makes: a cell `x named inside the region `region is `region(`x), so a callee names freely without colliding with its caller, as a room names its levers without knowing which castle it is in.

Identity, not position. Adapton names a node so it keeps its name when its contents change; the alternative, naming by content, cannot say "same node, new value" (Fumola's notes, What is a cache key a function of?). Names derived from position are worse than either: an address survives only as long as the shape it addresses, which in Fumola's mergeSort measurements turned a repair of 23 to 25 nodes into 139. The game's list indexes are such names: delete the first thing in a place and every PullThing(i) after it means a different thing. So:

• Places are named by where they are, and do not move: world(start)(square(E4))(castle(N))(room(3)).
• A thing or person is named once, when it is made, by its owner and a name unique there (lever(L), or the next free shell(10)), and keeps that name for good: it is an id, not a location.
• Where it is now is a field: Placed(owner), SetAside (the world's buffer of things taken out, to be put back as themselves), or Carried(person).
• A template is a kind, placed nowhere: place(castleroom).style(trap), lever, person(costume(ninja)). Making an instance from it mints a name; putting a set-aside one back does not.

Globals, RuleState and Cmd, proposed#copy link

In Hazel. First the addresses and what they name:

# a game symbol, as Fumola's: text, a number, or one applied to another #
type Symbol = + Text(String) + Num(Int) + Call(Symbol, Symbol)

# supposed: Hazel parses a symbol from its text and prints it back, so
   rules, saves and logs write world(start)(square(E4)) #
# parse_sym : String -> Symbol    "a(b)(c)" is Call(Call(a, b), c) #
# print_sym : Symbol -> String    print_sym(parse_sym(t)) == t #

# lever(L) is Call(Text("lever"), Text("L"));
   world(start)(square(E4)) is Call(world(start), square(E4)):
   an owner applied to what it owns, as Fumola's `region(`x) #

type Where = + Placed(Symbol) + SetAside + Carried(Symbol)

type Setting = + B(Bool) + I(Int) + F(Float) + S(String) + A(Symbol)

# a placed thing or person: its name for good, its template, where it is now #
type Instance = (id = Symbol, template = String, where = Where,
                 settings = [(String, Setting)])

# a place: its address, its template, its ways, and what it owns #
type Way = (dir = Dir, to = Symbol, via = + Open + Door(Symbol) + Shut(Symbol))
type PlaceState = (id = Symbol, template = String, ways = [Way], owns = [Symbol])

Then the whole game, each room's own state, and commands and events by address:

# the whole game, as any rule may read it #
type Globals = (
  friend = (id = Symbol, at = Symbol),      # the person being played, and where #
  places = [PlaceState],
  instances = [Instance],               # every thing and person made #
  set_aside = [Symbol],                   # the world's buffer, re-placeable #
  random_numbers = [Float]              # the event's random numbers (today's draws) #
)

# what each room's rule is about: its own, named, typed #
type TrapRoomState = (here = Symbol,
  levers = [(id = Symbol, up = Bool)], wiring = Wiring,
  pits = [(id = Symbol, there = Bool, covered = Bool)])
type TreeRoomState = (here = Symbol, hatch = (id = Symbol, shut = Bool))
type SquareState = (here = Symbol, levers = [Instance], doors = [Instance])
type WorldState = (here = Symbol, squares = [PlaceState])
type CastleState = (here = Symbol, rooms = [PlaceState], out = Out)

type RuleState =
  + Trap(TrapRoomState) + Tree(TreeRoomState) + Square(SquareState)
  + World(WorldState) + Castle(CastleState)

# the event names what happened to, by address #
type Event = + Pull(Symbol) + Fall(Symbol) + Leave(Symbol, Dir) + Arrive(Symbol)

# commands name what they act on, by address #
type Cmd =
  + Done + Say(String, Cmd) + Wait(Int, Cmd)
  + Flip(Symbol, Cmd)                     # a lever #
  + Swing(Symbol, Bool, Cmd)              # a hatch, a pit's lid, a door: open? #
  + Set(Symbol, String, Setting, Cmd)     # any setting of any instance #
  + Move(Symbol, Where, Cmd)              # an instance to a new owner, or aside #
  + Go(Symbol, Cmd)                       # the friend, to a place #

# a rule: its room's state, the whole game to read, the event #
let on_event : (RuleState, Globals, Event) -> Cmd

The commands get fewer and more general: one Swing for every hatch, lid and door, one Set for any setting, and Move, which today's rules cannot do at all. Each names its target, so the game's act no longer has to check that a number means what the rule meant. Today's, beside them:

The tree room's rule becomes | Pull(h) => Swing(h, !s.hatch.shut, Done) with s : TreeRoomState: the same one line, now saying which hatch.

What next#copy link

• Decide the symbol syntax (calls, world(start)(square(E4)), as above) and the list of kinds, from the vocabulary table: one word each for a world, a square, an inside, a room.
• Give every placed thing a name when it is placed (and the default world's 68 things one each), and keep it through moves; a thing's index stops being its id.
• Write RuleState for the tree room first, the smallest, with the game building it from addresses, beside today's Globals; then the trap room.
• Add the world's buffer of set-aside things, as peopleAway is for people.
• Parse and print symbols in Hazel (parse_sym, print_sym, supposed here): a rule writes parse_sym("world(start)(square(E4))") and gets the tree, with no constructor names.
• Later, if strings and helper calls wear thin: symbol literals in Hazel, as Fumola has today (`world(`start)(`square(`E4))): the parser reads the tree directly, so parse_sym("...") becomes a literal, checked when the program is, with its names highlighted in the tiles.
• Show addresses in the event log, so a change reads …house(1).hatch: shut → open.

How this was put together#copy link

Written on 2026-10-25 by Claude, for Matthew, from ^ticket(609). The game was read at eee9446 (Messed Up Dress Up 0.0.429). The default world, the insides, castles and room styles were read from the game's own tables, run in node (data/places.json); Figure 4 and the appendix are drawn from that file. The rooms' fields and types were read from dress-up/js/25-scripting.js and 25-fumola.js. The pictures in the appendix are the game's own drawings, from the dress-up-pictures archive's newest run; things got a folder of their own there for this report.

Appendix: every address#copy link

Every place and placed thing of the default world, then the templates: places, castle room styles and people. Open a row to see the game's drawing of it (fetched from the archive only then). A thing's number here is its order among its kind in that place, as a name would be minted; the game today knows it only by its index in the place's list.

places (64)#copy link

things (68)#copy link

templates: places (51)#copy link

templates: people (36)#copy link

The data#copy link

• The numbers, for programs too: every table in this report, and what its numbers measure, is also in this page as JSON, in its <script type="application/json" id="report-data"> element, so a reader or an agent that fetches the page alone has the dataset. The same, with any raw files that survive, is in 033/data/.