EXP Map Makingfor people who have never done it

AI tools

The toolkit

The scripts that read and write map and vehicle files directly. Plain Python, runnable by hand, no AI required.

The toolkit#

The toolkit is a set of Python scripts that read and write the game’s files directly. An agent uses them, but there is nothing AI about them β€” run them yourself from a terminal.

Getting it#

Only part of the toolkit is published so far. The expeditions-tools repository holds the base module tools (fob-modules), the custom model tools (map-models: import_model.py, after_pack.py, fix_map_model_brands.py), the map tools (map-tools) and the rock-light tool (rock-lights: add_rock_lights.py). The other scripts on this page, wiki.py among them, are not published yet; their commands are here so you know what exists.

Once you have it, put the folder anywhere you like and work from inside it. Every command on this page is written as if your terminal is in the toolkit folder:

cd <wherever you put the toolkit>
python wiki.py howto road

What you need first#

  • Python 3.11 or newer, with pip install pillow numpy requests
  • The game installed, because the scripts read its paks and call its converter
  • Blender 4.0 or newer, only if you are importing your own 3D models

The scripts find your game and your mod folder on their own. If they cannot, they say so and tell you what to set.

Run one thing first

python wiki.py howto road If that prints a list of documentation pages, everything is wired up. If it cannot find the game, it will say which path it tried.

They exist for the work the editor structurally cannot do: operations whose target changes continuously along a path, and operations over a whole network at once. Do not reimplement the editor’s brushes. Use the editor for sculpting and placement; use these for the rest.

Read the documentation first#

The single highest-value command here:

python wiki.py howto <road|river|trees|terrain|zones|sounds|overlays>

It returns every page for that topic from the 514-page official mirror, in reading order. howto road returns nine pages about overlays.

This exists because a day was lost carving roads into a heightmap while the editor’s actual road tool sat indexed in that wiki the whole time.

python wiki.py search "<phrase>"      # full-text across the docs
python wiki.py schema <type>          # the editor's own type definitions

Test a search tool with a question, not a keyword

The index returned nothing useful for “how do I make a road” for months, because it was only ever tested with words that were already known to be in it.

Terrain and roads#

need command
real-world elevation fetch_terrain.py <lat> <lon> --span --blocks
lay a road network make_overlays.py <level>
cut a graded bench sculpt_roads.py
smooth a roadway smooth_roadway.py
push heights into tiles push_heights.py
clear scatter from a road clear_roadway.py, sync_tiles.py
rivers paint_river.py, shape_river.py
build a whole map from real terrain build_map.py

A push into tiles is a merge, never a copy

Tiles hold hand sculpting done after the master was written. Protect water channels and take explicit no-go areas for ground you reshaped by hand.

Cap terrain movement near 3 m. Forcing a gradient onto a bad alignment once produced 30 m embankments, and a surface 30 m different from its surroundings has a cliff at every boundary.

Models#

need command
what models exist stock_models.py, list_installed_models.py
re-seat placements reseat_models.py
move a group move_cluster.py
check a custom model converts and loads verify_model.py
import a .glb as a placeable model import_model.py <file.glb> --name <name> --height <m> (published, map-models)
make custom models load in a packed map after_pack.py after every pack, or fix_map_model_brands.py <level> --apply for one map (published, map-models)

verify_model.py exists because ResourceConverter --mod-convert -s only tells you the files parse. Twenty-nine models passed it and then crashed the editor on placement. The script converts, keeps the output, and inspects the artifact the engine actually reads.

Scale is meaningless without the mesh

Read the bounding box out of the mesh and specify sizes in metres. Copying a scale distribution across a different mix of brands once turned a 6.84 m boulder into a 227 m potato stuck to a cliff.

Missions and zones#

need command
validate objectives before packing check_objectives.py <level> / --pak / --all
author the gameplay layer build_missions.py
write objectives, locks and rewards from one plan build_objectives.py <plan.json> / --apply
lock a custom truck and its parts behind those objectives vehicle_unlocks.py <plan.json> --mod <id> / --apply (how it works)

