One More Adventure: Making and Sharing Mods

This guide explains how to make a mod for One More Adventure, how to test it, and how to share it with other players. You do not need to know how to program. A mod is a folder of pictures, music, and plain text files.

Mods work in the full game on Windows and Linux. The demo and the phone and tablet versions do not load mods.

The game also writes this guide into its mods folder as MODDING_GUIDE.txt.

1. The Mods Folder

The game makes a folder called "mods" next to the game itself the first time it starts. On Steam, you can find it by right-clicking the game in your Library, choosing Manage, then Browse local files.

Every folder inside "mods" that has a file called mod.json is one mod. Mods you subscribe to on the Steam Workshop are downloaded by Steam and load the same way, without going into this folder.

The game also keeps these in the mods folder for you:

MODDING_GUIDE.txt: This guide.
mod_log.txt: A report the game writes every time it reads your mods. It lists every mod it found, what each one adds, and every problem it ran into. When something does not show up, look here first.
_game_files: Copies of the game's own data files, tile pictures, and icons, to start your mods from. The game rewrites this folder whenever it is updated and never loads anything from it. Do not put your mod in it, and do not edit the files in it. Copy what you need into your own mod folder instead.

The game reads mods when it starts, and again when you leave the Mods screen after changing something there. It never reads them in the middle of a game. After you edit your own mod's files, restart the game to see the change.

2. The Mods Screen

Choose Mods on the title screen to see every mod the game found, both your own and the ones from the Workshop. Each row shows the mod's title, version, author, what it contains, and any problems.

The box at the left switches a mod on or off. A switched-off mod stays listed but adds nothing.
Move Up and Move Down change the load order (see section 14).
Publish (or Update) sends one of your own mods to the Steam Workshop (see section 17).

Your choices take effect when you leave the Mods screen.

3. Your First Mod

Make a new folder inside "mods", for example mods/my_first_mod. Inside it, make a plain text file called mod.json. Notepad is fine. It looks like this:

{
  "id": "my_first_mod",
  "title": "My First Mod",
  "version": "1",
  "author": "Your Name",
  "description": "What the mod does, for the Workshop page."
}

What each line means:

id: Required. A short name the game uses to tell mods apart. Use 1 to 64 letters, numbers, underscores, or dashes, and no spaces. Two mods cannot have the same id, and "base" is taken by the game. Saved games remember mods by their id, so do not change it once people are using your mod.
title: The name players see. If you leave it out, the folder name is used.
version, author: Shown on the Mods screen. Change the version when you update.
description, changenote: Used only on the Workshop page. The changenote tells subscribers what changed in an update.
max_level: Only for mods that change the level cap (see section 12).
workshop_id: Written by the game when you publish. Do not change it. It is how the game knows which Workshop item to update.

Then add one or more of these folders next to mod.json:

music/          New music sets.                        (section 5)
assets/         Tile sets for the map.                 (section 6)
monster_tiles/  Monster, character, and player icons.  (section 7)
data/           Settlement names and game content.     (sections 8 to 12)

Start the game, open the Mods screen, and check that your mod is listed. Then read mods/mod_log.txt to see what the game found in it.

A few rules for every mod:

Only pictures (PNG), music (MP3 or OGG), and text (CSV, JSON) are read. A mod can never run a program.
The game's fonts can only show plain English letters, numbers, and common punctuation. Accented letters lose their accents, curly quotes and long dashes become plain ones, and other symbols are dropped.
File and folder names are matched without caring about capital letters.

4. Looks Only, or Content

Every mod is one of two kinds. The game decides which by what the mod folder holds, not by anything the mod says about itself.

Looks-only mods change how the game looks or sounds: music sets, tile sets, icons, and settlement name lists. They are always safe. Your achievements stay on, and a saved game never needs them. If one is missing later, the game simply uses its own pictures and music instead.

Content mods change how the game plays: anything else in the data folder (monsters, items, quests, characters, vignettes, and so on) and the level cap. While a content mod is on:

