Sharpee
Chord / Vocabulary & Text / define action

define action

define action <name> … end (dedent-terminated) declares a brand-new action: its grammar, its requirements, its refusals, and its body. This one action shows the whole surface:

define action petting
  grammar
    pet the animal
    pat the animal
    stroke the animal
  the animal must be reachable
  score gentle-hands worth 5
  refuse without animal: pet-what
  refuse when the animal is a snake: glass-way
  otherwise refuse cant-pet
  award gentle-hands
  phrase petted

  phrases en-US
    pet-what:
      Pet what?
    glass-way:
      You settle for pressing a hand to the cool glass.
    cant-pet:
      {capitalize the animal} really is not the sort of thing you can pet.
    petted:
      You give a good long scritch.

Reading it line by line:

  • grammar lists the surface patterns. the <word> marks a slot, and the slot name is the value name used everywhere else in the action. Because the pattern says the animal, the requirements and phrases all refer to the animal. → cardinality on a pattern is reserved: it is refused at compile time until it is implemented.
  • the animal must be reachable is a scope constraint (no colon): a precondition on a slot the parser enforces during resolution. Reachable means what it does in play: the animal is in the same place or in an open container — a closed glass case blocks reach even though you can see through it (that is why the example's refusal settles for the glass), another creature's possessions are out of reach, and reaching requires seeing, so darkness refuses too.
  • score attaches an action-owned score.
  • refuse without <slot>: <key> refuses when the slot was not filled at all (nothing to pet); refuse when <condition>: <key> refuses on a condition; otherwise refuse <key> is the last-resort refusal when no trait claimed the action on this target.
  • The remaining lines are the ordinary body: statements (award, phrase) that run when the action proceeds.
  • phrases is the action's locale block.

Everything a pattern can say

Pattern lines read exactly like the commands a player types. Beyond words and slots, three shapes cover the rest.

Alternation — or between single words makes them alternates of one pattern; optional words go in square brackets:

define action peering
  grammar
    peer in or into the target
    peer [closely] at the target

peer in the box, peer into the box, peer at the box, and peer closely at the box all match.

A slot that takes the rest of the line — stated as a slot property, so the pattern still reads like the typed command:

define action inscribing
  grammar
    inscribe the message
  the message takes the rest of the line

inscribe meet me at the mill at dawn puts the whole phrase in the message.

Slot properties

Every statement about a slot is one idiom — a the <slot> … line under the grammar. You have seen must be reachable; slots can also require must be visible (seen but not necessarily touchable) or must be held (carried by the player):

define action flourishing
  grammar
    flourish the item
  the item must be held

A slot can carry a type. is an instrument marks the tool something is done with; is a topic marks free text the player refers to rather than an object in the world:

define action prying
  grammar
    pry the target with the tool
  the tool is an instrument
  the target must be reachable

Pattern meanings

An indented means <key> <value> line under a pattern hands the action a fact about which phrasing the player chose:

define action lurking
  grammar
    lurk under the target
      means position under
    lurk behind the target
      means position behind

Both patterns run the same action; position arrives as under or behind depending on the line that matched.

Direction words

A directions block binds to the slot named direction, declares the word set with or-joined aliases, and expands every pattern using that slot — including the bare form, so the words work as commands on their own. It is vocabulary, not a compass: declare whatever directions your story's geometry needs.

define action sailing
  grammar
    sail the direction
    the direction
  directions
    port or p
    starboard or sb
    fore
    aft

sail port, sail sb, and a bare starboard all reach sailing, each carrying its canonical direction.

Which pattern wins

When more than one pattern could read a command, one ordering decides, in four steps:

  1. The reading whose nouns name things. Every way a line can read the input is tried, and a reading that fills a slot with words naming nothing in the world loses to one whose words all name something. So give the old man the sword reads the old man and the sword, whatever the line order, and put jack in the box in chest reads the toy and the chest.
  2. The more specific line — the one that spells out more of what was typed — wins whatever its tier. A story's take the thing takes take lamp and leaves take off hat to the standard taking off, because that line spells out two words to the story's one.
  3. At equal specificity, the story's line beats the standard library's. This is what makes extend action settle a contest: restate the standard line under your action and yours wins.
  4. Between equally specific lines of one tier, the one listed first, so the order of grammar lines (and of define action blocks) is meaningful.

A broad story line does not capture a standard verb's more specific phrasings. To take a standard phrasing away from its action, say so with remove from action; nothing is implied by writing a shorter line. There is no numeric priority and no ordering construct.

That ranking holds for the whole game, not just where the action makes sense. A story action whose grammar carries wear dress takes every wear dress a player ever types, in every room and chapter, away from the standard wearing action — so a second dress the player is holding later can never be worn by that phrase. To react to a standard action on one thing, put an on clause on the thing (on the player wearing) and leave the phrase to the standard action; reserve a story action's grammar for phrases that are the story's own.

How a command is read

Every entity slot has a seat: it is the command's direct object or its indirect object, and the action reads it by seat, never by position. The first entity slot in a line is the direct object and the second the indirect, unless the action's earlier lines already seated that name: a slot name keeps one seat across every line of an action. Giving's first line, give the item to the recipient, seats the item direct and the recipient indirect, so hand the recipient the item seats them the same way and give the old man the sword hands over the sword. is an instrument and is a topic take no seat; they are the command's instrument and topic. Two names in one seat is a compile error (analysis.seat-conflict).

When the player stops short, the question asks by seat and by the verb they used:

> give
What do you want to give?

> unlock door with
Unlock it where?

A slot's must be held, must be reachable or must be visible is checked while the command is read, by the same noun matcher the rest of the engine uses to decide which thing a phrase names. When the words name something the player can see but the slot's requirement excludes it, the refusal names the thing and the reason:

> wind lantern
You aren't holding the brass lantern.

> wind the widget
You can't see any widget here.

and and a comma are list readings, never hard splits. take knife and lamp names two things as a list and nothing as one item, so it is a list; take salt and pepper shaker names one thing as a single item, so it is that item, taken once. Articles are optional in both directions: climb rope matches a line written climb the rope, and take the lamp off matches take lamp off.

Claiming a verb only where it makes sense

When a story action should exist only somewhere, or only sometimes, the head takes while <condition>. The action's grammar is a rule only while the condition holds; elsewhere the input parses as though the action did not exist, so a shadowed standard verb reaches its own grammar and its own clarifications:

define action releasing while the player is in the Yard
  grammar
    drop
  phrase let-go

  phrases en-US
    let-go:
      You let go of the rope.

In the Yard, bare drop lets go. Anywhere else, bare drop is the standard dropping action and prints its "What do you want to drop?". The condition is read before any slot binds, so it names no slot — rooms, states and the player, not the item. Refusals inside the claim stay refuse when.

The standard slot names

The standard library's grammar uses seventeen slot names, most-used first: target, item, recipient, device, container, door, portal, topic, tool, weapon, vehicle, key, supporter, hook, object, location, destination. Reuse them when you extend a standard action — an extension's lines refer to the same slots the action already resolves.

Actions and traits

The relationship to traits: define action declares the verb, its grammar, and its default outcomes; a define trait with an on <verb> clause is how a particular kind of thing responds to that verb. Together they are the story-author's version of stdlib's action-plus- behavior pattern: the animals above are pettable because petting exists as an action and something makes the animals respond to it.