Library reference

Source-derived reference for the library declarations. All entries show their source location; supported author and host interfaces have reviewed descriptions.

Alphabetical symbols · Alphabetical members

Actions

Classes

  • AccompanyingInTravelState — Temporary state used while an actor follows a leader through travel.
  • AccompanyingState — An ActorState that follows an explicitly stored leader during travel.
  • Action — Defines argument requirements and the execution and reporting hooks for a command.
  • Actor — A character that participates in travel, conversation and actor states.
  • ActorState — Behaviour and presentation state associated with an Actor.
  • AdjRun — A run of them, so a phrase may carry as many as it likes.
  • AdjWord — An article, which a player types without thinking about it and every parser in the genre accepts. vhyl refused TAKE THE TOKEN and ASK ZOÉ ABOUT THE TAPE until an author game tried to write a walkthrough in English. A production of its own rather than a word in each rule, so the three noun phrase shapes stay three. Spelled anArticle because article is already the language module's a/an chooser, and a production shares a namespace with a function.
  • AgendaItem — A scheduled item of actor behaviour.
  • Attachable — A thing that can attach to another entity.
  • AttachableComponent — A component that can be attached to another entity.
  • BagOfHolding — An openable container with a distinct bulk policy.
  • Bed — A platform supporting lying posture.
  • Booth — A container that an actor may enter.
  • Button — A control operated by pressing.
  • Chair — A platform supporting sitting posture.
  • Command — Carries parser captures, resolved arguments and reports through an action.
  • Component — A thing whose identity and placement are tied to another object.
  • Consultable — A thing that can answer consult actions.
  • Container — A Thing whose contents participate in containment and capacity rules.
  • ConvAgendaItem — An agenda item that accounts for conversation activity.
  • Conversation — A host-driven choice conversation with a stable id and target.
  • Daemon — A scheduled event that repeats at its interval.
  • DarkRoom — A room that requires another light source to be visible.
  • Decoration — Scenery normally omitted from room listings.
  • Dial — A control whose setting can be changed by the player.
  • DialogueChoice — A selectable conversation option with stable identity and availability rules.
  • DialogueContext — The asker and active conversation passed to choice hooks.
  • DialogueError — Optional host-driven conversations. Include after vhyl.t. Copyright (c) 2026 John Cunningham. MIT License; see LICENSE.
  • Distant — Scenery visible but outside ordinary reach.
  • Doer — Redirects or customises a resolved action for selected objects.
  • Door — A travel connector shared by rooms through connects relation rows.
  • Enterable — A fixed object an actor can enter.
  • Event — Schedules a property call on an owner after completed turns.
  • EventList — Cycles, stops or exhausts an authored list of values.
  • Fixture — Fixed furniture or scenery within a location.
  • Food — A thing that can be eaten.
  • Fuse — A one-shot scheduled event.
  • Gadget — Base for manipulable controls such as switches and buttons.
  • GoodbyeChoice — Standard choice that closes a conversation.
  • GuidedTourState — An accompanying state that leads another actor toward a tour destination.
  • Heavy — A thing too heavy for ordinary taking.
  • HermitActorState — An actor state that declines ordinary conversation.
  • Immovable — A thing that cannot be moved by ordinary actions.
  • InitObject — An object whose execute hook runs during vhylStart.
  • Intangible — A perceivable thing that cannot be touched.
  • InternalSpeaker — A private conversational voice bound to its asker through voiceOwner.
  • Lever — A control with lever-specific action reporting.
  • LiteralPhrase — ----------------------------------------------------- literals and topics
  • LockableContainer — An openable container with lock state.
  • Message — A message keyed by stable id, with text or a computed say method.
  • MultiLoc — A fixture present in multiple rooms through presentIn relation rows.
  • Noise — A sound present in one or more rooms.
  • NounPhrase — internal
  • Odour — A smell present in one or more rooms.
  • OpenableContainer — A container that can be opened and closed.
  • OutdoorRoom — A room lit by the sky under the default world policy.
  • Passage — A travel connector without a door's open and closed state.
  • PathPassage — A passage whose bulk policy permits a path-like route.
  • Platform — A surface on which an actor may stand.
  • PreCondition — Checks or establishes a requirement before an action executes.
  • PreinitObject — internal
  • RearContainer — A thing that receives objects placed behind it.
  • Report — ------------------------------------------------------------- reporting
  • Room — A lit-by-default location whose exits and contents are relation rows.
  • Scene — Tracks a condition-driven interval in the world.
  • SecretDoor — A door initially hidden from ordinary observation.
  • Sensed — A sensed phenomenon that can be present in multiple rooms.
  • SenseEvent — A recurring event conditioned on the player's location.
  • StairwayDown — A connector representing travel downward.
  • StairwayUp — A connector representing travel upward.
  • State — Synchronises vocabulary with an observed property condition.
  • SubComponent — A subordinate physical part of another thing.
  • Surface — A fixed surface on which things can rest.
  • Switch — A binary control operated by turn-on and turn-off actions.
  • Thing — Base entity for physical and describable things in the adventure world.
  • Topic — A vocabulary-resolved subject used by ask and tell dialogue.
  • TopicDialogueChoice — Explicitly adapts a TopicEntry into a choice conversation.
  • TopicEntry — An ask or tell response matched to a topic and optionally an actor state.
  • TravelConnector — A traversable entity that can control staging, passage and travel reports.
  • Unthing — A referable absence with a custom explanation.
  • Vehicle — A boardable thing that can carry an actor through travel.
  • Verb — Maps a stable structured action code to an Action and optional direction.
  • Wearable — A thing that can be worn and removed.

