Writing puzzles for Castle Quest
Castle Quest's dungeons, mines, caves, ruined keeps and inn cellars can hold puzzles written by players. A puzzle is one small text file (a .json file) describing a few steps the adventurer must do in order: find something, read a clue, use an item, answer a riddle, pull levers, beat a guardian, or give something to a ghost.
About half the places a player explores for the first time get one of these puzzles. In a dungeon or a mine, solving it also opens the way to the lower floor.
Puzzles are also the building blocks of Mini Adventures: an adventure file ties 2 to 5 puzzles together with a story, and players take them one at a time from a village notice board. See Mini Adventures below.
How to make one
- Copy the example below into a plain text editor (Notepad is fine) and save it with a name ending in
.json, such asmy-puzzle.json. - Change the words to tell your own story. Keep the shape: the quote marks, commas and brackets.
- Open the puzzle checker, choose your file and press Check. It tells you exactly what to fix, step by step.
- When it says your puzzle is fine, send the file to the game's maker, who can add it to the game.
An example
This four-step puzzle is in the game now. Steps are done in order, from the top.
Loading...
The parts of a puzzle
| Part | What it is |
|---|---|
"id" | A short name in small letters, numbers and dashes, like "drowned-bell". Every puzzle needs its own. |
"title" | The puzzle's name, shown in the player's journal (up to 60 letters). |
"places" | Where it can appear: a list chosen from . Leave it out for dungeons, mines, caves and keeps. |
"minLevel" | The lowest player level it appears for, from 1 to 20. Leave it out for any level. |
"intro" | What the player reads when they first walk in. |
"things" | (Optional) your own words for the things in your puzzle, e.g. "bell": "A great bronze bell..." |
"steps" | The steps, in the order they must be done: 2 to 8 of them. See below. |
"reward" | What the player gets at the end: "gold" (0 to 500), "xp" (0 to 300, experience),
"magic" (true or false: true gives a magic item), and "text" (what they read when it's solved). |
The steps
Every step has a "type" and a "text": what the player reads when that step is done. A player may pick
something up early, but can't use it until its turn comes.
Things a step can happen at
Use one of these names for "at". The game draws them; you can describe them in your own words with "things".
Monsters
For a guardian ("fight") or something sitting on an item ("guard"):
The complete list (for puzzle generators)
Every field the game reads is below. For computer programs that write puzzles, the same rules are in the standard
JSON Schema format (puzzle-schema.json): give that file to your generator.
Fields not listed are ignored. Text fields must not be blank.
The puzzle
| Field | Needed? | Kind | Allowed |
|---|---|---|---|
id | yes | text | 1 to 40 of a-z, 0-9 and -. Unique. Also the file name. |
title | yes | text | up to 60 |
places | no | list | 1 or more of: dungeon, mine, cave, keep, cellar. Default: dungeon, mine, cave, keep. |
minLevel | no | whole number | 1 to 20. Default 1. |
intro | no | text | up to 400 |
things | no | thing name → text | names from the things list; each text up to 200 |
steps | yes | list of steps | 2 to 8, done in order |
reward.gold | no | whole number | 0 to 500. Default 0. |
reward.xp | no | whole number | 0 to 300. Default 40. |
reward.magic | no | true / false | true gives a vault prize: a better weapon, a magic item, an elixir or potions. Default false. |
reward.text | no | text | up to 400 |
Each step
| type | Needs | May have | How it plays |
|---|---|---|---|
find | item (up to 40), text | guard (monster) | An item in a spot of its own. Each find's item must be different. Done when its turn comes, even if picked up early. |
read | text | at (thing) | Without "at": writing on a wall in a spot of its own. With "at": shown when the player walks up to that thing. Done when its turn comes, even if read early. |
use | item, at, text | The item must come from an earlier find, and each item can be used or given only once (it is used up). Too early: "Nothing happens... yet". | |
give | item, at, text | As use, for handing something to a ghost or a prisoner. | |
riddle | at, question (up to 300), answers (2 to 5, each up to 60), correct (1 = first answer) | wrong (up to 300), text | Offered only on its turn. A wrong answer costs 6 strength; the player may try again. |
levers | at, levers (2 to 5 names, each up to 30), order (every name once), text | wrong (up to 300) | Offered only on its turn. The player sees "Pull the <name> lever". A wrong pull resets them all and costs 4 strength. |
fight | monster, text | name (up to 40) | A guardian in a spot of its own. Done when its turn comes, even if beaten early. |
Monsters, weakest to strongest
| Monster | Strength | Hits for | Suits |
|---|---|---|---|
| rat | 8 | 1-3 | level 1 and up |
| goblin | 12 | 2-5 | |
| wolf | 15 | 2-6 | |
| spider | 18 | 3-6 | |
| bandit | 25 | 3-8 | level 2 to 3 and up |
| scorpion | 30 | 4-10 | |
| hag | 30 | 4-9 | |
| skeleton | 30 | 4-9 | |
| orc | 35 | 4-10 | |
| dwarf | 35 | 5-11 | |
| bear | 45 | 5-12 | |
| werewolf | 65 | 6-12 | level 5 and up |
| troll | 85 | 6-14 | |
| ogre | 110 | 8-16 | level 8 and up |
| giant | 170 | 12-22 |
Will it fit?
Each of these needs a spot of its own: every different thing named in "at", every find, every fight, and every read without "at". Rough room for spots: dungeon about 10, keep about 10, mine about 7, cellar about 6, cave about 5, and a small animal den only 1 or 2. A puzzle too big for a place is simply not used there (in a dungeon or mine the way down is left open instead). Several steps can share one thing (a "use" and a "riddle" both at the bell, say) and that only needs one spot.
Never allowed
- The < and > signs, anywhere in the file.
- Files bigger than 64 KB.
Mini Adventures
A Mini Adventure is a small Castle Quest made from puzzles that are already on the website. The player starts in a village; its notice board shows the adventure's story and its puzzles as tasks. They take one task at a time, travel to its place (a dungeon, mine, cave or ruined keep a few squares away, marked on the map, or the inn cellar in the village), solve it, and come back to the board for the next. When every task is done, they get the adventure's reward. Players can work at the inn and buy gear at the smithy along the way.
An adventure is one small .json file, checked and uploaded with the same checker (it goes into the
adv folder). Upload its puzzles first: the checker makes sure every puzzle it names is on the website.
adventure-schema.json describes the format for puzzle generators.
{
"id": "trouble-at-the-mill",
"title": "Trouble at the Mill",
"story": "Strange things are happening around the village...",
"minLevel": 1,
"puzzles": [
"millers-secret",
{ "puzzle": "miners-ghost", "place": "cellar" },
"drowned-bell"
],
"reward": { "gold": 100, "xp": 80, "text": "The elders thank you with a purse of gold." }
}
| Field | What it is |
|---|---|
id | Required. A short name in small letters, numbers and dashes. Also the file name: adv/<id>.json. |
title | Required. Up to 60 letters, shown on the list of adventures and the notice board. |
story | Required. Up to 800 letters: what is going on, shown on the list and the notice board. Do not name the village: it is different every time. |
minLevel | Optional, 1 to 20 (default 1). The level the adventure is meant for; players below it are warned but can still play. |
puzzles | Required. 2 to 5 puzzle ids, each used once, in the order listed on the board (players may do them in any order).
To fix where a puzzle happens, write { "puzzle": "its-id", "place": "cellar" }; the place must be one the puzzle allows.
Otherwise the game picks one of the puzzle's places, so a puzzle that allows only cellar is always under the inn.
Only one puzzle per adventure can be in the cellar. |
reward | Optional, for finishing every task: gold (0 to 1000), xp (0 to 600), magic (true for a magic prize),
text (up to 400 letters). Each puzzle also gives its own reward when solved. |
As with puzzles, the signs < and > may not appear anywhere, and fields the game does not know are rejected.
Writing tips
- Every bit of writing goes between "double quote marks". If you need quote marks inside, use 'single ones'.
- The < and > signs aren't allowed anywhere in a puzzle (they could be used to slip web code into the game).
- Put a comma between the items of a list, but not after the last one.
- Numbers (gold, xp, minLevel, correct) and true/false have no quote marks.
- Give fair clues: a riddle's answer should be something a careful player can work out from the read steps.
- The checker catches mistakes, but it can't tell if your story makes sense: read it through once more.