A character that plays with it is marked Modded, for good. Turning the mod off later does not undo that.
A Modded character earns no achievements.
A Modded character's Hall of Champions entry shows "(Modded)" after its difficulty.
The game asks before it starts a new character, or loads one that is not Modded yet, so nobody is marked Modded by surprise. A loaded character is saved again right away, marked Modded.
A saved game made with a content mod will not load without that mod. The Load menu shows which mods it needs.

5. Music Sets

A mod adds new music sets. It never replaces the game's own music. Put your tracks in folders like these:

music/<Set Name>/title/      music for the title screen
music/<Set Name>/world/      music for the world map
music/<Set Name>/dungeon/    music for dungeons

Tracks can be MP3 or OGG files, and you may group them in more folders inside those three. A set does not need all three places.

Each set appears in Options, Audio, Music Sets, named after its folder. The game plays only the sets a player ticks there, shuffled, without repeats. If no ticked set has music for a place, that place is silent.

One mod can hold several sets, for example "Lute", "Strings", and "Lute and Strings".

6. Tile Sets

A tile set is the art for the map: terrain, settlements, caves, dungeons, and so on. The game ships two: KMAlexander and Gregs-Drawings. A mod tile set always appears as a new choice in Options (Tiles), so the game's own sets stay as they are.

There are two ways to make one.

Build on a game tile set. Name your folder after one of the game's sets, for example assets/KMAlexander. Inside it, use the same folder names the game uses (copy them from mods/_game_files/assets/KMAlexander). A picture with the same name as one of the game's replaces it, and a picture with a new name is added as another variation. Everything you leave out comes from the game's set. Players see it as "KMAlexander (Your Mod Title)".

Example:
  assets/KMAlexander/Plains/Plains03.png   replaces one plains tile
  assets/KMAlexander/Plains/Plains07.png   adds a seventh plains tile

Make a brand new set. Give the folder any other name, for example assets/Watercolor. Each terrain folder you include is used on its own, with only your pictures in it. A terrain you leave out comes from the KMAlexander set, so you can start with a few terrains and add more later. Players see it as "Watercolor (Your Mod Title)".

Tile pictures are PNG files with see-through backgrounds. The game's own are 101 by 101 pixels, and a hex always fits in that square. Your pictures can be any size:

Up to 101 by 101, a picture is drawn like the game's own, as crisp pixel art.
Bigger pictures are drawn as detailed art. The game keeps up to 505 by 505 pixels of detail, which is what one hex shows at the closest zoom, so zooming in looks sharp. Anything bigger is shrunk to 505 when the game loads it. When zoomed out, the game shrinks the picture smoothly.
A picture that is not square keeps its shape. The game centres it in the hex and the terrain's own colour fills the rest.

A few folders work a little differently:

Adding a picture to a terrain folder adds a variation. Which variation each hex shows is picked from its position, so adding one reshuffles the look of that terrain. It changes nothing else.
Caves and Manmades are the pictures for caves and ruins. Added pictures are used too.
PlayerBoat uses only its first picture.
Dungeons/TreasureChests are found by words in the name: open, unlocked, and locked.
Flames, FairieFire, GreenClouds, Silver, Treasure, PointOfInterest, and QuestMarker are pictures that are not terrain. To change them, put them inside your tile set folder, for example assets/KMAlexander/QuestMarker/QuestMarker01.png. They then apply while your tile set is chosen. FairieFire pictures are animation frames, so you can add more.

7. Icons and Player Portraits

Monster, character, and player portraits live in monster_tiles. The same naming rule applies: a PNG with the same name as one of the game's replaces it, and a new name adds an icon. You can see every name in mods/_game_files/monster_tiles.

An icon's background can be see-through in either of two ways, or both:

A PNG with see-through pixels, the same as a tile picture. Soft and partly see-through edges work.
Pure magenta (red 255, green 0, blue 255) wherever the background should be. This is how the game's own icons work. Do not smooth the edges into the magenta, or a pink rim shows.

The game's icons are 54 by 54 pixels. Icons can be any size, and follow the same rules as tile pictures: over 101 by 101 they are drawn as detailed art, up to 505 by 505 is kept for zooming in, and a picture that is not square keeps its shape. The game smooths the edges of detailed icons itself when it shrinks them, so magenta edges should stay hard even on a big picture.

