Welcome, Commander!

This tutorial will guide you through creating your first template-based mod for Xenonauts 2. We’ll start from scratch — no prior modding experience needed. By the end, you’ll have a working “Hello World” mod and a solid understanding of how to tweak game data.

Quick reference, example data mods:

• X2-Modding/example-mods

Xenonauts 2 is designed with content packs and templates that make modding accessible. Game data (weapons, items, units, etc.) is defined in human-readable text files (usually JSON). A mod in X2 is essentially a new content pack containing template files that override or add to the base game data. You don’t need special tools – a simple text editor will do. We’ll walk through setting up a mod folder, creating template files, and activating the mod in-game.

What you’ll learn:

• The folder structure for Xenonauts 2 mods and where to place files.

• How to create a manifest.json for your mod.

• How to override existing game templates (examples: adjusting cover values, weapon damage, unit health).

• How to follow naming conventions and manage mod dependencies.

• How to enable your mod in-game and test your changes.

Let’s get started!

The first step is to set up a dedicated folder for your mod, with a manifest file that tells the game about your mod.

1. Locate the Game’s assets Directory: Find the assets folder in your Xenonauts 2 installation. This is where the base game content and mods reside. Inside, you’ll see a folder called xenonauts which contains the core game assets.

   1. Use this folder to find out what assets exist!

2. Locate the Game's local mod directory: Find the My Games/Xenonauts 2 folder in your My Documents (or Linux equivalent). This is where the game stores saves, settings, logs and local mods. Inside should be a folder called Mods, if not, create it.

   1. Locate the Game's log folder: The folder named Logs in the local data folder will hold the logs of the game, which you'll need to debug.

3. Create a New Mod Folder: In the Mods directory, create a new folder for your mod. You can name it something descriptive for your mod – for this tutorial, we’ll use my_first_mod (avoid spaces and uppercase; see naming tips below). Your folder structure should look like:

   My Documents/Xenonauts 2/Mods/
   └─ my_first_mod/             (your mod content pack)
   

4. Create a Manifest File: Inside my_first_mod, create a file named manifest.json. This file is required and tells the game engine it’s a content pack. Open manifest.json in a text editor and add the following JSON content:

   {
      "version": "0.0.4",
      "asset": {
          "Name": "My First Xenonauts 2 Mod",
          "UID": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", // Use https://www.uuidgenerator.net/
          "Description": "A simple mod that tweaks some game values for demonstration.",
          "Author": "YourName",
          "Website": "",
          "Tags": ["Balancing"],
          "Version": "1.0.0",
          "$type": "Common.Content.DataStructures.ContentPackManifest"
      },
      "$type": "Common.Content.DataStructures.VersionedAsset"
   }

   Let’s break down these fields:

   • Name: A human-readable name for your mod (appears in the mod list in-game).

   • UID: A unique identifier string (UUID) for your mod. Tip: You can use an online UUID generator, or leave it blank and the game will generate one on first load. https://www.uuidgenerator.net/

   • Description: A brief description of what your mod does.

   • Author: Your name or handle.

   • Website: (Optional) URL if you have a page for your mod.

   • Tags: Keywords categorizing the mod (e.g. "Mod", "Balance", "Items").

   • Version: Your mod’s version number (you choose the format, e.g. 1.0.0).

   • $type fields: These should remain as shown – they inform the game of the data structure types (content pack manifest). Use the same $type lines as in the example.

   Make sure the JSON syntax is valid (commas, braces, and quotes in the right places). This manifest will allow the game to recognize and load “MyFirstMod” as a content pack.

