# A Story For You — for an agent

> Interactive branching fiction in a URL: https://storyforyou.cc/

A Story For You is a zero-backend, client-side interactive text engine. A complete branching micro-quest,
escape room, or gamebook travels entirely inside the URL fragment (`#txt=...`). The browser never
sends the fragment to a server, requiring no database, accounts, or hosting fees.

This file documents how an AI can compile any story idea into a working, clickable link.

---

## 1. How to Write a Story Link

Output a single unbroken line:

    https://storyforyou.cc/#txt=title=Story+Title&author=Author&mood=storm&theme=parchment&start=n1&n1=Passage+text...|Choice+1->n2|Choice+2->n3&n2=...

### URL Parameters

- `title=`: Story title (use `+` for spaces).
- `author=`: Author or assistant name.
- `mood=`: Procedural ambient soundscape:
  `storm` (wind & rain), `dungeon` (cavern drone & water drips), `hearth` (crackling fire & warm pad),
  `space` (cold crystalline drone), `night` (crickets & nocturnal breeze), `cabin` or `quiet` (subtle room presence).
- `theme=`: Visual reading skin:
  `parchment` (warm paper), `slate` (night reading), `sepia` (vintage book), `terminal` (phosphor green), `midnight` (obsidian).
- `start=`: Starting node ID (defaults to `n1`).
- `n<id>=`: A passage node (`n1`, `n2`, `n_cellar`, etc.).

---

## 2. Passage Node Syntax

A node is formatted as:
`Passage text[+optional_grant]//Paragraph two.|Choice 1 -> target[tags]|Choice 2 -> target[tags]`

1. **Paragraphs:** Separate paragraphs with `//` (converted into indented book paragraphs).
2. **On-Entry Item Grants:** Append `[+item_name]` to passage text:
   `n_desk=You open the roll-top desk and find a brass key.[+brass_key]|Return to hall->n1`
3. **Choices:** Separated by `|`. Format: `Action Label -> target_node [modifiers]`
   - `Search the desk -> n2` (normal choice)
   - `Unlock the iron gate -> n3 [?brass_key]` (requires `brass_key` in inventory to be clickable)
   - `Light the torch -> n4 [?matches][-matches][+torch]` (requires and consumes `matches`, grants `torch`)
   - `Banish the phantom -> END [win]` (triggers victory screen)
   - `Step onto the fragile ice -> END [loss]` (triggers defeat screen)

### Tag Reference

- `[+item]`: Grants `item` to the reader's satchel.
- `[-item]`: Consumes `item` from the satchel.
- `[?item]`: Gating condition — choice is disabled unless `item` is in satchel.
- `[!item]`: Negative condition — choice is disabled if `item` is in satchel.
- `[win]`: Ends the story with a Victory badge.
- `[loss]`: Ends the story with a Defeat badge.

---

## 3. Best Practices for Story Authors

- **Length Budget:** Keep between 6 and 16 nodes (around 1,500 to 2,500 characters total) so the URL stays compact and easily shareable in chat apps without truncation.
- **Inventory Logic:** Introduce 1–2 key items early (e.g. `silver_key`, `crowbar`, `talisman`, `torch`) that unlock deeper branches later.
- **Atmosphere First:** Establish the sensory mood in the first sentence (smell of rain, ticking clocks, cold stone, distant thunder).
- **Multiple Endings:** Always provide at least one clear triumph (`[win]`) and at least one alternate fate or tragic end (`[loss]`).

---

## 4. Worked Example: The Alchemist's Vault

Here is a verified 6-node escape quest:

https://storyforyou.cc/#txt=title=The+Alchemist's+Vault&author=AI+Storyteller&mood=dungeon&theme=slate&start=n1&n1=You+wake+trapped+in+a+subterranean+laboratory.+Green+alchemical+flames+flicker+in+iron+sconces.//A+heavy+bronze+portal+bars+the+exit.|Inspect+the+stone+workbench->n2|Examine+the+bronze+portal->n3&n2=The+bench+is+covered+in+beakers+and+calcified+parchments.//Inside+a+lead-lined+box,+you+discover+a+vial+of+glowing+vitriol.[+acid_vial]|Take+the+vitriol+and+return+to+the+vault->n1&n3=The+bronze+portal+is+lashed+shut+with+thick+corroded+chains.|Dissolve+the+chains+with+vitriol->n4[?acid_vial][-acid_vial]|The+chains+are+too+thick+to+break;+search+the+room->n1&n4=The+vitriol+hisses+violently,+melting+the+iron+links+into+slag.//The+bronze+doors+creak+open+into+a+dark+spiral+staircase.|Ascend+towards+the+cool+night+air->n_win|Drink+from+the+glowing+basin+beside+the+stairs->n_loss&n_win=You+emerge+onto+a+wind-swept+hillside+under+a+canopy+of+stars.//You+are+free.|Take+a+deep+breath+and+walk+home->END[win]&n_loss=The+shimmering+liquid+burns+like+liquid+fire.//Darkness+consumes+your+senses.|Succumb+to+the+slumber->END[loss]