A new picture becomes a player portrait in character creation when its name starts with one of these words:

Barbarian, Elf, Female, Gnome, Halfling, Human, People,
HB_Dwarf, HB_Elven, HB_Guard, HB_Human, HB_Ranger

For example, HumanSheep01.PNG shows up as a portrait.

If a player loads a character whose portrait came from a mod they no longer have, the character simply gets a plain portrait.

8. Settlement Names

Town names are made of pieces: a prefix, a root, and a suffix, with separate lists for small, medium, and large settlements. There is one list for each people: human, elf, and dwarf.

data/settlement_names_human.csv: Replaces the human lists. It must have at least one root for every size (small_root, medium_root, large_root).
data/<creator>_settlement_names_human.csv: Adds words to the human lists. <creator> is your own name (see section 9).

The columns are small_prefix, small_root, small_suffix, medium_prefix, medium_root, medium_suffix, large_prefix, large_root, and large_suffix. Copy the game's file from mods/_game_files/data to start.

Name lists only change worlds made while the mod is on. Towns in a saved game keep the names they already have. You cannot add a new people, because that would change how worlds are made.

9. Game Data: Replace or Add

The game's rules and content are tables in plain text files. You will find a copy of every one in mods/_game_files/data. CSV files open in any spreadsheet program. Save them as CSV again, not as a spreadsheet.

Your mod can change a file in one of two ways, chosen by the file's name in your mod's data folder:

data/items.csv: REPLACES the game's file completely. The game reads yours instead. Use this to change rows the game already has (copy the game's file and edit it), or for a total conversion.
data/<creator>_items.csv: ADDS rows to the game's file. <creator> is your own name, made of letters, numbers, underscores, or dashes. "user" is taken. For example: data/samwise2000_items.csv.

Only one mod may replace any one file, but any number of mods may add to it. Additions also work on top of a replacement.

The rules for added rows:

New rows need new ids of 1,000,000 or more. The game will never use an id that high, so your rows can never clash with a future update. A row with a lower id is skipped. To change one of the game's own rows, replace the file instead.
Two mods cannot add the same id to the same file. Pick a starting number that is unlikely to be taken, such as 1,250,000, and count up from there.
Your file needs the column that identifies a row (usually "id"), but it may leave out other columns and put them in any order. Columns the game's file does not have are reported in mod_log.txt and ignored.
Some files are not keyed by an id. In the six level tables a row is a level, in the loot tables it is a level (HD) or a distance, and in abandoned_structure_treasure.csv it is a monster and item pair. Added rows must use a key that is not already there.

The files a mod can replace or add to:

monsters.csv                   monsters
abandoned_structure_monsters.csv
                               monsters found only in Ancient Magic
                               Centers
abandoned_structure_treasure.csv
                               what those monsters guard
items.csv                      items
enchantments_and_curses.csv    magic item enchantments and curses
loot_table_a.csv, loot_table_d.csv, loot_table_h.csv,
loot_table_m.csv, loot_table_u.csv
                               treasure carried by animals, dragons,
                               humanoids, other monsters, and undead
loot_table_c.csv               treasure in chests
loot_table_p.csv               what is inside found packs and purses
quests.csv                     quests (see section 10)
characters.csv                 named characters you can hire
hirelings.csv                  hireling types you can hire
bandit_parties.json            bandit parties and quest fighters
                               (see section 11)
vignettes.csv                  dungeon traps and puzzles
vignettes_prepper.csv          the Prepper's notes
vignettes_world.csv            world map scenes
the six level tables           see section 12
settlement_names_*.csv         see section 8

