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.pyamong 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.