Sharpee
Chord / Cookbook / Overview

Cookbook

A table-first companion to the standard library reference: every standard action's phrasings, the trait that makes an entity eligible, and the refusal keys it speaks. Then, for the actions you will reach for most, it adds a worked example in story context: the Chord .story scene an author writes, and the transcript a player sees.

Every story block on these pages is a verbatim excerpt of a loadable fixture, and every transcript line is genuine engine output: replayed and diffed against the running engine, never hand-typed.

How to read this

Each category opens with a table: the action, the phrasings that actually parse (grounded in the parser's grammar, not the help lists), what an entity needs to be eligible, and the message keys the action refuses with. Refusal keys are single kebab words (fixed-in-place), not dotted ids and not fixed text; a story retargets a platform message with override message <alias> (ADR-254/255), and the reference explains how. Success keys, events, and the full check order live in the corresponding reference entry; this document is the quick lookup and the gallery.

Below each table, the worked examples come in pairs: the author writes a small scene, the player sees a few commands against it, always including at least one refusal and one success. <direction> in a phrasing means any of the twelve direction words (north/n … up/u, in, out).

Two authoring notes that recur in the examples:

  • Give every multiword entity an aka alias. It is a kindness to players, not a requirement: the full name parses in every form, article or no; x the iron key and x iron key both hit (ADR-231).
  • Where an example carries a custom refusal on a standard action, its phrase is declared under a single-token kebab label (define phrase ring-fused) and named by refuse ring-fused (ADR-254): phrase keys are single words, never dotted. Custom refusals work on every standard action: giving, showing, throwing, and wearing included. To retarget a platform standard-action message instead of adding your own, use override message <alias> (ADR-255) — for example override message taking-fixed-in-place. Refusals inside a define action (see turning) take short keys as they always have.

What this document leans on

  • The standard library reference is the full catalog this cookbook indexes: check order, success keys, events, traits, and the honest platform notes.
  • the Author Guide documents the .story language the "author writes" halves are written in.
  • docs/work/stdlib-cookbook/ holds the fixtures and the verify.mjs harness that replays every transcript on these pages against the real engine. If the engine's words change, verification fails and this document gets refreshed. That is the drift protection.

Sections