These files cannot be changed by a mod: achievements.csv, spells.csv (spells work through the game's code), weapon_former_names.csv, encounter_tables.csv, Feats.txt, and Tips.txt. The game does not read encounter_tables.csv at all. Where a monster appears in the wild is set by the preferred_biomes column of monsters.csv.

A monster's "type" column decides which loot table its treasure comes from. Only these types work: animal, humanoid, undead, dragon, and monster.

10. Quests, Characters, and Hirelings

Quests. Add quests with data/<creator>_quests.csv. The easiest way to start is to copy a side quest chain from the game's quests.csv, give every row a new id from 1,000,000 up, and change the text. The steps of one quest share a chain_id. An added quest's chain_id must be left blank or be 1,000,000 or more, and it may not be another mod's chain id, so your steps can never join one of the game's own quests by accident.

Quest ids of 1,000 and up are side quests, so every mod quest is a side quest. A mod quest that starts on a notice board appears there along with the game's, and shares the same limits on how many quests a village, town, or city offers.

When a quest names a character, it uses the character's name. When it names a monster or an item, it uses that row's id.

Named characters. Add characters with data/<creator>_characters.csv. The game finds named characters by name, so a new character's name must not already be in the file. Rows that reuse a name are skipped, and two mods that add the same new name cannot be on together. A character's settlement_spawn column says which settlement sizes they appear in. A hire_fee of 0 means they never appear in taverns, and can only be met through a world scene that rescues them by name.

Hirelings. Add hireling types with data/<creator>_hirelings.csv. Hirelings are types, like "Militia Recruit", so names may repeat. A hireling appears in taverns of its own people (the race column: Human, Elf, or Dwarf), at the world's technology level. Small settlements only offer level 1 hirelings, medium ones up to level 2, and large ones up to level 3.

The weapon_id, armor_id, and similar columns of characters and hirelings are item ids. They can point at the game's items or your own. The icon column is the name of a picture in monster_tiles, the game's or your own.

11. Bandit Parties

The "Adventurers Gone Bandit" scene pits the party against a band of other adventurers of the player's level. The bands, and a few fighters used by quests, are in bandit_parties.json. Look at the game's copy in mods/_game_files/data to see what a band looks like.

To add bands, make data/<creator>_bandit_parties.json like this, with each actor written out in the same way as the game's:

{
  "parties": [
    {"target_level": 3, "actors": [ ... ]}
  ],
  "quest_actors": [ ... ]
}

A band needs a target_level from 1 to 20 and at least one actor. The game only has bands for levels 1 to 10. Bands for levels 11 to 20 are for mods that raise the level cap.
Each band is fought once by each character. When a level has several bands left, the game picks one at random. Once all the bands for a level are beaten, the scene is an empty campsite.
Keep your bands in the same order when you update your mod, and add new ones at the end. The game remembers which bands a character has fought by their place in your file.
Quest actors are found by name. A name already in the file is skipped, and two mods cannot add the same new name.

12. The Level Cap

Characters normally stop at level 10. A mod can change that by adding "max_level" to its mod.json, with a number from 1 to 20:

{
  "id": "epic_levels",
  "title": "Epic Levels",
  "max_level": 15
}

The six level tables must then have a row for every level up to the new cap. Add the rows with <creator>_ files, the same way as other additions:

experience_required_per_class_level.csv   experience needed
base_attack_bonus_advancement.csv         base attack bonus
base_spell_bonus_damage.csv               magic damage bonus
saving_throw_per_level.csv                magic resistance
actions_per_round.csv                     actions per round
hit_dice_per_level.csv                    hit dice

Each of these has a Level column and one column for each class and class mix: Fighter, Rogue, Mage, Fighter_Rogue, Fighter_Mage, Rogue_Mage, and Fighter_Rogue_Mage. Fill in every column of every new row.

In the experience table, the row for a level is the experience needed to go up FROM that level. So the row for your top level is never used. The game's own level 10 row is like that.
In the hit dice table, a row is the total dice at that level, for example 11d8 at level 11.
If any of the six tables is missing a level, the cap stays at 10 and mod_log.txt says which table and which levels are missing.
Spells only go up to tier 5. Above level 10, spellcasters still gain mana, prayers per day, and damage from their level, but no new tier.
Party members and hirelings follow the same cap.
Only one mod at a time may set the level cap.

A mod may also LOWER the cap, for a low-power game. It needs no new rows. A character who is already above the cap keeps their level, but gains no more. To play the low-power game in full, use a new or low-level character.

A level cap counts as content, even in a mod with nothing else in it.

13. Files That Go Together

Changing only the values in a file, and keeping every id, is always safe. Rebalancing a monster, renaming an item, or changing a price does not affect any other file.

Dropping or renumbering ids is different. Many files point at rows in other files by their id, or by their name. If you replace a file and an id or name that another file points at disappears, the game will go wrong. The game does not check this for you, so you need to replace the other files in the same group too.

These files stand alone and can be replaced on their own:

settlement_names_human.csv, settlement_names_elf.csv, and settlement_names_dwarf.csv
the loot tables, as long as they keep the same rows (50 each)
vignettes.csv and vignettes_prepper.csv
enchantments_and_curses.csv

The six level tables go together. Replace all six at once, with the same levels and the same class columns.

The rest of the game's content is one connected web:

quests.csv points at: other quests, monsters (by id), items (by id), and characters (by name)
items.csv points at: quests (quest items and quest starters)
characters.csv and hirelings.csv point at: items (their gear) and icons
vignettes_world.csv points at: monsters (by id) and characters (by name)
abandoned_structure_treasure.csv points at: abandoned_structure_monsters.csv and items.csv
bandit_parties.json points at: items (their gear), quests, and icons
monsters.csv and abandoned_structure_monsters.csv point at: icons

So, if you drop or renumber ids in:

monsters.csv          also replace quests.csv and vignettes_world.csv
items.csv             also replace quests.csv, characters.csv,
                      hirelings.csv, abandoned_structure_treasure.csv,
                      and bandit_parties.json
quests.csv            also replace items.csv and bandit_parties.json
characters.csv names  also replace quests.csv and vignettes_world.csv
abandoned_structure_monsters.csv
                      also replace abandoned_structure_treasure.csv

A total conversion replaces the whole web.

Some rows are used directly by the game itself. Keep these when you replace a file, or the thing next to them stops working:

Items (by id)
  1, 2, 6, 8, 13, 18, 27, 30, 37, 39, 40, 41, 45, 46, 47, 57, 61, 68,
  69, 72, 101   starting gear in character creation
  5, 33         Sarah's sword and armor
  7, 19         weapons only dwarves or elves can train in
  11            the Shillelagh spell's club
  13            the staff
  22 to 26, 74  firearms
  52            a ring given to one quest's bandit
  62            the purse
  66            rations
  69, 70, 71    arrows, bolts, and bullets
  106, 107, 108 the Ancient Magic Center's prizes

Enchantments (by id)
  10            Sarah's sword
  103 to 106    kept out of random treasure

Monsters
  47            Sarah, when she fights the party
  275, 278      the werebear and werewolf curses
  618           the Steel Golem's arena
  "Giant Rat"   what the Polymorph spell turns a target into
  "Spectre", "Specter", "Vampire"
                drain two levels instead of one

Characters (by name)
  "Sarah"       her quest chain
  "Hans"        a quest statue

Quests: Ids below 1,000 are the main story. Several of them, and a few side quests, are used directly by the game: the race stories that lead into the main story, the Upyr College, the end of the main story, and the Sarah and bandit-ring quests. A total conversion may drop the story. The game then simply never reaches those parts.

World scenes
  1001          reserved for statues

Bandit parties
  The quest fighters "Thaddeus the Paladin", "Michael Hopeland",
  "Congregant", "Insurance Broker James", "Lord David McKenzie", and
  "Lannewyn the Druid" are found by name by their quests.

Words with fixed meanings. Some columns only understand words the game knows: a quest's objective type, origin, and reward and gate words; a vignette's failure effects and reward types; an item's category, slot, and effects; an enchantment's effect; a monster's type; terrain names; class names; and equipment slot names. Copy them from the game's own rows. A word the game does not know does nothing.

Spell scrolls and Shelf Stable Magic are found by their effect, not their id, so any item with the same effect works the same way.

14. Load Order and Clashes

Mods load in the order shown on the Mods screen. Where two mods supply the same thing:

Icons: the mod lower in the list wins.
Tile sets: every mod's tile set is its own choice in Options, so they never clash.
Rows added to the same file: all of them are added, in order.
Settlement name lists: the first replacement in the list is used, and every addition is added.

Some clashes are too risky to guess at. If any of these happen, the game loads no content from any mod (looks-only parts still load), and mod_log.txt names the mods involved:

two mods replace the same file
two mods add the same id to the same file
two mods add a named character, quest fighter, or quest chain with the same name or id
two mods set the level cap

Fix it by switching one of the mods off on the Mods screen.

15. Saved Games and Mods

A saved game remembers which mods it was played with.

A looks-only mod is never required.
A save made with a content mod needs that mod. Without it, the Load menu shows "needs mods:" and the mods' titles, and the save will not open.
A save made with replaced files needs the same files replaced by the same mods. The Load menu shows "made with other replaced data".
Turn the mod back on, or subscribe to it again, and the save opens.

Saves sync between computers with Steam Cloud. Workshop mods follow your Steam account, but mods you put in the mods folder yourself do not. Copy those to every computer you play on.

16. Testing Your Mod

After each change, restart the game and read mods/mod_log.txt. It shows exactly what was loaded, and the reason for every row or file that was not. The Mods screen shows the same problems on each mod's row.
Test content mods with a new character you do not mind being marked Modded.
New items show up in shops and treasure by their rarity and technology level. New monsters show up in the wild by their preferred_biomes, and in dungeons, once the party has enough experience (min_xp_tier).

17. Sharing Your Mod on the Steam Workshop

You can publish a mod straight from the game. Steam must be running.

Add a picture called preview.png to your mod folder. It is the picture on the Workshop page. Keep it under 1 MB.
Fill in "title" and "description" in mod.json.
Open the Mods screen and choose Publish on your mod's row.
Check what the screen says will be uploaded. Only mod.json, preview.png, and the music, assets, monster_tiles, and data folders are sent. Anything else in your folder, such as source files or notes, stays on your computer.
Choose who can see it: Private, Friends only, Unlisted, or Public. Private is a good way to test first.
Read the Workshop terms of service (the screen has a link), then choose Submit. An upload cannot be cancelled once it starts.

The game writes the new Workshop item's number into your mod.json as "workshop_id". The button then says Update. To update, change your files, raise the "version", write a "changenote" in mod.json, and choose Update. For updates, the visibility starts on "Keep as it is".

The game adds the Workshop tags for you, from what the mod contains:

Music              music sets
Tile Art           tile sets
Icons              icons and portraits
Monsters           monsters.csv or abandoned_structure_monsters.csv
Items              items, enchantments, loot tables, or
                   abandoned_structure_treasure.csv
Quests             quests.csv
Total Conversion   replaces quests.csv, so it brings its own story

If Steam says you must accept the Workshop legal agreement, the game tells you. Your item stays hidden until you accept it on Steam.

Players who subscribe get your mod the next time they start the game. If you have the same mod in your own mods folder, your folder copy is used, so you always test your latest version.

18. Sharing without the Workshop

A mod is just a folder, so you can also share it as a zip file. The player unzips it into their mods folder, so that mod.json ends up at mods/<your mod>/mod.json, and starts the game.

19. Quick Troubleshooting

My mod is not listed.: Check that mod.json is directly inside your mod folder, that it has an "id", and that it is valid JSON (every line except the last ends with a comma, and every text is in double quotes). mod_log.txt says why a folder was skipped.
My new rows are not in the game.: Check that their ids are 1,000,000 or more, that the file name is <creator>_<game file name>, and read mod_log.txt.
Nothing from any content mod works.: Two mods clash. mod_log.txt names them. See section 14.
My saved game will not load.: It needs a mod that is missing or switched off. The Load menu says which. See section 15.
My tile set is not in Options.: Check that the pictures are PNG files inside assets/<Set Name>/<Terrain>/.
My music set is silent.: Tick it in Options, Audio, Music Sets, and check that the tracks are in a title, world, or dungeon folder.