5. Folder Structure in Your Mod: Inside your my_first_mod folder, you will create sub-folders that mirror the structure of the base xenonauts pack for any assets you want to override or add. The general asset path format in Xenonauts 2 is:

   <ContentPack>/<TypePrefix>/<Screen>/<TypePostfix>/<Name>.<Ext>.

   • ContentPack: This is either xenonauts (base game) or your mod’s folder (e.g. my_first_mod).

   • TypePrefix/TypePostfix: These are folder categories for asset types (e.g. template as prefix for data templates. TypePostfix is used if we further want to carve it up, but often left out.

   • Screen: The game screen or context the asset belongs to (e.g. groundcombat, strategy, common, etc. – more on this below).

   • Name and Extension: The specific asset file name and extension (for templates, the extension is .json).

   For example, if we want to override a ground combat template from the base game, we would place our mod file under my_first_mod/template/groundcombat/... following the same sub-path as in the xenonauts folder. We will see this in action in the examples below.

Naming Conventions: Xenonauts 2 enforces strict naming rules for files and folders:

• Use lowercase letters and underscores for names. For example, plasma_rifle.json is good, whereas PlasmaRifle.JSON is not.

• Use singular nouns for folder names and types. (The base game uses some plural folder names like “blueprints”, but when naming your own files/folders, stick to singular to avoid mistakes.).

• No spaces or special characters in names. Use underscore _ instead of spaces.

Following these conventions ensures the game can find and load your mod assets without issues.

With the folder and manifest set up, we’re ready to add content to the mod!

Now we’ll create a simple example mod within MyFirstMod. This mod will adjust the cover protection value of “Full Cover” in ground combat. It’s a classic “Hello World” for Xenonauts 2 modding – a small change that’s easy to test.

What is a “blueprint” template? In Xenonauts 2, environmental objects like cover are defined as blueprint templates (under the blueprints category). For instance, low walls, rocks, and other cover objects have templates that define how much protection they offer. In the base game, a Full Cover object might stop 60% of incoming fire by default【30†source】. We’ll change that to 80% to see the effect.

Follow these steps:

1. Identify the Base Template Path: We need to find the template that defines Full Cover in the base game content. Browsing the base xenonauts assets (or referring to the modding documentation) shows that cover templates are located in:

   xenonauts/template/groundcombat/masters/blueprints/simple/cover/full/cover_full.json

   The path breakdown:

   • template/groundcombat – It’s a template used in Ground Combat.

   • masters/blueprints – “Masters” indicates base prototypes; “blueprints” indicates environment objects.

   • simple/cover/full/cover_full.json – Folders for category and type, ending in the file cover_full.json which defines the full cover object.

   In the base file, cover_full.json, the relevant component is a StoppingChanceComponent set to 60.0 (meaning 60% cover).

2. Replicate the Folder Structure in Your Mod: Under my_first_mod, create the folders to match that path. Inside my_first_mod, make a template folder, then inside it groundcombat, then masters, then blueprints, then simple, then cover, then full. (Yes, it’s a deep path, but matching the structure is critical so the game knows exactly which asset you’re overriding.)

   Your mod folder should now look like:

   my_first_mod/
   ├─ manifest.json
   └─ template/
     └─ groundcombat/
        └─ masters/
           └─ blueprints/
              └─ simple/
                 └─ cover/
                    └─ full/
                       └─ cover_full.json
   

   All folder names are lowercase as shown.

3. Create the Mod Template File: Open a text editor and create the file cover_full.json in the full folder you just made. This file will override the base full cover definition. We don’t need to copy the entire original file; we can use the “override via inheritance” approach to change only what we want. Use the following JSON content for your mod’s cover_full.json:

   {
    "version": "0.1.0",
    "asset": {
      "Parent": {
        "$content": "xenonauts-:-Xenonauts.GameScreens.GroundCombat-::-masters/blueprints/simple/cover/full/cover_full.json",
        "$type": "Common.Content.AssetReference`1[[Artitas.Template, Assembly-CSharp, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null]]"
      },
      "Name": "default",
      "_components": [
        {
          "$content": 80.0,
          "$type": "Common.Components.StoppingChanceComponent"
        }
      ],
      "$type": "Artitas.Template"
    },
    "$type": "Common.Content.DataStructures.VersionedAsset"
   }

   What this does:

   • The Parent field tells the game that our mod template inherits from the original asset at the given path (the base cover_full.json in the xenonauts pack). This means we start with all the properties of the base full cover.

   • Under _components, we provide a new StoppingChanceComponent with the value 80.0. This overrides the base cover’s stopping chance (60%) with our new value (80%). We only include the component we want to change; other components from the base (if any) remain unchanged by inheritance.

   • The Name is set to "default" to match the base template’s name. This can also be left out or set to something more descriptive.

   • We include the required $type fields for Artitas.Template and VersionedAsset just as in the base file. These should remain as given.

   Save the file. Congratulations – you’ve created your first mod template override!

4. Understanding the Change: With this mod file in place, when the game loads mods, it will see that my_first_mod provides a cover_full.json in the same path as the base game’s, and will load ours after the base game’s data. Because we pointed to the base as Parent and changed the StoppingChanceComponent to 80.0, full cover in Ground Combat will now stop 80% of bullets instead of 60%. All other cover behavior remains as default.

5. Tip – Checking Template Versions: We set "version": "0.1.0" at the top of our JSON. This is the asset file version. The game may use this for upgrade checks. It’s good practice to leave it as is (or match the base file’s version if different). The Xenonauts 2 content manager will handle versioning and can even auto-upgrade older versioned assets if needed. For a simple mod like this, you usually don’t need to worry about it; just use the same version number as the base asset or 0.1.0 if unsure.

At this point, our mod folder has a manifest and one template override. Next, we’ll add more examples to demonstrate modding other template types (weapons and units).

For our second example, let’s modify a weapon’s stats. This will show how to mod item templates (weapons are considered a subtype of items in Xenonauts 2). We’ll increase the damage of the basic ballistic rifle to make it more powerful. This is something you can easily verify in-game by checking the weapon’s stats or shooting an alien.

1. Identify the Weapon Template: In the base game assets (xenonauts content pack), weapons used in Ground Combat are defined under template/groundcombat/item/weapon/. The ballistic rifle’s template file is ballistic_rifle.json in that directory.

   Opening the base ballistic_rifle.json reveals that it inherits from a master template weapon_primary.json (the generic template for primary weapons) and has a component for damage with value 34.0 (likely meaning 34 damage). We want to override that value.

   Side note: Many weapons have a strategy counterpart template (for their strategic properties like cost, ammo, etc.) and a groundcombat template (for combat stats like damage, accuracy, etc.). The ballistic_rifle has a Ground Combat template and also a Strategy template (for inventory and manufacturing). Since we’re only changing damage (a combat property), we’ll override the Ground Combat template. (For a completely new weapon, you’d usually create both, but that’s beyond our simple example.)

2. Create the Folder Path in my_first_mod: Just like with the cover mod, replicate the path for the rifle template in your mod folder. Under MyFirstMod/template/groundcombat/item/weapon/ create the file ballistic_rifle.json.

   Folder structure so far:

   my_first_mod/
   ├─ manifest.json
   └─ template/
     ├─ groundcombat/
     │  ├─ masters/… (cover example files)
     │  └─ item/
     │     └─ weapon/
     │        └─ ballistic_rifle.json
     └─ (others as needed)
   

3. Define the Mod Weapon Template: Open ballistic_rifle.json in a text editor and add the following:

   {
    "version": "0.1.0",
    "asset": {
      "Parent": {
        "$content": "xenonauts-:-Xenonauts.GameScreens.GroundCombat-::-item/weapon/ballistic_rifle.json",
        "$type": "Common.Content.AssetReference`1[[Artitas.Template, Assembly-CSharp, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null]]"
      },
      "Name": "ballistic_rifle",
      "_components": [
        {
          "_min": 0.0,
          "_val": 50.0,
          "_max": 3.402823e+38,
          "$type": "Xenonauts.GroundCombat.Damage"
        }
      ],
      "$type": "Artitas.Template"
    },
    "$type": "Common.Content.DataStructures.VersionedAsset"
   }

   Explanation:

   • We set the Parent to the base ballistic_rifle.json in the xenonauts pack. This means we inherit all of the rifle’s properties (ammo type, firing modes, etc.) by default.

   • We override the Damage component: in the base, it was ~34.0; here we’ve set _val to 50.0 (for example, to significantly boost damage). We include _min and _max as well to mirror the structure of a stat component. Essentially, we’re saying the rifle’s damage stat goes from 34 to 50. We leave other stats like accuracy and TU cost unchanged (they’re inherited).

   • File name is kept the same ("ballistic_rifle") so that we’re modifying the existing item, not creating a new item. If you wanted to make a new weapon (say a “super rifle”), you’d give it a new filename and likely wouldn’t point to the same Parent file (you might point to a generic master or point to it if you want to inherit). But for overriding, matching the path ensures you’re editing the original.

   Save the file. Now our mod will increase the ballistic rifle’s damage in Ground Combat by roughly 47% (34 → 50). This change should be visible in game — for instance, in the soldier equip screen tooltip or Xenopedia entry for the rifle (which pulls data from the templates), you should see the damage stat reflect the new value. And of course, in battle your rifles will hit harder!

   Note: We only altered the Ground Combat template. The Strategy template (which might contain purchase price, etc.) remains untouched, which is fine because we didn’t need to change it. The game’s template mirroring system means there are separate template files for different contexts (strategy and groundcombat) even for the “same” item. Keep this in mind: if you mod something that has multiple aspects (like an item’s combat stats and its strategy properties), you may need to mod both files. In this case, damage is only relevant in ground combat, so one file suffices.

For a final example, let’s modify the stats of a unit – specifically the M.A.R.S. robotic drone that Xenonauts can deploy. This will demonstrate modding an actor template (the kind used for soldiers, vehicles, aliens, etc., often under combatant templates). We’ll increase the MARS vehicle’s health as our tweak.

1. Understand MARS in Game Terms: The MARS is a mechanical unit, essentially a mini-tank. In Xenonauts 2’s data, the MARS’s stats (like hit points) are defined in its combatant template. Because units exist both in Strategy (base management, soldier roster) and Ground Combat, there are templates for each. The MARS’s Strategy template defines its base stats (HP, reflexes, strength, etc. for the strategy layer, which carries into combat) and default equipment, while the Ground Combat side handles things like its armor and weapons.

   We will focus on the Strategy combatant template for MARS’s core stats. The base game has this file under a path such as:
   xenonauts/template/strategy/actor/combatant/mechanical/xenonauts/mars/default.json.
   (Under species “mechanical”, faction “xenonauts”, role "mars", the file default.json contains the stats.)

   In the base data, the MARS might have 100 HP (with min=max=100, meaning it always has 100; otherwise it would randomize between the min and max). We’ll change it so it can have more – say 200 HP.

2. Create the Folder Path: In your mod folder under template/strategy/actor/combatant/mechanical/mars/, create folders for the path leading to default.json. Specifically: mechanical/xenonauts/ then place mars.json there.

   Full path for the mod file:
   my_first_mod/template/strategy/actor/combatant/mechanical/xenonauts/mars.json

3. Edit the MARS Template: Open default.json (in my_first_mod’s strategy actor path) and add:

   {
    "version": "0.1.0",
    "asset": {
      "Parent": {
        "$content": "xenonauts-:-Xenonauts.GameScreens.Strategy-::-masters/actor/combatant/mechanical/xenonauts/mars/default.json",
        "$type": "Common.Content.AssetReference`1[[Artitas.Template, Assembly-CSharp, Version=0.0.0.0, Culture=neutral, PublicKeyToken=null]]"
      },
      "Name": "mars",
      "_components": [
        {
          "_min": 200.0,
          "_val": 200.0,
          "_max": 200.0,
          "$type": "Xenonauts.Common.Stats.HitPoints"
        }
      ],
      "$type": "Artitas.Template"
    },
    "$type": "Common.Content.DataStructures.VersionedAsset"
   }

   Explanation:

   • Parent: We reference the original MARS combatant template from the base game (species mechanical, faction xenonauts). By inheriting, we keep all default behavior and components of the MARS.

   • We override the HitPoints component for the unit to be 200.

   • We left other components like Reflexes, TimeUnits, etc., as they were (inherited from base).

   Save the file. With this mod, when enabled, the MARS unit should have a higher health pool. You could see this in-game by checking the MARS in the Soldier roster (it should display HP 200/200 instead of 100/100, for example), or by noticing it survives more hits in combat.

4. Note: We edited the Strategy template for MARS’s HP as the MARS gets spawned in Strategy and then forwarded to GC. In general, most components for combatants are edited in their Strategy counterpart and the GC counterpart has sane default values to load directly into GC in editor. The Strategy counterpart exists also to provide a "generation" template, allowing a range on stats to enable randomization.

Now we have three examples in one mod: changing cover, a weapon stat, and a unit stat. Feel free to add more tweaks or new files in your mod following the same pattern (manifest entry, correct path, parent reference, your changes).

With all the files in place, it’s time to see your mod in action!

1. Run the Game and Enable the Mod: Launch Xenonauts 2. From the main menu, go to the Mods menu. In the mod list, you should see “My First Xenonauts 2 Mod” (or whatever Name you gave in the manifest) listed.

   • Click the checkbox or toggle to enable your mod. The game might allow enabling/disabling on the fly, but after changing mod status, you’ll need to click an “Apply Changes” . Do so, and the game will load your mod’s content pack.

   • In some more complicated mods the game cannot fully refresh the pack, and a restart might be required. This tends to happen if a Mod does code-based asset loading. However, for simple template based mods, refresh should work fine.

2. Check for Errors: If there’s an issue with your manifest or JSON files, the game may show an error or simply not list your mod. Double-check that:

   • The manifest.json is correctly formatted JSON and placed directly inside the MyFirstMod folder (one level deep, not nested further).

   • Each $type line and other punctuation in your files are correct. A missing comma or quote can break the JSON. The game log (if accessible via a console or log file) will point to JSON parsing errors if any.

3. Start a New Game or Load a Save: To see your changes:

   • For the cover mod: Start a ground combat mission (or load a save in ground combat) where full cover objects are present (e.g., a mission with walls, large rocks, etc.). When your soldiers or aliens shoot and use full cover, you won’t directly see a “80%” label on screen, but the combat log or hit chances behind the scenes reflect the new value.

   • For the rifle damage mod: Go to the soldier Armory (equipment screen). Select a soldier with a ballistic rifle. Hover over the rifle or check its stats – you should see the damage value has increased (e.g., if it shows “Damage: 50” whereas normally it was 34). You can also take the rifle into a mission and notice it killing weaker enemies in fewer hits. This confirms the mod override is active.

   • For the MARS health mod: In the strategy layer, build or cheat-in a MARS unit (if you don’t already have one at game start). Open the Soldier or Vehicle roster where MARS is listed. You should see its health displayed as 200. If you only enable this mod on an existing save, note that already existing MARS units will not retroactively gain health; it’s best to test by producing a new MARS or starting a new campaign for a clean test.

4. Enjoy Your Mod! You have successfully created and activated your first Xenonauts 2 mod. Feel free to experiment by tweaking other values or combining multiple changes. Just keep track of what you change so you can verify it in-game.

5. Troubleshooting: If your mod doesn’t seem to work:

   • Ensure the mod is enabled (the mod manager should show it as active).

   • Check that your file paths and names exactly match the base content you intended to modify. A single folder name that’s off (even by a letter) will mean the game can’t match your file to the original to override it.

   • Look at the game’s log file if available. It can contain messages about mod loading, including any errors in reading your files. Common issues are typos in JSON (missing commas or braces) or incorrect $type strings.

   • Remember that some changes might not apply retroactively to existing save data. For example, if an item’s stat is baked into a save, you might need a new mission or new item to see the effect. Starting a fresh game or mission is a surefire way to test.

• Overrides vs. Extensions: In our examples, we overrode existing assets (cover, rifle, MARS) by using the same path/name and pointing to the base asset as a Parent. This is great for tweaks. If you want to add new content (for instance, a brand new weapon or a new vehicle), you would not use an existing name. Instead, you’d create a new template file with a new name and possibly base it on a generic prototype. For example, to add a new rifle, you might create my_super_rifle.json with Parent pointing to a suitable master (like weapon_primary.json) but give it a unique Name ("my_super_rifle"). You’d also have to integrate it into the game (e.g., add it to a research project or starting equipment) via other templates or parameters. Start with overrides to learn the system, then carefully add new items once comfortable.

• Content Pack Load Order: The base game content pack (xenonauts) is always loaded first, then mods are loaded. If multiple mods are enabled, their load order determines the order in which files are found. If two mods change the same template, only the one with the highest load order will work for that file.

• Dependencies: If your mod requires another mod to be present, you can specify that in your manifest. The manifest supports a Dependencies field where you list required mod UIDs and version ranges. This way, the game can warn the user if they enable your mod without its prerequisite. For example:

  "Dependencies": [
      { "UID": "<OtherMod-UID-here>", "MinimumVersion": "1.0.0" }
  ]

  In our simple “my_first_mod” we have no dependencies, so we left that out.

• Naming Matters: As emphasized, stick to the naming rules (lowercase, no spaces, singular names) for everything: your mod folder, files, and internal asset Names. The engine is case-sensitive and will ignore or not find files that don’t match expected names. For instance, if the base game expects laser_weapon.json and you named your override Laser_Weapon.json, it will not work or cause bugs.

• Template Mirroring: Remember that many game elements have separate templates per game screen. Items are the most common example: an item usually has a groundcombat template (combat stats) and a strategy template (for base/inventory stats). The game “mirrors” these — e.g., a “Sniper Rifle” has one template in groundcombat defining damage and accuracy, and one in strategy defining cost and availability. If you create or modify items, ensure you address the side you need, or both sides if necessary. (Our weapon and cover examples were groundcombat-only; the MARS example was strategy-side primarily.)

• Testing Your Changes: It’s highly recommended to test your mod changes in a controlled scenario. You can create a quick custom mission or use the game’s debug options (if available) to spawn items or units. This helps verify your mod works as intended. For example, to test a new weapon, you might give it to a soldier at game start (possibly via editing a loadout template or using the developer console) rather than waiting to research it. For our simple changes above, starting a new game and checking known stats was sufficient.

• Documentation and Examples: The Xenonauts 2 devs have provided some official modding documentation and example mods (like the cover mod and health mod we mimicked). These are extremely useful references. Don’t hesitate to open the base game’s JSON files or the official examples to learn how something is configured. You’ll find lots of patterns you can follow. Comments in those files (if any) and naming conventions can give clues about what various components do. There’s also likely a community Wiki or Discord where modders share knowledge — a great resource if you get stuck or want to do more advanced modding.

• Be Careful with Updates: If the game updates to a new version, your mod may need updates too, especially if the developers change the structure or expected values in the templates you touched. Because we used the Parent inheritance method, minor base game changes will carry over (since you inherit new base data except the parts you override). But major changes (like renaming components or balancing values) might require you to revisit your mod. Keep an eye on patch notes for anything related to things your mod alters.

• Have Fun and Iterate: Modding is an iterative process. Tweak a value, test it, tweak again. Because template mods load quickly, you can adjust and re-launch the game to see results relatively fast. Just remember to exit the game before editing the files, and use the mod refresh to reload changes.

Good luck, and happy modding, Commander!