Area Descriptions

How to write the text players actually read: rooms, objects, weapons, armour, monsters, and action messages. Code makes an area work; descriptions make it worth exploring.

Rules for everything

8th grade reading level. Short sentences, common words. Fantasy terms (wight, pauldron) are fine; modern jargon is not. Watch for short, obscure words a 13-year-old would not know: write “loose rock”, not scree; “wedge-cut stones”, not voussoirs. A readability checker counts syllables and sentence length, not vocabulary, so judge words by hand too.
No em dashes. Use a comma or colon.
Go easy on hyphens. Ordinary noun pairs stay open: “mule cart”, “fish market”, “grain store”. Hyphenate only a true compound adjective before a noun (“thick-walled cistern”), and at most one per sentence.
No trailing \n. The driver adds newlines.
Narrator voice. Atmospheric and omniscient. Do not open with “You see”; just describe.
Match the area’s tone. A flooded crypt is grim and terse; a harbour market is lively and warm. Read nearby files first to catch the register.
Flowing, not inventory. “A well stands. A bench sits. A lane runs west.” reads barren. Write full sentences with mood and connection.
No transient life. Describe the place, not who is in it. Never write animals, people, or anything that spawns as present (“a dog sleeps by the gate”): spawns wander off and the text lies. Use traces instead (hoofprints, empty pens, a cottage), tiny unspawned life (crickets), or distant sounds.

Rooms

Element	Rule
`set_short`	2 to 6 words, lowercase unless a proper noun. A place or scene.
`set_long`	Concrete, layered, touchable detail. As long as the room needs, no filler. Layout first, atmosphere second.
`set_items`	Cover most nouns in the long. Important things 1 to 2 sentences, minor scenery 1.
`set_smell`	1 sentence, under 80 characters.
`set_listen`	1 sentence, under 80 characters.

Ground the room

The most common failure is a long that names the geography from above (“the ruins field opens to the northwest”) instead of putting the reader on the ground among real things. Two rules fix it:

Name particular, physical things, not categories. “Dead thistles rattling in a storm-ditch” beats “sparse vegetation”; “a toppled column half-buried in loose rock” beats “ruins”. Distrust terrain, vegetation, ruins, area, various, structures, scenery, features.
Fill the vertical layers. Touch at least two of the three, ideally all: underfoot (flagstones, mud, roots, worn steps), body height (a broken wall, a bench, a trough, a cart), and overhead (beams, a vault, hanging nets, branches, the sky). Give most of those nouns an item.

Length does not hurt readability. The grade comes only from sentence length and syllables per word, so a long, rich room still reads easy if it is built from short sentences and plain words. Fix a bad score by splitting sentences and swapping fancy words, never by cutting detail.

Bad Filler. The short names nothing, the long describes nothing, and the item just repeats its own key back to the player.

set_short("room");
set_long("There are some things here.");
set_items(([
    "things": "Just some things.",
]));

Bad Named geography. It reads correctly, but it describes the land from above. Nothing is underfoot, nothing is at body height, and there is nothing to touch.

set_long("The ruins field opens away to the northwest under a cold sky. The "
    "ground falls sheer to the east, and far below the sea and the isles lie "
    "spread in the haze.");

Good Indoor. Walls, floor, niches, and a bracket, each with its own item, plus a smell and a sound. Layout comes first, then mood.

set_short("the northwest corner of a crypt");
set_long("Moisture seeps through the stone walls, pooling in the grooves between "
    "ancient blocks. The floor is uneven, worn smooth by centuries of "
    "procession. Broken burial niches line the north and west walls, their "
    "contents long since plundered. A rusted iron torch bracket hangs empty "
    "above the largest niche.");
set_items(([
    "walls": "Ancient stone blocks, damp and darkened where water seeps between the joints.",
    "floor": "Worn smooth by generations of feet. A few flagstones have cracked and shifted.",
    ({ "niches", "burial niches" }): "Stone niches carved to hold the dead. Most are cracked open and empty.",
    ({ "torch bracket", "bracket" }): "A rusted iron bracket above the largest niche. Its torch is long gone.",
]));
set_smell("default", "The air smells of wet stone and old dust.");
set_listen("default", "Faint drips echo somewhere deeper in the crypt.");

Good Outdoor. The same ridge as the named-geography example, now grounded. Underfoot: paving, a storm-ditch, loose rock. Body height: thornbushes, thistles, a dead juniper. Beyond: the sheer drop to the sea.

set_long("A ruined gate stands here where the path tops the ridge, its arch fallen "
    "and its wedge-cut blocks heaped in the dead grass. Thornbushes and dry "
    "thistles crowd the old paving, and a shallow storm-ditch runs beside it, "
    "choked with grit and ash. Loose rock spills down either slope, past a "
    "lightning-killed juniper grey by the gate. Eastward the ground drops sheer "
    "to the sea far below.");

Objects, food, and drink

Element	Rule
`set_short`	Article, descriptor(s), noun. 3 to 8 words.
`set_long`	1 to 3 sentences, 20 to 40 words. Look and notable features. Hint at purpose, never state mechanics.
`set_id`	3 to 5 aliases: the type noun, the full name, key material and adjective combos.