Run check_objectives.py before every pack. Objective errors are silent: a stage where every substage is optional is prohibited and errors, a null localOffsetScoutingAreaRelativeZone crashes, and a dangling globalZoneId hangs Deploy with no popup and no log line.

Packing and checking#

need command
pack a map pack_map.py
patch one member in place patch_member.py
identify a pak pak_fingerprint.py
a map misbehaves check_pack.py <Level>

check_pack.py comes before any theory. When a map misbehaves, run it first and read what it says, rather than reasoning about what might be wrong.

apply_loot_naming.py is disabled

It is still in the folder, and its own header says so: it broke a map for a week and must not be run. Older notes that tell you to run it after every pack are out of date.

Custom content#

need command
validate a FOB module check_fob_module.py
pack a FOB module pack_fob_module.py

An invalid $type in a FOB module is silently nulled at pack time, which is why a validator exists.

Vehicles#

python port_vehicle.py analyze <mod.zip>
python port_vehicle.py port <mod.zip> --id <modid> --name "My Truck"

Brings a SnowRunner vehicle into Expeditions: works out the required textures, writes source .tga maps, encodes them with the game’s own converter, rebuilds pc.pak, installs and registers the mod.

flag effect
--donor <dir> reuse real .tga files where the names match. Defaults to the game’s own sample mod, so genuine template textures are preferred over invented ones
--palette <json> {"material": [r,g,b]} colour overrides
--no-install build only, do not touch your mod folder
--work <dir> scratch directory
--skip-self-test skip the encoder verification. Do not

It verifies the encoder against a file the game itself produced before it changes anything, and refuses to continue if that check fails. The ordered procedure is the porting runbook; the explanation of the big failure is Porting a SnowRunner truck.

restore_addons.py β€” give a ported truck back its stock accessories#

python restore_addons.py analyze <main.pak> --pc <pc.pak>
python restore_addons.py fix     <main.pak> <out.pak> --pc <pc.pak> [--synthesize]

Bumpers, side steps and the spare wheel are separate addon classes, installed only because a socket names one in DefaultAddon. A port loses them two ways: the class lives in the donor game, or the mod dropped the default outright. Neither logs anything.

Pairs the mod’s truck class to the donor’s on socket names, not filenames β€” a mod renames the class file but cannot rename CJ7FrontBumper. Refuses to enable an addon whose mesh is absent, and reports textures with no encoded .pct. A truck with no confident donor match is reported as not checked rather than as passing.

--synthesize rebuilds a class neither game ships, from the donor’s template for that kind. Mesh-less addons only β€” cloning geometry between trucks bolts on the wrong part.

vehicle_ui.py β€” store and garage artwork#

python vehicle_ui.py --howto
python vehicle_ui.py mod.pak out.pak --shot shot.png --name Tundra \
    --box L T R B [--safe L T R B] [--exclude L T R B] [--badge TRD]

--howto prints how to compose the screenshots and what every image field is for. --box only has to contain the vehicle β€” the tool mattes it and measures the real silhouette. --exclude paints out a scene object standing against the bodywork, which otherwise survives the matte because it shares an edge with the vehicle.

Full field table in Store and garage artwork.

add_rock_lights.py β€” a rock-light kit on any truck#

python add_rock_lights.py                                         # asks step by step
python add_rock_lights.py --truck <class> [--plan | --remove]     # a truck in Media
python add_rock_lights.py --truck <class> --mod-dir <mod folder>  # an installed truck mod

In the rock-lights folder. Adds an empty slot to the truck’s class and five add-ons that fit it, White, Amber, Red, Blue and Green: eight lights each, on with the engine, with pods that are placed from the truck’s wheels and mounted on its own frame. --plan prints where each pod goes and changes nothing. On an installed mod it backs up each pak once. The method is explained in Rock lights on any truck.

Conventions these scripts follow#

Measure, then claim. Report the number, not the impression.

A zero result is a claim. Run a positive control before citing one. A search that returns nothing may be a search that was not looking in the right place.

Never write a backup into a folder the editor scans. Backups left in subgroups\ were loaded as empty SubGroups, and the symptom was models that would not highlight and snap appearing broken β€” both selection-driven, so one bug wearing two faces.