Skip to main content
shapez 2 Wiki

Mods: Best Mods & How to Install Guide

Mods are user-created packages that alter or extend shapez 2 — from simple quality‑of‑life utilities to new machines, gameplay features, translations, or custom scenarios. The game has native mod support and a defined folder structure so mods can be installed, developed, and shared easily.

Where to put mods and persistent data

  • The game stores persistent data (including mods, custom scenarios, presets, and exported base data) inside the Game Data Folder (a.k.a. Game Data or save/game folder).
  • Paths:
    • Windows: %USERPROFILE%\AppData\LocalLow\tobspr Games\shapez 2\
    • MacOS: ~/Library/Application Support/tobspr Games/shapez 2/
    • Linux: ~/.config/unity3d/tobspr Games\shapez 2/
  • Open the folder from the game:
    • Main menu → Play → Show Folder, then go to the parent folder.
    • Ingame → Blueprint Library → Open Folder, then go to the parent folder.
    • Debug Console commands: logs.open-folder or savegames.open-folder (note: MacOS uses Player.log for some logging).

Mods folder layout and installation

  • The mods folder inside the Game Data Folder is where you place mods for the game to load locally.
  • Each mod is a subfolder inside the mods folder. The game will load each subfolder as a separate mod.
  • Steam Workshop mods are supported and will be downloaded automatically when subscribed via the Workshop.

Modding resources and tooling

  • Official and community resources:
    • Official modding documentation and art/asset guidelines provided by the developer.
    • Sample mods and Shapez Shifter (modding API) repositories are available on GitHub.
    • Unofficial community documentation exists to complement official docs.
    • Useful third‑party tooling documentation: MonoMod RuntimeDetour and HarmonyX for runtime detouring and patching.
  • The game uses Unity (specific Unity version noted in docs) and a modding API (ShapezShifter) to simplify integration; no external mod loader is required.
  • Assembly and class references are available for deeper development and debugging.

Creating and exporting game data to mod from

  • The game can export its internal data (base content like entities, scenarios, presets) for reuse or reference:
    • In-game, open the debug console (F1) and run debug.export-game-data.
    • This creates a folder named basedata- inside the Game Data Folder. Use files there as templates for custom JSON content.

Custom scenarios, presets, and difficulties

  • Custom Scenarios:
    • Place scenario JSON files into the custom-scenarios folder in the Game Data Folder for the game to load them.
    • The exported in-game scenario files appear in the scenarios folder of an exported basedata folder.
  • Custom Scenario Presets:
    • Put custom scenario preset JSON files in custom-scenario-parameter-presets in the Game Data Folder.
    • In-game scenario presets live inside scenario-parameter-presets in exported basedata folders.
    • When selecting a Scenario, the first Scenario Preset in the internal list that points to that Scenario is selected as the default.
  • Custom Difficulty Presets:
    • The game does not currently support loading custom difficulty presets directly as JSON files. You can still inspect the in-game difficulty presets in the difficulty-presets folder of an exported basedata folder.

Custom translations

  • To load custom translations, create a translations-override.json file with the same format as translations-en-US.json and place it where the game expects.
  • Start the game with the --custom-translations command line argument for it to load the override file.
  • The LanguageTitle inside the file is ignored; the language will appear as "Custom" in the language setting. Missing keys fall back to English.

Development workflow and debugging

  • Typical workflow:
    • Export base game data to use existing JSON as templates.
    • Create a mod subfolder with your assets, code, and JSON definitions following the documentation and art guidelines.
    • Use the modding API (ShapezShifter) or runtime patching libraries if you need to change code behavior.
    • Test locally by placing the mod folder into the mods directory and launching the game.
  • Debug Console is available in-game for commands and troubleshooting.
  • Debugging and runtime patching docs and community examples (sample mods) are recommended references.

Publishing and sharing mods

  • Steam Workshop:
    • Mods can be published to the Steam Workshop for automatic distribution.
  • Community sharing:
    • Blueprint and content sharing also happen via the Community Vortex website and the official Discord (#🛠blueprints).
  • Follow the game's mod publishing and asset guidelines when publishing to avoid conflicts or broken assets.

Topics & advanced considerations

  • Relevant modding topics covered in documentation:
    • Modding Overview, Development Environment, Mod Loading, Debugging, Mod Publishing, Command Line Arguments, Game Files, Custom Game Modes, Debug Console.
  • Use provided sample mods and API references to learn pattern and best practices.
  • When modifying or adding content as JSON (scenarios, presets, translations), ensure file naming and placement match the expected folders described above so the game recognizes them.

Quick checklist to get started

  • Export base data: open debug console → debug.export-game-data.
  • Create mod folder inside Game Data Folder/mods/ and add your content.
  • For custom scenarios or presets, put JSONs in custom-scenarios or custom-scenario-parameter-presets respectively.
  • For translations, create translations-override.json and start the game with --custom-translations.
  • Subscribe/publish on Steam Workshop to share or receive mods.
  • Consult official modding docs, sample mods, and ShapezShifter for code examples and API usage.

Pages featured in this guide