Content reference

The place to look up the exact name of a setting. If you’re just getting started, part 1 of the manual is the better place to begin, since it explains all of this step by step.

This reference lists every setting of every kind of content file, which can be found in your game’s content/ folder. Each file describes one thing, such as a stop or a boon. When you build, the build (engine/build.py) reads every one of these files and checks each setting. If something is wrong, it stops and tells you which file, which line and what to do about it. In that case, it doesn’t write anything.

The examples below are shortened to what matters. The example game in example/content/ has a working file of almost every kind. The first file of each kind also explains every one of its settings in comments. Those first files are also what new.sh copies when you make something new.

The rules for every file

• One thing per file. A file contains a single { ... } block.
• The file name decides the order. The number at the front sets the order of the things of that kind: 03-stop-3.jsonc comes after 02-stop-2.jsonc. To reorder things, simply renumber the files.
• An id is permanent. Saves remember things by it. Use lower case letters, numbers and hyphens, starting with a letter, like "old-harbour". Don’t change an id once people have played your game.
• Kinds of values. Text goes in double quotes, numbers go without them, yes or no is true or false and lists go in square brackets. Long text can also be written as a list of lines, which the build joins with spaces: ["the first part", "the second part"].
• Comments start with // and are fine anywhere, so each file can explain its own settings. That’s also why the files end in .jsonc, “JSON with comments”: editors then know that comments are allowed. The build forgives a comma right before a closing bracket, but some editors don’t, so it’s best to leave it out.
• Colours are written as #rrggbb (or #rgb), or as rgba(…) or hsla(…) for see-through colours.
• A setting the build doesn’t know is ignored. The build tells you about it, usually along with the name it thinks you meant.

The floor plan

Used by stops, floor shapes, event puzzles and chambers.

A floor plan is a list of eight lines with eight characters each. Every character is one square:

"floor_plan": [
  "00000000",
  "01111110",
  "01111110",
  "01122110",
  "01122110",
  "01111110",
  "01111110",
  "00000000"
]

What the build checks. Every square that isn’t a gap has to sit on a row of three squares, across or down, or it could never be matched. There has to be some stone to gild at all: a stop’s plan without a single 1 or 2 is refused. Where a plan has covers, every patch of covers that doesn’t match has to touch a square that starts clear, so the player can reach it. At least 16 squares have to start clear.

A covered amulet can’t be moved. Unless its cover says otherwise (the cover’s matches), it isn’t part of any match either. Once it’s free, it’s an ordinary amulet again and its stone is gilded when it’s matched.

Conditions

Used by relics (found_when) and by the looks (unlocked_by).

A condition block is a group of conditions and every one of them has to be met. null means “right from the start”. A number means “at least this many”.

Counted over all of the player’s journeys:

About the stop that was just won (so a relic can be found the moment the player wins a stop that meets these):

There is one more: relic, a relic’s id, so that finding one relic can unlock the next.

"found_when": { "stops_won": 1 }
"found_when": { "win_at_stop": "stop-2", "win_moves_to_spare": 5 }
"unlocked_by": { "stars": 15 }

Rewards

Used by relics, events and chambers.

A reward is a group of any of these: gold and lapis (whole numbers, 1 or more) and boon (a boon’s id, or "random").

"reward": { "gold": 45 }
"reward": { "lapis": 25 }
"reward": { "boon": "hammer" }

Stops (content/stops/)

A stop is one place on the journey, with its own floor, amulets, scenery and music. The stops come one after the other, in the order of their file names.

amulets is either one list of 4 to 6 amulet ids or a list of such lists, like [["round", "square", "triangle", "diamond"], ["round", "drop", "star", "diamond"]]. In that case, the game picks one of the lists at random each time the stop starts (restarts included).

music: key is a note, like "D3" (or a frequency from 40 to 1000 Hz). scale is one of hijaz, double harmonic, dorian, minor, major, mixolydian, lydian, phrygian, major pentatonic or minor pentatonic, or a list of semitone steps of your own. instrument is one of harp, lyre, oud, flute or bell.

Pictures. A stop’s scenery is images/backdrops/<id>.svg and what shows through the gaps in its floor is images/boards/<id>.svg (or a .png or .jpg of the same name). The build stops if one of them is missing. scenery and board_backing name a different picture instead, without the ending: "scenery": "stop-1".