Dictionaries

Enums

  • Direction — internal
  • dobjRole — internal
  • posIn — internal
  • standing — internal
  • token — Public declarations for vhyl: relations, vocabulary and verification ranks. Copyright (c) 2026 John Cunningham. MIT License; see LICENSE.

Functions

  • accompanists — The actors in this room travelling with this leader, breadth first. A state says whether it comes along, and a guided tour says so only for the leg of the tour it is on — which is what stops a guide following the player off the route.
  • account — internal
  • accountAbout — internal
  • accountAs — One account, at a given place in the report order.
  • accountDefault — internal
  • actOnce — One object's worth of a command: redirect, refuse, act.
  • addReport — Put a report on the command's list.
  • addToAgenda — internal
  • aName — internal
  • AName — internal
  • applyCase — internal
  • article — ------------------------------------------------------------- the words
  • awardPoints — Award points once for a named achievement.
  • bestReading — internal
  • beVerb — "is" or "are", and "was" or "were".
  • blockingFor — The nearest shut container between the player and this thing, or nil. Nearest first, because opening the outer one is what lets you reach the inner one, and the loop comes back for the rest.
  • bothOf — What is in both lists.
  • bulkIn — How much is already inside something.
  • capitalised — internal
  • carried — internal
  • carriedBulk — How much the player has in their arms, for a passage with a limit.
  • chooseOne — internal
  • clearMessageParams — internal
  • conjugate — One verb, agreeing with whatever the last parameter named. English needs an -s on a third-person singular present verb and nothing anywhere else, which is the whole of the agreement most library messages need. A verb whose past is not "-ed" says so.
  • connectorHere — A connector is in scope from either of the rooms it joins.
  • contractionName — it's, you're, the keeper's* — the contraction of a name and "to be".
  • converse — ASK X ABOUT Y and TELL X ABOUT Y.
  • defaultDescReport — The same, for a description: You see nothing unusual. Dropped when anything else is said, but kept for an implied command, because a description is an answer rather than an acknowledgement.
  • defaultReport — internal
  • deliverTopic — Execute the exact selected entry; both ASK/TELL and menu adapters use it.
  • describeRoom — internal
  • destinationOf — Where this exit ends up, following a connector if there is one.
  • dialogueContext — internal
  • dialogueEnd — internal
  • dialogueSay — internal
  • dialogueText — Keys stay stable; optional literal Message.text is terminal/example fallback. Fallback text and message activity must be observational, like availability.
  • dirName — internal
  • doBoard — internal
  • doEnter — internal
  • doGetOff — internal
  • doGo — internal
  • doInventory — ---------------------------------------------------------- action helpers
  • doorDestination — The room on a door's far side, from the one you are standing in.
  • doPush — internal
  • doPutIn — internal
  • doPutOn — internal
  • endedCommand — internal
  • endingFor — The verb endings, by the string inside the braces. Answers nil for a word that is not one.
  • expandAll — internal
  • expandBody — internal
  • expandNested — A nested [...] inside a tense choice, which is a parameter in brackets.
  • expandOne — Expand one {...}, given what is inside it. The order matters: a tense choice, then a verb ending, then an irregular verb, then the format table, and only then the fallback that treats an unknown word as a regular verb — which is vhyl's own addition and is what lets a message write {take} instead of take{s}.
  • extraReport — An extra line that does not suppress a default.
  • findDoer — The Doer that catches this command, if any.
  • finishAccompaniment — internal
  • finishCommand — The account and the turn, once, however many objects the command named.
  • finishGame — End the game. The turn that calls this finishes; nothing after it runs.
  • firstNamed — internal
  • formKind — internal
  • getLiteral — internal
  • getTopic — internal
  • getTopicText — internal
  • here — Return the room containing the player.
  • holds — internal
  • inPast — ---------------------------------------------------------- the expander
  • inScope — internal
  • irregularVerb — internal
  • isAre — "is" or "are", for a count. Agreement, as far as vhyl needs it.
  • isAreFor — The same, for one thing whose name is grammatically plural.
  • isDark — A room you can see in: lit itself, or by something in it or carried.
  • isVerbWord — Whether a word left of a | is a verb rather than one half of a choice.
  • itName — A pronoun for something that is not the player: he, her, it, them.
  • kindIsPronoun — internal
  • kindIsSubject — Whether this kind is the sentence's subject.
  • kindMeansActor — Whether this kind implies the actor rather than taking a selector.
  • kindNamesNothing — {way} names no object, so it must not disturb the antecedent.
  • kindReflexes — Whether this kind has a reflexive form to fall back on.
  • listContents — internal
  • listedPhrases — internal
  • listSensed — What can be sensed here, listed after the room.
  • litBy — internal
  • literalText — The words of a literal phrase, joined back into a line.
  • mainReport — The main result of the action. There may be several.
  • meetPreConds — internal
  • messageFor — The message that answers to this id, or nil.
  • msgFor — The text of a message about one or two objects, read rather than said. refuses answers a sentence for the turn to print, so it needs the words rather than the side effect. A message with no text — one whose body emits — has nothing to read, and answers nil so the caller falls back to whatever it would have said anyway.
  • nameList — internal
  • nestedIn — What the player is in or on, if anything short of the room.
  • nomName — The subject form: you, I, the keeper.
  • noteDone — internal
  • noteSeen — A displayed discovery is world knowledge, including for a host using only semantic events. Do not infer this from arbitrary message subjects.
  • noteSentenceEnd — internal
  • noteSubject — Note that a parameter named this entity, for the verb and the pronoun after it.
  • objName — The object form: you, me, the keeper.
  • oppositeOf — internal
  • paramOf — The entity a {...} parameter names, by the word the message used.
  • pcPerson — The person the player character is written in, and whether that person takes a plural verb. "I", "you", "we" and "they" all take the bare form; only a third-person singular takes the -s.
  • pcWord — internal
  • phraseCandidates — The entities a phrase names: every word in it has to name them.
  • possAdjName — internal
  • possNounName — mine, yours, his, hers, its, theirs* — the form that stands alone.
  • postureName — internal
  • prepFor — The English word for a spatial position. vhyl says a thing rests posOn another; which preposition that is, and that English has one at all, is this module's business.
  • proIsPlural — Whether this thing takes a plural verb: they are, it is.
  • pronounSet — ------------------------------------------------------- the name shapes
  • proPossAdj — his/her/its/their — the form that qualifies a noun.
  • proPossNoun — his/hers/its/theirs — the form that stands alone.
  • proReflexive — himself/herself/itself/themselves.
  • proWord — he/she/it/they, and him/her/it/them.
  • rankOf — internal
  • readingRank — internal
  • recover — internal
  • reflexiveName — myself, yourself, himself, herself, itself, themselves*.
  • relocateActor — A movement fact is independent of prose and visibility. Fiat relocation uses this too, but deliberately gathers nobody and consumes no action.
  • removeFromAgenda — internal
  • replaceAction — internal
  • reportAfter — Moved after every main report, however early it is added.
  • reportBefore — internal
  • reportFailure — A main report that also marks the command a failure, so a caller that ran it as an implied action knows not to go on.
  • roomFor — Whether one more thing fits. A capacity of 0 means no limit is stated.
  • roomSpecials — internal
  • runActors — Every event that is due, in declaration order.
  • runCommand — internal
  • runCommandOver — internal
  • runEvents — internal
  • runScenes — Run every turn: start and stop whatever scenes are due.
  • sayAbout — Say an id about an object and a list of things, or a word.
  • sayFor — Say an id about one or two objects, with no command in hand.
  • sayMsg — Say what this id means. c is the command, so a message that wants the objects has them; one that does not ignores it. An unknown id prints the id itself rather than nothing, because a message that silently says nothing is the hardest kind to find.
  • sayReports — internal
  • seeInto — Whether what is inside can be seen. Open, or not shuttable, or shut but transparent — a glass jar with the lid on shows what is in it.
  • setMessageParam — internal
  • splitParam — internal
  • syncStates — Bring every state's vocabulary into line with the world. Idempotent: a state whose word has not changed writes nothing, so this costs one property read per state on a turn where nothing happened.
  • takePosture — ------------------------------------------------------------- postures
  • tellApart — internal
  • thatName — internal
  • theName — ------------------------------------------------------- naming helpers
  • TheName — internal
  • topicAvailableTo — internal
  • topicFor — internal
  • tryImplied — internal
  • tSel — internal
  • verbEnding — internal
  • verbFor — The verb this code names, or nil.
  • verbForPosture — The verb that puts somebody into a posture, for an implied command.
  • vhylAct — Submit a structured verb code and entity arguments to the normal action cycle.
  • vhylStart — Initialise the world once, place the player and describe the initial room.
  • vhylTurn — Submit parser tokens to the library's text command cycle.
  • visible — Visible means reachable without opening anything: every container between the item and the room has to be open. One walk up the containment table.
  • wayFrom — internal
  • wayWord — internal
  • wearTravelState — internal
  • withPast — The tense a {...!} parameter and quoted speech pin themselves to.
  • withPresent — internal
  • withTense — internal
  • wordFor — The word a kind produces for a thing.

