Make Text Adventure Objects Operable: Which Usage Clues Should Descriptions Reveal?
The player is stuck in the "old greenhouse" and enters "unscrew," "turn," "open," and "twist open" at a brass valve, but the system only replies, "You can't do that." The problem is usually not the verb library, but that the description does not provide usage clues. An operable object description must simultaneously reveal four types of information: material and structure, position and orientation, current state, and connections. Based on these, players infer "what can be done to it," rather than guessing the one unique verb in the author's mind.
Introduction
The player is stuck in the "old greenhouse" and enters "unscrew," "turn," "open," and "twist open" at a brass valve, but the system only replies, "You can't do that." The problem is usually not the verb library, but that the description does not provide usage clues. An operable object description must simultaneously reveal four types of information: material and structure, position and orientation, current state, and connections. Based on these, players infer "what can be done to it," rather than guessing the one unique verb in the author's mind.
The fictional teaching example "old greenhouse" is used throughout below. The characters, objects, and values in this example are all writing examples, not tested data.
First Look at a Description with No Clues
There is a valve in the corner of the greenhouse. Beside it on the ground is a strip of cloth, and on the shelf is a glass bottle.
This text can be read, but it cannot be operated. The player does not know what the valve is connected to, whether the cloth is dry or wet, or whether the bottle has a lid. Any verb can only be guessed. If the author writes the check to accept only "twist open the valve," then the player's inputs of "twist," "turn," and "wrench" will all be rejected. The frustration comes from missing items in the description, not from the player not being smart.
Comparison After Adding the Four Types of Clues
| Clue type | Static wording | Operable wording |
|---|---|---|
| Material and structure | There is a valve | The valve body is brass, a hex nut is stuck at the pipe opening, and the handle points up |
| Position and orientation | Beside it is a strip of cloth | The cloth is draped over the iron railing directly below the valve, with one end hanging into the standing water |
| Current state | On the shelf is a glass bottle | The glass bottle lies on its side on the middle shelf, the mouth is plugged with a cork, and the body has a fine crack |
| Connections | The valve is connected to a pipe | The upper end of the valve connects to a rusted vertical pipe, and the lower end connects to a short horizontal pipe; the horizontal pipe leads to a nozzle above the glass bottle |
With all four types of clues present, the player can infer: the valve handle can be turned; the cloth can absorb water or be wrapped around the handle; the cork can be pulled out; the nozzle is aimed at the bottle. The range of actions that can be attempted therefore becomes explainable, rather than an infinite verb list.
Write the Clues as a Range of Attempts
After the description, it is recommended to close with a sentence giving the "range of attempts," clarifying which actions are within the check and which are only environmental description:
You can turn the handle, wrap the cloth around the handle and then turn it, pull out the cork, and move the bottle out from under the nozzle. The valve is fixed to the pipework and cannot be moved away as a whole.
The purpose of this sentence is to draw boundaries. "Move the valve away" is excluded, so the player will not waste turns; "wrap the cloth around it and then turn" is included, showing that the combined action is feasible. The author does not need to list all synonymous verbs, only to explain the physical range of the action.
Object Action Word List
The same object will accept different actions in different states. First make a small table for each of the three objects in the old greenhouse.
Brass valve
| State | Actions that can be attempted | Not suitable to accept |
|---|---|---|
| Handle points up, nut is stuck | Turn the handle, wrench the handle, wrap cloth around it and then turn | Pull the valve off directly |
| Handle has been turned halfway | Continue turning, turn back to the original position | No removable structure is described, so the handle cannot be taken off directly |
Wet cloth strip
| State | Actions that can be attempted | Not suitable to accept |
|---|---|---|
| One end is soaked in water | Pick up, wring out water, wrap around the handle, wipe | Light on fire (the environment gives no fire source) |
| Wrapped around the valve handle | Pull tight, untie, turn together with the handle | "Use" alone |
Cracked glass bottle
| State | Actions that can be attempted | Not suitable to accept |
|---|---|---|
| Lying on its side, corked | Stand upright, pull the cork, move away; smashing requires confirming the consequences of destruction | Cannot collect water without pulling the cork |
| Has collected water | Pour out, put back on the shelf, place under the nozzle | Check whether it is already full before continuing to add water |
The word list is not a whitelist for checks, but a self-check tool for the author: for the actions listed under each state, corresponding clues should be findable in the description.
Distinguish Between Cannot Be Performed and Destruction That Can Be Performed
When an action cannot be performed, point out the missing condition; when it can be performed but will damage the object, first warn of the known consequence and let the player confirm. Do not write both types as "no." Synonymous verbs should be understood by intent, and everyday wording should not be treated as an error.
- Input "light the cloth strip": the cloth strip is wet, and there is no fire source in the greenhouse. The feedback can say, "The cloth strip is still dripping, and there is nothing around that can start a fire."
- Input "smash the glass bottle": first respond, "This will lose the water-collecting container. Do you still want to smash it?" Only after confirmation describe the fragments and change the object state to damaged.
- Input "open the valve": understand and execute it as turning the handle; only if the player explicitly asks to lift off a lid that does not exist should you explain that the structure does not support it. If the words differ but the action intent is the same, the same handling should be used.
Include clues in the feedback so the player can correct the action next time.
Completion Check
After writing a passage of object description, check it against these five items:
- Do the four types of clues each appear at least once?
- Is the "range of attempts" written out and is one obvious but invalid action excluded?
- Does each state have an action word list, and can the basis for every action in the table be found in the description?
- Does misuse feedback point out the missing clue, rather than only giving a negation?
- Is it avoided that only one unique verb is accepted?
If item 5 does not pass, change the check to accept synonymous actions or combined actions, then go back to the description and add clues.
When AI-generated narrative is involved, these clues must be written into the prompt constraints; prompt constraints do not guarantee that every output is correct, and the author still needs to manually check whether the generated result preserves material, position, state, and connections.
Next step: pick one object in your hands that is blocking the player, add the four types of clues according to the table above, and then write one sentence giving the range of attempts.