Bad A bare noun for the short, a long that only restates it, and a single id, so get glass vial fails.

set_short("a vial");
set_long("It is a vial.");
set_id(({ "vial" }));

Good The short adds size and material, the long gives a detail worth looking at twice, and every reasonable name works as an id.

set_short("a small glass vial");
set_long("A small glass vial sealed with a wax stopper. The liquid inside shifts "
    "between amber and deep red depending on the angle of the light.");
set_id(({ "vial", "glass vial", "small vial", "small glass vial" }));

Weapons

Element	Rule
`set_short`	Article, material or descriptor, weapon type. 3 to 8 words.
`set_long`	1 to 3 sentences, 20 to 50 words. Blade or head, grip, condition. Hint at quality without stats.
`set_id`	Weapon type, full name, key material and adjective combos.

Bad Two flat sentences with no blade, grip, or condition to picture.

set_short("a sword");
set_long("A sword. It is sharp.");
set_id(({ "sword" }));

Good Blade, grip, and pommel in turn. The runes hint at something special without stating a single number.

set_short("a rune-etched steel longsword");
set_long("A longsword forged from folded steel, the blade etched with faint runes "
    "near the crossguard. The leather-wrapped grip is worn smooth from use, "
    "the pommel capped with a dull iron disc.");
set_id(({ "sword", "longsword", "steel longsword", "rune-etched longsword" }));

Armour

The same rules as weapons. The long should also describe the part of the body it covers, not just repeat the type name.

Bad It names the type and stops.

set_short("a helmet");
set_long("It is a helmet.");
set_id(({ "helmet" }));

Good Plates, visor, and lining, described as they sit on the head.

set_short("a riveted steel full helm");
set_long("A full helm of riveted steel plates, the visor hinged and raised to "
    "reveal the face. A ring of dried leather lines the interior where it "
    "meets the skull.");
set_id(({ "helm", "helmet", "full helm", "steel helm", "riveted steel helm" }));

Monsters

Element	Rule
`set_short`	Article, 1 to 2 descriptors, creature type. 3 to 8 words. `a`/`an` for common monsters, `the` for unique or boss monsters.
`set_long`	2 to 4 sentences, 30 to 60 words. Body, then notable features, then visible gear, then an optional hint of power.
`set_id`	Creature type, descriptor combos, plurals where they make sense.

Bad “It looks dead” tells the player nothing they could not guess from the word zombie.

set_short("a zombie");
set_long("A zombie. It looks dead.");
set_id(({ "zombie" }));

Good Body first (grey skin pulled tight), then a notable feature (the stump), then gear (the corroded blade), and a final hint that something is guiding it.

set_short("a grey-skinned barrow wight");
set_long("A corpse dragged back to motion by foul magic, its skin grey and pulled "
    "tight across the bones. One arm ends at a ragged stump. The other "
    "clutches a corroded blade, its grip too firm and deliberate to be "
    "anything but directed.");
set_id(({ "wight", "barrow wight", "undead", "corpse" }));

Action messages

Feedback when a player does something, uses an item, or the world reacts.

Type	Rule
Failure	1 sentence, under 80 characters. Describe the outcome, not the mechanic.
Success	1 sentence, under 80 characters. Evocative, never “You succeeded.”
Environmental	1 to 2 sentences, atmospheric.

Bad Each message reports a result without showing anything, and each ends with a stray \n the driver already adds.

write("You failed.\n");
write("You succeeded.\n");
message("info", "Something happened.\n", environment());

Good Failure. The player learns what resisted, not that a roll failed. write() goes to the acting player only.

write("The mechanism resists, and something grinds against your effort.");

Good Success. One short, physical sound instead of “You succeeded.”

write("The lock gives way with a dull click.");

Good Environmental. message("info", ..., environment()) sends it to everyone in the room.

message("info", "A cold draught pushes through the room, setting the torch flames sideways.", environment());

Before you submit

Text you just wrote always reads fine to you, because you already know what it means. These habits help you see it the way a player will.

Walk it in the game

goto each room and read it as a player would. Then look at every noun the long mentions. If the game says there is nothing there, add an item. Try listen and smell too. auditarea lists any rooms in a directory with a short long or only a few items.

Read it aloud

Wherever you stumble or run out of breath, the sentence is too long. Wherever you skim, it is filler. If you want a number, paste the prose (not the code) into a free readability checker and aim for grade 8 or below.

Come back tomorrow

A day away is the cheapest editor there is. Better still, ask another builder to walk the area and tell you what confused them or what they wanted to look at but couldn’t.

Common slips

Contradictions. A “rusted, empty bracket” in the long that “holds a burning torch” in its item.
Impossible details. A sealed full helm “revealing the face”.
A view from above. “The ruins stretch northwest” instead of what is underfoot, beside you, and overhead.
Vague nouns. Terrain, ruins, various where a real thing should be.
A list, not a place. “A well stands. A bench sits.”
Someone in the room. A dog, a guard, or a monster written into the long. It will wander off, and the text will be wrong.
Numbers showing through. “+3 damage” instead of “a wickedly sharp edge”.
The wrong mood. A cheerful line in a grim crypt.
Typos and stray characters. Em dashes and trailing \n included.