map_position: x and y are measured in the map picture’s own units, which are set by the viewBox of images/icons/map/background.svg. label is "right" or "left": which side of the marker the stop’s name is shown on.

Floor shapes (content/floor-shapes/)

A floor shape is a floor plan that several stops can share. A stop names the ones it may use in its shared_floor_shapes and then, now and then, it’s played on one of them instead of its own floor_plan. That’s a nice way to give a stop some variety without drawing a new stop.

Amulets (content/amulets/)

An amulet is one of the pieces the player swaps. This file contains what How to play says about it. Its picture is images/amulets/<id>.svg (or .png).

Trials (content/trials/)

A trial is a task that can be offered at the start of a stop. If the player finishes it, they win its boon.

The goals are clear_amulets, make_specials, cascade, gild_in_one_move, clear_in_one_move, moves_to_spare, make_suns, make_bands, crack_thick, gild_half_quickly, no_boons and combine_specials. A clear_amulets trial should have {amulets} in its text, so it names the amulet.

Boons (content/boons/)

A boon is a power the player keeps and uses whenever they like. Players keep boons by their id.

The effects (★ means the player chooses a square first; the number is the default amount):

Badges (content/badges/)

A badge is a mark some amulets wear when they fall in. When the amulet is matched, the badge’s power is used. Its picture is images/badges/<id>.svg (96 by 96, with the badge as a circle with a radius of 24 in the middle); the build won’t accept a badge without one.

The powers (the number is the default amount):

The last four are meant for cursed badges.

Covers (content/covers/)

A cover is something that sits atop an amulet and keeps it in place, such as sand, water, amber, a net or ivy. A covered amulet can’t be swapped, doesn’t set off its special or badge and stays where it is when the board is shuffled. Its picture is images/covers/<id>.svg, drawn over the amulet on a canvas of 192 by 192 (the amulet’s square goes from 32 to 160). A cover can also have <id>-1.svg, <id>-2.svg and so on, for when it looks different with that many layers left. The first cover (by file name) is the one curses, omens and the cover_amulets badge power use, unless they’re told otherwise. Part 1, chapter 8, “A new cover”, explains all of this with a worked example.

A cover loses at most one layer in each step of clearing, however many matches touch it at once.

Curses (content/curses/)

A curse is what failing a trial costs the player, at the next stop only. The trial’s card names its curse before the player accepts it.

The effects are called hardships and the omens use the same list:

Omens (content/omens/)

An omen is a hardship a player may choose to face at a stop they’ve already gilded, in exchange for a bigger reward (how much bigger is omens.reward_percent_each in settings.jsonc). It lasts for that stop and its restarts. Saves remember omens by their id.

Relics (content/relics/)

A relic is a lasting reward for something the player has done. It’s found once and then kept in the Museum for good.

Events (content/river-events/)

An event is something that can happen between two stops. There are two kinds: a puzzle and a choice. (The folder is called river-events because the engine began as a game about a river journey.)

Every event has these settings:

How often events happen at all is river_event_percent in settings.jsonc.

A puzzle is a short game on a little board of its own:

A choice offers the player a small decision:

cost and give are rewards: a choice can cost gold or lapis and give gold, lapis or a boon. take_a_boon trades away one of the player’s boons. gamble leaves the outcome to chance. It’s a good idea to always include a choice that simply lets the player carry on.

On the scroll, each choice that does something becomes a card, much like a trial’s card. Its label is the heading, followed by “You pay:” and “You get:” lines made from its cost, give, take_a_boon and gamble. So keep the label a short action (“Pay for the shortcut”, “Join the dance”) and leave the price out of it. A choice that does nothing becomes the way out, below the cards. A card the player can’t afford stays on the scroll, dimmed, with the reason.

Chambers (content/chambers/)

A chamber is an extra place beside a stop, with a small board of its own. It opens once that stop has been gilded (and once the “chambers” stage has arrived on a first journey; see settings.jsonc). The player finds it on the win screen, on the stop’s card and as a doorway beside the stop on the map. The goal is always to gild the floor.

Its setting is either "tomb" (the default), which is dim and lit by torches, or "oasis", which is in daylight. (These are the engine’s names; what your game calls such places is up to its text.jsonc.) The two only differ in how they look and in one more thing: a tomb wakes a little more each time the player goes back in. Cursed badges turn up, more likely with every return and its reward for returning grows with them ("returning" in settings.jsonc; never on the easiest difficulty and not before curses have arrived on a first journey). An oasis stays calm.

