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.
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.
1. Add a picture called preview.png to your mod folder. It is the
picture on the Workshop page. Keep it under 1 MB.
2. Fill in "title" and "description" in mod.json.
3. Open the Mods screen and choose Publish on your mod's row.
4. 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.
5. Choose who can see it: Private, Friends only, Unlisted, or Public.
Private is a good way to test first.
6. 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.