Grammar

Macros

Messages

Objects

  • actArgs — The command an action intent fills in. One command runs at a time, so this is reused rather than allocated, for the same reason msgArgs is.
  • allDirections — ------------------------------------------------------------- directions
  • dialogueUI — An optional library module may handle structured UI intents.
  • enOpenClosed — internal
  • expandCtx — internal
  • gameMain — Per-game startup settings supplied by a modify gameMain declaration.
  • gameOver — Set when the game is over, with what to say.
  • impliedArgs — The command an implied action runs in, so the outer one is not disturbed.
  • language — internal
  • lastNamed — internal
  • listenAction — internal
  • messageParams — internal
  • moveSlash — ---------------------------------------------------- one parameter body
  • msgArgs — internal
  • multiLocPreinit — A MultiLoc names the rooms it stands in and vhyl writes the rows, for the same reason a door does: where a thing is belongs to the declaration, and turning that into table rows is the library's job.
  • objClosed — Shut. Implies CLOSE.
  • objEmpty — Nothing inside. Implies taking one thing out, and the loop does the rest.
  • objHeld — Held directly by the player. Implies TAKE.
  • objNotWorn — Not being worn. Implies TAKE OFF.
  • objOpen — Open, if it is the kind of thing that shuts. Implies OPEN.
  • objUnlocked — Unlocked. Implies UNLOCK, with no key named — the action finds one.
  • objVisible — Visible. Nothing implies being able to see.
  • player — The library player entity; place it by setting gameMain.initialRoom.
  • score — internal
  • smellAction — internal
  • touchObj — internal
  • travelActions — --------------------------------------------------------- actor travel
  • turnCount — The turn the game is on, counted from the first command.