Its floor plan may use any cover’s letters and its card explains every cover on its floor (with the cover’s chamber_note). Its reward is paid the first time; every later visit pays its return_reward.

It uses the stop’s amulets and music unless it has its own amulets. A tomb darkens its scenery and muffles the music, as if you were hearing it through the walls.

Checking a chamber. Type node engine/tools/events-sim.js. On a first visit, the bot should win it between about half and nine times in ten (50 to 90 per cent). The bot also plays each tomb as a first and a fourth return, which should come out harder.

The stall (content/stall/)

Something the stall sells: bought for one stop and used once (or kept until it’s used, for a second wind or a boon).

gives is one of: {"moves": n} (more moves, right now), {"reshuffle": true} (a reshuffle, right now), {"second_wind": n} (another try after running out of moves, kept until it’s needed) or {"boon": [ … ]} (a boon for the player’s hand, by its id or "random").

The Treasury (content/treasury/)

A lasting upgrade: bought one level at a time and kept for good.

The effects are extra_moves (more moves at every stop), badge_chance (added to how often badges fall), trial_chance (added to how often trials are offered), win_gold and win_lapis (paid for every stop won). Upgrades with the same effect add up.

The looks: amulet sets, floor sets, frames and sparkles

A look only changes how the game looks. All four kinds have the same basic settings, plus a few of their own. Players unlock looks by playing, or buy the ones that have a price.

Every player starts with one look of each kind. These are the ones named in edition.jsonc (starting_looks), or otherwise the first file of each kind. Never delete a starting look or change its id, since saves rely on them.

Amulet sets (content/amulet-sets/)

The same amulet pictures, recoloured, or pictures of the set’s own. Besides the settings every look has:

Pictures of its own. A set can bring its own pictures in images/amulet-sets/<its id>/, named after the amulets (round.png, square.png and so on). They’re drawn instead of the usual ones and any amulet without one keeps its usual picture. Small pixel-art pictures (say 16 by 16) look their best with "pixel_art": true.

The colour changes are hue_shift (in degrees, from −360 to 360), saturation, brightness, contrast, sepia and greyscale. Keep the amulets easy to tell apart: shift the colours rather than taking them away, or every amulet ends up looking the same.

Floor sets (content/floor-sets/)

The squares under the amulets. The file gives the look its name, description and unlock; its pictures can be found in the folder images/floors/<id>/: bare, thick and gilded (or gilded-1 to gilded-4, which are mixed across a golden floor). With "uses_each_stops_own_stone": true, the see-through bare and thick pictures are laid over each stop’s own stone_colour.

Frames (content/frames/)

The board’s frame.

Sparkles (content/sparkles/)

The sparks when a stone is gilded.

settings.jsonc

The numbers for the whole game. Every single one is optional: if you leave one out, the game uses the default shown here. The file itself has a comment beside each of them, too.

Pictures and icons (images/)

Every picture is a file of its own. Part 1 of the manual (chapter 6, “Pictures”) lists the folders, the names and the sizes. images/favicon.svg is the picture in the browser’s tab.

The map is the size of images/icons/map/background.svg (its viewBox) and each stop’s map_position is a place on it. Icons (the folders in images/icons/: dock, boons, relics, menu, codex, stall, ui and map) have to be SVG files. Keep each one’s viewBox and give gradients ids that no other icon uses, since the game shares them across the whole page. A relic uses images/icons/relics/<its id>.svg if there is one and otherwise the icon named by its "icon"; a picture in images/relics/ is used before either. The build complains about a file that isn’t one <svg viewBox="…"> drawing.

Sounds and music (sounds/, music/)

Recordings a game brings instead of the sounds and music the engine makes up. Both folders sit in the game’s folder, next to images/. Both are optional.

.wav, .ogg and .m4a work too. The recordings go inside the game file, so keep them small. A name the build doesn’t know is left out and the build says so, with the name it thinks you meant.

text.jsonc

Every word on screen, grouped by screen (hud, dock, title, menu, stages, win, lose, shop, stall, treasury, customise, saves, audio, map, journey, trial, event, popup, codex, conditions, boards, boons, omens, curses and so on). The keys on the left stay as they are; the text on the right is yours.