Properties

Relations

  • attachedTo — Records attachment between two entities.
  • connects — Associates a door with every room from which it can be used.
  • contains — Places an item in one container; read the inverse through location.
  • dialogueActive — internal
  • dialogueAsker — internal
  • dialogueUsed — internal
  • dialogueVoice — Binds a private speaker to its owner; voiceOwner is the inverse.
  • exits — Connects rooms by a direction for travel.
  • knows — Records explicit knowledge of another entity.
  • presentIn — Places a MultiLoc in several rooms without changing containment.
  • vocab — Assigns noun and adjective words to an entity.

Templates

Verbs

  • vAskAbout — Built-in verb code 55.
  • vAttach — Built-in verb code 53.
  • vBoard — Built-in verb code 30.
  • vClose — Built-in verb code 24.
  • vConsult — Built-in verb code 49.
  • vDetach — Built-in verb code 54.
  • vDetachPart — Built-in verb code 40.
  • vDialogueBegin — The integer codes are transport verbs, not speech-act categories.
  • vDialogueRefresh — Built-in verb code 82.
  • vDialogueSelect — Built-in verb code 81.
  • vDoff — Built-in verb code 33.
  • vDown — Built-in verb code 15.
  • vDrink — Built-in verb code 39.
  • vDrop — Built-in verb code 22.
  • vEast — Built-in verb code 12.
  • vEat — A subject and a direction (60-69).
  • vEnter — Built-in verb code 31.
  • vExamine — One subject (20-49).
  • vFlip — Built-in verb code 28.
  • vGetOff — Built-in verb code 5.
  • vGive — Built-in verb code 58.
  • vIn — Built-in verb code 16.
  • vInventory — Built-in verb code 2.
  • vLie — Built-in verb code 9.
  • vLieOn — Built-in verb code 45.
  • vListen — Built-in verb code 36.
  • vLock — Built-in verb code 42.
  • vLook — Nothing to say (1-9).
  • vLookBehind — Built-in verb code 35.
  • vLookUnder — Built-in verb code 34.
  • vNorth — Built-in verb code 10.
  • vOpen — Built-in verb code 23.
  • vOut — Built-in verb code 17.
  • vPourInto — Built-in verb code 57.
  • vPress — Built-in verb code 29.
  • vPushEast — Built-in verb code 62.
  • vPushNorth — Built-in verb code 60.
  • vPushSouth — Built-in verb code 61.
  • vPushWest — Built-in verb code 63.
  • vPutBehind — Built-in verb code 52.
  • vPutIn — Built-in verb code 51.
  • vPutOn — Two subjects (50-59).
  • vSay — Built-in verb code 46.
  • vScore — Built-in verb code 4.
  • vShow — Built-in verb code 59.
  • vSit — Built-in verb code 8.
  • vSitOn — Built-in verb code 44.
  • vSmell — Built-in verb code 37.
  • vSouth — Built-in verb code 11.
  • vStand — Built-in verb code 7.
  • vStandOn — Built-in verb code 43.
  • vTake — Built-in verb code 21.
  • vTellAbout — Built-in verb code 56.
  • vThinkAbout — Built-in verb code 48.
  • vTurn — Built-in verb code 25.
  • vTurnOff — Built-in verb code 27.
  • vTurnOn — Built-in verb code 26.
  • vUndo — Built-in verb code 3.
  • vUnlock — Built-in verb code 41.
  • vUp — Built-in verb code 14.
  • vWait — Built-in verb code 6.
  • vWear — Built-in verb code 32.
  • vWest — Built-in verb code 13.
  • vWriteOn — Built-in verb code 47.