In the text, you can use **bold**, *italic*, \n for a new line, {name} for something the game fills in and {n|one|many} for a word that depends on a number. If the game asks for a key that the file doesn’t have, the build stops and names it.

The group names gives the word a name may start with ("article": "The ") and how it’s written in the middle of a sentence ("article_mid_sentence": "the "). That way, “The small hall” reads “Explore the small hall” and a relic reads “Find the golden key”. If you leave it out, names are always written as they are.

Appendix: every name the build knows

This appendix is written by the build (python3 build.py --docs) from the names in the code, so it always matches the engine. Please don’t change it by hand: your change would be replaced the next time.

The sections above list most of these already. This appendix puts all of them in one place. The build checks every content file against them and if one of them ever changes, the build’s error message lists the current ones.

Conditions (for found_when and unlocked_by). Counted: stars, three_star_stops, stops_gilded, stops_won, hard_wins, trials_finished, river_events, relics_found, suns_forged, best_cascade, thick_stones_cracked, gold_earned, gold_held, lapis_held, win_streak, journeys, seals_stamped, omens_braved and chambers_explored. About the stop just won: win_moves_to_spare, win_on_difficulty, win_at_stop, win_without_boons, win_on_board, win_two_specials_at_once, win_after_failures, win_with_omens, win_suns_forged, win_best_cascade and win_specials_made. And relic, so one relic can unlock the next.

Trial goals: clear_amulets, make_specials, cascade, gild_in_one_move, clear_in_one_move, moves_to_spare, make_suns, make_bands, crack_thick, gild_half_quickly, no_boons and combine_specials.

Badge powers (effect in badges): gild_stones, gild_around, gild_wide, gild_row_and_column, row_and_column, clear_around, clear_its_kind, break_covers, extra_moves, give_lapis, lose_moves, ungild_stones, thicken_stones and cover_amulets.

Hardships (effect in curses and omens): fewer_moves, fewer_moves_percent, thick_stones, thick_stones_share, thick_edges, fewer_badges, more_cursed_badges, buried_amulets, covered_edges and no_boons.

Boon effects: extra_moves, gild_stones, thin_thick_stones, cord_row, shatter_one, shatter_square, make_banded, make_sun, make_ringed and shuffle.

Boons (in rewards, stall items and events): the ids of the files in content/boons/, or "random" for one drawn at random from those with "random_reward": true.

Cover sounds: sand, splash, crack, stone, gild, blessing, create and land. Cover rules: broken_by is beside or on, layers goes from 1 to 9, matches and spreads are true or false.

Amulets: every picture in images/amulets/ is an amulet a stop can use (except sun, which is a special).

Special amulets’ pictures (in images/specials/): band, band-glow, band-arrows, ring, ring-glow, star-glow and star-points.

Relic icons: any file in images/icons/relics/ (without its ending), or a picture images/relics/<id>.png.

Music: the instruments are harp, lyre, oud, flute and bell. The scales are hijaz, double harmonic, dorian, minor, major, mixolydian, lydian, phrygian, major pentatonic and minor pentatonic, or a list of semitone steps of your own, like [0, 2, 3, 5, 7, 9, 10].

Sounds (to replace with a recording in sounds/): bad, blessing, bomb, coins, crack, create, gems, gild, land, line, lose, match, moves, page, refund, rollup, sand, select, shuffle, splash, stone, sun, swap, ui, unroll and win.

Treasury effects: extra_moves, badge_chance, trial_chance, win_gold and win_lapis.

Colour changes (in amulet sets): hue_shift, saturation, brightness, contrast, sepia and greyscale, applied in the order you write them (hue_shift is in degrees).

Currencies: gold and lapis.

Kinds of board (for win_on_board): classic, grand, ruins and omega.

Difficulties (for win_on_difficulty): the four names in settings.jsonc (difficulty), which are Relaxed, Normal, Hard and Hardest unless your game names its own.

Event goals (goal.type): gild, collect and score.

Floor-plan characters: . for a gap, 0 for already gilded, 1 for bare stone, 2 for thick stone and each cover’s two letters.

The starting looks: those named in edition.jsonc (starting_looks), or otherwise the first file of each kind. Every save begins with them and relies on them, so keep their ids.