In Xenonauts 2, projects represent things that have some kind of requirement or cost (prerequisites), and some effect when those prerequisites are completed.

Primary examples are Research projects (handled by scientists in laboratories) and Engineering projects (handled by engineers in workshops). Each project is defined with various components such as its name, description, prerequisites (requirements to start or unlock the project), and effects (what happens when the project is completed).

Key characteristics of projects:

• Research projects (ProjectType = "Research") are typically one-time investigations (e.g. studying alien technology or performing an autopsy). They usually consume time proportional to scientists’ efforts and are not repeatable by default.

• Engineering projects (ProjectType = "Engineering") generally involve manufacturing items, vehicles, base facilities, or other physical outcomes. They often require resources (materials) and time (engineer-hours).

Both types share a similar data format and are defined as templates with components. The game’s data is organized so that many projects inherit from base templates that set common defaults (for example, general research vs. engineering properties, or standardized project durations).

A project is defined in a JSON file under the game’s .../strategy/projects/... directories (with subfolders for each category, such as research/ or engineering/). The important fields in a project definition include:

• Parent template: Most project JSON files use a "Parent" reference to inherit base properties. For example, a new research project might use the base research template or a pre-defined “duration” template that sets its research point requirements. Likewise, an engineering project might inherit from the base engineering template or a variant. This inheritance avoids repeating common fields. For instance, a research project file might start like:

  "Parent": {
    "$content": "xenonauts-:-Xenonauts.GameScreens.Strategy-::-masters/projects/research/research_duration4.json",
    "$type": "Common.Content.AssetReference`1[[Artitas.Template,...]]"
  },
  "Name": "my_new_research",
  ...

  In this case, it inherits from research_duration4.json which is a template setting a certain research ProgressPoints (e.g. a medium-length research). The base research template defines general properties like project type, default progress points, and meta flags. Engineering projects similarly often use engineering_durationX.json templates or the base engineering.json.

• Name and Description: The "Name" field (inside the asset) is the internal identifier for the project. The display name shown to players is provided by a Common.Components.NameComponent in _components, usually with a string value. Similarly, the description text is given by a Common.Components.DescriptionComponent. For example, a project might include:

  {"$content": "Laser Weaponry", "$type": "Common.Components.NameComponent"},
  {"$content": "Development of an array of handheld Laser weapons for our soldiers to use...", "$type": "Common.Components.DescriptionComponent"}

  Note: Localization is tackled through the LocalizableGUIDComponent and topic of another article. For a simple mod you can also use raw text directly in the Name/Description components.

• PrerequisitesComponent: This is a critical component listing conditions required for the project. Prerequisites can serve two roles in the data:

  • Unlock prerequisites (Variant "Unlocks"): Conditions that must be met for the project to become available (e.g. prior research completed, items obtained). These do not consume resources; they simply gate the availability.

  • Cost prerequisites (Variant "Cost"): Resources or time requirements that will be consumed or expended when the project is started or as it progresses (e.g. materials to be consumed, work-hours required).

  Prerequisites are quite flexible and can represent logic such as:

• Previous projects: requiring another research or project to be finished. This uses ProjectPrerequisite with a reference to the other project and a Status (usually "Finished"). Example: a laser weapon research might require the Alenium Generator research to be finished first. In JSON it appears as:

  {
    "Project": { "$content": "xenonauts-:-...-::-projects/research/building_alenium_generator.json" },
    "Status": "Finished",
    "Variant": "Unlocks",
    "$type": "Xenonauts.Strategy.Data.Prerequisites.ProjectPrerequisite"
  }

  You can list multiple such prerequisites. For instance, a plot research “UOO-1 Sabotage” requires two prior projects (e.g. Phase 4 and Cleaner investigation projects) both to be finished before it unlocks.

• Item prerequisites: requiring the player to possess certain items in stores (often used for research that needs an artifact or corpse). This uses ItemsPrerequisite or AggregateItemsPrerequisite. For example, an autopsy research might require at least one corpse of that alien type in storage (and optionally also completion of a general Xenobiology research). In the Alien Symbiote autopsy data, we see an AggregateItemsPrerequisite looking for a corpse item in the Xenonauts base stores (with Consumes:false because the corpse isn't consumed to unlock, just needs to exist). The relevant snippet looks like:

  {
    "Selector": { "Group": "Xenonauts.Strategy.Components.GeoBaseGroup", "$type": "Xenonauts.Strategy.Data.EntitySelectors.GroupEntitySelector" },
    "Quantity": 0,
    "Item": { "$content": "xenonauts-:-...-::-item/corpse/corpse_biter.json" },
    "Consumes": false,
    "Variant": "Unlocks",
    "$type": "Xenonauts.Strategy.Data.Prerequisites.AggregateItemsPrerequisite"
  }

  Here Quantity: 0 with an Unlocks variant essentially means "at least one of this item is present". (The game interprets this as needing >0 since it’s an unlock prerequisite check.) This is wrapped in some delegate prerequisites logic to apply to any player base, etc., but the core idea is checking for the item. Additionally, the Symbiote autopsy required the Abstract Xenobiology project to be finished – demonstrating multiple prerequisites.

• Resource costs: materials that will be consumed when starting or completing an engineering project. This uses ItemsPrerequisite with Consumes:true and a specified quantity, typically marked as a Cost variant. For example, manufacturing a vehicle might require 20 units of Alenium and 20 units of Alien Alloys as cost. In the ARES Combat Platform engineering project, the prerequisites include:

  {
    "Quantity": 20,
    "Item": { "$content": "xenonauts-:-...-::-item/alenium.json" },
    "Consumes": true,
    "SlotType": { "$content": "Stores", "$type": "Xenonauts.Common.Components.Item.MainBaseSlots" },
    "Variant": "Cost",
    "$type": "Xenonauts.Strategy.Data.Prerequisites.ItemsPrerequisite"
  },
  {
    "Quantity": 20,
    "Item": { "$content": "xenonauts-:-...-::-item/alloys.json" },
    "Consumes": true,
    "SlotType": { "$content": "Stores", "$type": "Xenonauts.Common.Components.Item.MainBaseSlots" },
    "Variant": "Cost",
    "$type": "Xenonauts.Strategy.Data.Prerequisites.ItemsPrerequisite"
  }

  Both of those are contained under the project’s PrerequisitesComponent, meaning you must have those resources (and they will be deducted when the project starts).

• Time / work capacity: the amount of work required. Research projects implicitly use ProgressPoints and scientist allocation to track time (the base research template defines a progress bar, e.g. 160 points, and scientists contribute to filling it). Engineering projects similarly use ProgressPoints, but they also often include an explicit OperationPointsPrerequisite as a cost. This represents the total work units required. For example, the ARES vehicle manufacture above has:

  {
    "value": 250000.0,
    "Variant": "Cost",
    "$type": "Xenonauts.Strategy.Data.Prerequisites.OperationPointsPrerequisite"
  }

  within its prerequisites. This huge number is the total engineering "operation points" needed. Each engineer at your base contributes a certain rate of operation points per hour (the exact rate may be defined elsewhere, possibly influenced by base facilities or difficulty). The project’s ProgressPoints (inherited via engineering_duration4.json in this case) might define how the progress is scaled – for instance, engineering_duration4 sets a base progress max of 600 points. The relationship is that the OperationPointsPrerequisite defines the actual amount of work required, while ProgressPoints and difficulty settings determine how quickly that work is completed. (The game’s difficulty settings can modify project speeds via a DifficultyModifiableComponent on the base templates, so values like 250000 might be adjusted by difficulty.)

• Logical combinations: Prerequisites can be grouped or combined logically using LogicPrerequisite or ADelegatePrerequisite with operators like "All" (AND) or "Any" (OR). For example, multiple cost items might be grouped under one ADelegate with operator All (meaning all those items are required together). Or you could use an "Any" operator to allow alternate prerequisite paths (e.g. require EITHER item X or item Y to unlock a project). The data structure allows nesting these for complex conditions. Most mod projects can stick to simple lists of prerequisites, but know that this system is powerful if needed.

• ProjectMetaComponent: This component defines special flags about the project’s behavior and presentation. The value is a comma-separated string of meta options. Common flags include:

  • "Repeatable" – the project can be undertaken multiple times (e.g. manufacturing ammo or equipment repeatedly).

  • "Stackable" – multiple instances can be queued (e.g. queue 5 units of the same item to build one after another, instead of one at a time).

  • "Cancellable" – the project can be canceled mid-progress by the player.

  • "CompleteNotification" – triggers a notification when finished.

  • "AvailableNotification" – triggers a notification when it becomes available (unlocked).

  • "ForceShowResearchAvailableNotification" – (research-specific) ensures a pop-up or alert for new research availability.

  • "Automatic" – the project does not require manual start; it will execute automatically (used for things like instant or background projects).

  • "QueueMaxQuantity" – allows specifying a quantity in one go (used for projects like disassembly where you might choose how many items to dismantle in a single project run).

  The base templates set some of these defaults. For example, the base Research template is marked Cancellable and will notify when available, ensuring the game alerts you to new research opportunities. Engineering base is marked Repeatable, Stackable, Cancellable, etc., meaning manufacturing projects by default can be repeated and queued. If you create a one-time engineering project (like a singular facility upgrade), you might override these flags (e.g. remove Repeatable/Stackable). In our grenade upgrade example below, the project meta excludes Repeatable because it’s meant to be done once.

• ProgressPoints: A component indicating the progress bar range for the project (min, current, max). This typically is defined in the parent template (e.g. a “duration3” template might set a moderate max value, whereas “duration7” sets a very large one).

• SortOrder and Categories: Projects can be assigned a sort order (numeric) and belong to a category for UI grouping. The SortOrderComponent helps control where in the list a project appears. The SortCategoriesReferenceComponent can link to a category (for instance, engineering projects might be grouped under "Vehicles", "Aircraft", "Equipment", etc. in the workshop interface). In the ARES project, you can see it referencing the vehicles category sort definition, which ensures all vehicle projects are grouped together in the UI. Typically, if you’re adding a new project of an existing type (say a new vehicle or weapon), reuse the relevant category reference from a similar project. If it’s a new category, you would define a new sort category asset (beyond the scope of this guide).

• Project State Machine & Effects: Each project has a ProjectStateMachineComponent which controls the states (like Setup, InProgress, Finished) and can attach effects to certain state transitions. Most commonly, we care about EntryEffects on the "Finished" state – i.e., what happens when the project completes. This is how the game grants rewards or triggers outcomes from a project. Some projects might also use effects on start or triggers during progress, but that’s less common.

  Effects are defined as objects under EntryEffects or ExitEffects, and there are different types:

  • Generate items or actors: Engineering projects often produce an item or a unit upon completion. For example, building the ARES Combat Platform uses a GenerateAndRecruitActorEffect when finished, which creates the ARES unit and adds it to the base (like recruiting a soldier). Manufacturing a piece of equipment might instead use an effect to add an item to your stores. (There are effects like AddItemEffect or DeltaItemEffect for manipulating inventory.)

  • Upgrade existing items: Some projects upgrade or transform existing equipment. The Plasma Grenades project in the base game is a good example: it's an engineering project that, when completed, upgrades all your old grenades to new, more powerful versions. Its Finished EntryEffects consist of multiple UpgradeItemsEffect entries that convert Frag Grenades and Alenium Grenades into Fusion (Plasma) Grenades, and also upgrade demolition charges to higher tiers. This means once the project is done, any instances of the old items in your stores are replaced by the new items automatically.

  • Unlock availability of new gear: Often, completing a research will unlock new items for production or purchase rather than granting them immediately. This can be handled by marking those items as available in the stores or manufacturing list. For example, completing Laser Weaponry research in the base game triggers effects that add laser weapon ammo to the stores with infinite quantity (meaning they become available to produce or are automatically replenished). In the Laser Weaponry project data, we see multiple DeltaItemEffect or AddItemToGeoBaseRequisitionEffect entries with Quantity: Infinity for various laser ammo types. This indicates those items are now effectively unlocked for use (infinite ammo implies you don’t need to manufacture ammo or it can be requisitioned freely). Similarly, a new aircraft or vehicle technology might unlock the ability to build that vehicle (which would actually appear as a new engineering project for construction, gated by the research’s completion).

  • Trigger missions or events: Some research projects can advance the storyline by spawning missions or triggering events. For example, the “UOO-1 Sabotage” plot research, upon completion, uses a CreateMissionEffect to spawn a special mission on the geoscape. This is done via an EntryEffect that references a Mission Definition asset, causing that mission (e.g., capturing resources or attacking a certain enemy facility) to appear when research is finished. Modders can similarly tie research to events or missions by using appropriate effects.

  • Apply strategic bonuses: Although not as visible in the JSON snippets we have, projects could in theory apply modifiers to gameplay (like granting a bonus or changing a game state). The autopsy template, for instance, had an effect that appeared to grant "TrainingPointProduction" bonus of 0 – likely a placeholder or deprecated effect. But one could imagine projects that improve soldier stats, global funding, etc., via effects (using DeltaRangeEffect, CampaignTagEffect, etc., if such exist in the game’s data). Check the game’s available effect types in code if you want to use an unusual effect.

In summary, a project JSON pulls together: a name/description, some prerequisites (unlock conditions and costs), optional meta flags for behavior, and effects on completion. Now let's see how you would create your own research or engineering project in a mod, using these components.

To add a new research project in your mod:

1. File placement: In your mod’s folder structure, mirror the path for research projects. For example, create a file at MyMod/strategy/projects/research/my_project_name.json. The exact starting directory may depend on how the mod loader expects it (some setups might require an assets/xenonauts/template/strategy/... path). Refer to the modding documentation for setting up the mod folder, but essentially you want to place your project JSON such that it corresponds to the game’s template/strategy/projects/research/ directory.

2. Inherit a base template: Decide how long/complex the research should be. If it’s similar in scope to an existing one, you can use the same parent. Common choices:

   • Use the generic research template: masters/projects/research/research.json – which by default has a moderate research length (e.g. max 160 points). You can override the ProgressPoints in your file if needed, or use a preset.

   • Use a duration preset: The game defines several research_durationX.json templates (0 through 9) which seem to correspond to different research lengths (possibly trivial to extremely long). For instance, research_duration0.json might be for very short projects (perhaps used by autopsies or instant projects), whereas higher numbers like research_duration6.json or 7.json are for major projects. You can inspect these in the assets: they simply set a different ProgressPoints max value (e.g. duration4 = 5000, duration7 = 50000, etc.). By inheriting from one of these, you automatically set the research effort required.

   • You could also create your own custom parent template if you want a specific new category, but that’s usually unnecessary.

   For example, if your project is a significant tech, you might do:

"Parent": { "$content": "xenonauts-:-...-::-masters/projects/research/research_duration6.json" },
"Name": "new_advanced_tech",
...

This indicates it’s a research with a fairly large effort required.

3. Define Name and Description: Add a NameComponent for the project’s title as it will appear in-game, and a DescriptionComponent explaining the project’s narrative or effects. Ensure the NameComponent text clearly identifies it (e.g. "Project: Advanced Lasers"). You can mark them for localization if needed (using a LocalizableGUIDComponent similar to base game data, but for a personal mod it might be fine to just include the text directly).

4. Set prerequisites: In the _components list, include a PrerequisitesComponent with an array of prerequisite entries. Consider:

   • Previous research: If this tech comes after some prerequisite tech(s), include ProjectPrerequisites for each of those. By default, multiple prerequisites in the array are treated as AND (all must be true) unless you specifically structure an OR logic.

   • Item requirements: If the research needs an artifact, alien corpse, UFO data, etc., include an ItemsPrerequisite. Usually for research, you don’t consume the item (set "Consumes": false) because you only need a sample to study. Use AggregateItemsPrerequisite if the item could be in any base or you have multiple bases – this sums across all storage (the base game uses this to ensure e.g. an alien corpse in any base storage counts).

   • Other conditions: Perhaps the project only becomes available in a certain phase of the game or after a story event. You might use a ProjectPrerequisite linking to a hidden “phase” project. (The game uses hidden phase tracking projects in masters/projects/phase.json to gate content.) For example, many story researches require that the campaign is in a certain phase (Phase 4 in the UOO example).

   Structure your prerequisites in JSON. For instance:

"$type": "Xenonauts.Strategy.Components.PrerequisitesComponent",
"$content": [
    {
      "Project": { "$content": "xenonauts-:-...-::-projects/research/precursor_tech.json" },
      "Status": "Finished",
      "Variant": "Unlocks",
      "$type": "Xenonauts.Strategy.Data.Prerequisites.ProjectPrerequisite"
    },
    {
      "Selector": { "Group": "Xenonauts.Strategy.Components.GeoBaseGroup", "$type": "Xenonauts.Strategy.Data.EntitySelectors.GroupEntitySelector" },
      "Quantity": 0,
      "Item": { "$content": "xenonauts-:-...-::-item/artifact/my_alien_artifact.json" },
      "Consumes": false,
      "Variant": "Unlocks",
      "$type": "Xenonauts.Strategy.Data.Prerequisites.AggregateItemsPrerequisite"
    }
]

This would mean requires completion of "Precursor Tech" research and having at least one "Alien Artifact" item in storage to unlock.

If you want an OR (either condition A or B unlocks the project), you would wrap those in a LogicPrerequisite with "Operator": "Any". Refer to advanced examples or the game data for syntax, but something like:

{
  "Operator": "Any",
  "Children": [ <Prereq A>, <Prereq B> ],
  "Variant": "Unlocks",
  "$type": "Xenonauts.Strategy.Data.Prerequisites.LogicPrerequisite"
}

could be used.

5. Adjust Project Meta (if needed): By default, research is non-repeatable and you wouldn’t repeat a research anyway. The base research template already sets appropriate flags (Cancellable, etc.). You usually don't need to override the ProjectMetaComponent for a normal tech research. Only if you had a special case (like an automatic research that should complete instantly or hidden background research) would you change these. For example, the game’s autopsy_autocomplete template sets Automatic and zero progress for an instant completion behavior on autopsies on certain settings.

6. Define effects on completion: Think about what completing the research does:

   • Does it unlock new items or projects? In many cases, you don’t need to explicitly script “unlock X” because the presence of this finished research can serve as a prerequisite for other things. For instance, if your new research should enable a new engineering project (say, building a new weapon), you would create that engineering project separately and put a ProjectPrerequisite pointing to this research. The game UI will automatically show the engineering project as available once the research is done. This is the common pattern: research unlocks manufacturing or other research via prerequisites, not by a direct effect.

   • However, if the research should immediately give an item or some bonus, you can do so with effects. Maybe you want to reward the player with a prototype item upon research completion. You could use a CreateItemEffect or DeltaItemEffect. For example, one could grant a free item:

     "EntryEffects": {
      "Finished": [
        {
          "selector": { "Player": "xenonauts", "$type": "Xenonauts.Strategy.Data.EntitySelectors.PlayerSelector" },
          "effects": [
            {
              "Quantity": 1,
              "Item": { "$content": "xenonauts-:-...-::-item/weapon/my_new_gun.json" },
              "SlotType": { "$content": "Stores", "$type": "Xenonauts.Common.Components.Item.MainBaseSlots" },
              "$type": "Xenonauts.Strategy.Data.AddItemEffect"
            }
          ],
          "$type": "Xenonauts.Strategy.Data.ADelegateEffect"
        }
      ]
     }

     This would add one of the new guns to the player’s stores when the research finishes.

   • If the research triggers a story event or mission, include a CreateMissionEffect as seen in the example earlier. You’d reference a MissionDefinition asset and perhaps specify any override parameters.

   • If the research unlocks unlimited availability of something (like making an item purchasable or ammo infinite), you could use AddItemToGeoBaseRequisitionEffect with Quantity Infinity as the base game does for ammo. This effectively marks that item as available in stores (and infinite suggests no limit in purchasing or it’s automatically stocked).

   • Wrap these effects in the structure of the ProjectStateMachine. Usually:

     {
      "$type": "Xenonauts.Strategy.Components.ProjectStateMachineComponent",
      "TriggerEffects": {},
      "EntryEffects": { "Finished": [ ... effects here ... ] },
      "ExitEffects": {},
      "State": "Setup"
     }

     (Most projects start in state "Setup" and then go to "Finished" when done, triggering EntryEffects at that point.)

   If you don’t need any explicit effect (the research simply enables other content via prerequisites), you can omit ProjectStateMachineComponent entirely or leave it as inherited (the base might have a default with none or trivial effects).

7. Finalize and integrate: Save your JSON. If your mod requires a manifest or registration of new assets, ensure your new project file is included. In many cases, Xenonauts 2 will automatically merge the mod content if placed in the correct folder structure. Once in game, your project should appear in the Research screen when its unlock prerequisites are satisfied.

Example – Adding a New Research: Suppose we want to add "Advanced Alien Alloys" research that becomes available after researching basic "Alien Alloys" and recovering a Heavy Drone Wreckage. We want it to grant a new armor item prototype on completion.

• We’d create advanced_alien_alloys.json in projects/research/.

• Parent it to an appropriate duration template (maybe a mid-long research, e.g. research_duration5.json).

• Set NameComponent "Advanced Alien Alloys" and a DescriptionComponent explaining the project.

• Prerequisites: ProjectPrerequisite for alien_alloys.json (the basic alloys research), and an ItemsPrerequisite for one wreckage_heavy_drone.json in stores (Consumes false, since we just need to study the wreckage, not destroy it).

• Effects: perhaps use an AddItemEffect to give 1 unit of a new armor (item definition we’ve added in the mod) as a prototype reward, and/or an AddItemToRequisitionEffect to unlock that armor for manufacture.

• Keep meta as default (not repeatable, etc., since it’s a one-time research).

This would integrate into the tech tree smoothly: after Alien Alloys research and a mission where you recover a heavy drone, the new project appears. When finished, it grants the new armor and perhaps allows manufacturing more via an engineering project (which we’d also define).

Adding an engineering (workshop) project follows a similar process with some differences:

1. File placement: Put the JSON under .../strategy/projects/engineering/ in your mod’s folder. Name it something descriptive of the project outcome (e.g. build_laser_tank.json or upgrade_rifles_tier2.json).

2. Parent template: Choose a base for engineering. The base engineering.json template sets common behavior (repeatable, etc.). There are also engineering_durationX.json templates for scaling the ProgressPoints (i.e. baseline project length). Pick a duration that matches how long you want it to take. For manufacturing physical items, the “duration” might correspond to build time categories (e.g. a simple grenade might be duration1 or 2, a complex vehicle might be duration4+). If unsure, base engineering_duration3.json or 4.json are moderate. For one-off projects (like upgrades that shouldn’t be repeated), you might still use these but will adjust meta flags.

   Example:

   "Parent": { "$content": "xenonauts-:-...-::-masters/projects/engineering/engineering_duration2.json" },
   "Name": "build_new_weapon",
   ...

   This sets a base ProgressPoints (maybe something like 200 or 300 points) for the project, which combined with engineers will determine time.

3. Name/Description: Provide a NameComponent for the project (e.g. "Manufacture: Laser Cannon") and a DescriptionComponent that tells the player what this project does (e.g. "Build a Laser Cannon for our interceptors."). Use LocalizableGUIDComponent if needed, similar to research.

4. Prerequisites: Engineering projects often have more prerequisites:

   • Unlock prerequisite (research): If this project is to produce something new, you almost always gate it behind a research project. Include a ProjectPrerequisite with Variant "Unlocks" pointing to the research that enables this manufacture. For example, the project to build the ARES vehicle requires the ARES research be finished. Without this, the manufacturing project would show up prematurely. In your mod, if you add a new item, tie its engineering project to the appropriate research.

   • Facility or contextual prerequisites: Generally, Xenonauts 2 does not require specific buildings for specific projects (aside from having a workshop facility to do engineering at all). If a special project required a particular building, it might be done via a prerequisite on an Item that represents the facility or a Campaign Tag. The base data doesn’t show explicit FacilityPrerequisite types, so this might not be directly supported or needed. (If you needed it, one hack is to require an item that is only present if a building exists, but that’s beyond normal usage.)

   • Cost prerequisites: This is where engineering differs most from research:

     • Materials: List any item requirements with ItemsPrerequisite (Consumes true) to represent materials that will be consumed to build the item. Common materials are Alien Alloys, Alenium, perhaps elerium or other exotic components in your mod. Set the quantity needed. E.g., if building a new tank needs 50 alloys and 10 alenium, add two entries for those.

     • Work hours: Include an OperationPointsPrerequisite with a value representing the total engineering effort required. You can estimate this by looking at similar projects in game. For instance, building a basic vehicle might be 250000, a complex aircraft might be much higher. If your project is small (like assembling a weapon), it could be on the order of a few thousand or tens of thousands. This number combined with the ProgressPoints from the parent template and the number of engineers will determine how many days the project takes. (If unsure, use an existing project as a template; for example, if you add a new grenade type, see plasma grenade project cost which is 300000 operation points and 15 alenium.)

     • Other costs: Possibly money or other resources if the game had them – Xenonauts 2’s data doesn’t explicitly list a money cost in the project JSON (the economy might be simplified or handled elsewhere). If needed, you might simulate a money cost by requiring an “item” that represents money or by scripting an effect that deducts funds on completion. But typically Xenonauts 2 did not charge money for projects in the data we see (it might be handled by a separate economy system).

   Just like research, wrap these in the PrerequisitesComponent array. Ensure you mark resource ones as "Cost" variant. The engine will likely deduct those items when you start the project. If the player lacks them, the project either won’t start or will pause until they are available (depending on how Xenonauts 2 handles deficits – likely it prevents starting until you have them).

5. Project Meta flags: By default inherited from engineering base, your project will be Repeatable and Stackable. If your project produces a consumable or equipment, you probably want it repeatable (so the player can manufacture it as many times as needed). This is correct for most manufacturing projects (weapons, ammo, armor, vehicles, etc.). The UI will then allow choosing quantity or re-queuing.

   However, if your engineering project is a one-time upgrade or storyline event (e.g. "Install new Radar System" that should only be done once), you should override the meta to remove Repeatable. For instance, you could include a ProjectMetaComponent like:

   {"$content": "Cancellable,CompleteNotification,AvailableNotification", "$type": "Xenonauts.Strategy.Components.ProjectMetaComponent"}

   omitting Repeatable/Stackable. The Fusion Grenades upgrade project in the base game does exactly this – it is marked only cancellable with notifications, meaning you do it once. Conversely, generic manufacturing uses the default meta that includes repeatability.

   If your project allows specifying a batch size (like dismantling 5 alien alloys at once), consider using QueueMaxQuantity meta. The base disassembly template uses this to let players pick how many units to process. For example, if you made a project to dismantle alien alloys into base metals, you could allow a quantity input by including that flag.

6. Completion effects: When an engineering project finishes, you typically grant the item or outcome:

   • For building standard items (weapons, armor, equipment): The game usually directly adds those items to the base stores as part of the project completion. This might actually be done automatically by the game if the project is marked as producing a specific item. However, to be explicit or if doing something custom, you can use an effect:

     • AddItemEffect or DeltaItemEffect to add X quantity of the produced item to the base. If one build project produces one item, you could just rely on the game’s inherent knowledge of what the project is for (if linked somehow). But since in the data we often don’t see an explicit link "this project produces X", the safer approach is to include an EntryEffect that gives the item.

     • There might be a pattern where the project’s Name or some component implicitly references the item it produces (in Xenonauts 1, manufacturing projects tied directly to items). In Xenonauts 2’s JSON, the GenerateAndRecruitActorEffect clearly shows which unit to create for the ARES project. For simpler items, I suspect an AddItemEffect would be used. For example, if we looked at a weapon manufacturing project (not in the snippets above, but likely exists in the data), it would have an effect to add that weapon.

   • For producing vehicles or aircraft (which are entities rather than inventory items): use GenerateAndRecruitActorEffect as seen with the ARES vehicle. You need to reference the template of the thing to generate (in this case the ARES unit template in the actor/combatant/mechanical/... directory). This effect places the new vehicle into the base’s garage/hangar on completion. In your mod, if you create a new vehicle, you’d have a similar effect pointing to your vehicle’s actor template.

   • For base structures or other upgrades that aren’t items, you might use an effect to enable something. It could be adding a CampaignTag (to signal “X built”) or directly modifying a base property. The data doesn’t show an explicit example, but one could imagine an effect like unlocking a base facility. However, base facilities in Xenonauts 2 might actually be built via a different system (base building interface rather than projects).

   • For upgrade-type projects (like our grenade upgrade example): use UpgradeItemsEffect as shown in the Fusion Grenades project. You list each old item (the "From") and what it becomes (the "To"). This automatically replaces all instances. If your mod has a project like “Upgrade all Laser Weapons to Improved Laser Weapons”, you would enumerate all the basic laser weapons ammo/equipment in From and their improved counterparts in To, so that when done, soldiers’ inventories and stores reflect the new gear.

   • Multiple effects can be combined. They are executed in order listed. If some effects target specific bases or require selectors, use the appropriate selectors (e.g. PlayerSelector for the player global context, MyGeoBaseSelector for the base where project was built if needed, etc.). The ARES effect uses two selectors (Arg0 as Player, Arg1 as the Base) because it needs to generate the vehicle at the base that built it. For standard items, you might just add to Player’s storage across all bases or specifically to the base that initiated the project – depending on design. (By default, manufactured items likely appear in the base that built them; to replicate that, include a base selector.)

   Structure the effects in the JSON under the ProjectStateMachineComponent as described for research. For example, a simple manufacturing project to produce a new rifle might have:

"EntryEffects": {
  "Finished": [
    {
      "Arg0Selector": { "Player": "xenonauts", "$type": "Xenonauts.Strategy.Data.EntitySelectors.PlayerSelector" },
      "Arg1Selector": { "Target": null, "$type": "Xenonauts.Strategy.Data.EntitySelectors.MyGeoBaseSelector" },
      "Effect": {
        "Quantity": 1.0,
        "Item": { "$content": "xenonauts-:-...-::-item/weapon/my_new_rifle.json" },
        "IgnoreCost": true,
        "Delayed": false,
        "Randomize": false,
        "$type": "Xenonauts.Strategy.Data.EntityEffects.DeltaItemEffect"
      },
      "$type": "Strategy.Data.EntityEffects.BinaryArgsDelegateEffect"
    }
  ]
}

7. Test and iterate: Once the data is in place, test in-game. Ensure that:

   • The project appears in the Engineering screen when it should (after its unlock prereqs are met).

   • The materials are properly deducted on project start.

   • The time to completion feels right with available engineers (adjust OperationPoints or ProgressPoints if needed).

   • On completion, the desired outcome happens (item appears, etc.). If not, you may need to adjust the effect or ensure the item template is correctly defined.

Example – Adding a Manufacture Project: Let’s continue the earlier example: we researched "Advanced Alien Alloys", now we want an engineering project to manufacture a new advanced armor using those alloys.

• We have a new item defined for the armor (say armor_exosuit.json in items).

• Create build_exosuit.json in projects/engineering/.

• Parent to engineering_duration3.json (assuming making the armor is a moderate project).

• NameComponent "Construct Exosuit Armor" and DescriptionComponent accordingly.

• Prerequisites: ProjectPrerequisite for advanced_alien_alloys.json (the research we added). Possibly also require some standard tech like basic personal armor is done, if appropriate.

• Cost prerequisites: e.g. 10 Alien Alloys (consumed), 5 units of a new resource (if any), etc., and maybe 100000 operation points (just an example) for the work required.

• Meta: Repeatable (you might want to build multiple exosuits, so keep repeatable/stackable from base).

• Effects: On Finished, add one armor_exosuit item to the base’s stores. Since this is manufacturing, the game might actually allow you to choose quantity and do multiple in one go (depending on stackable and if you queue multiple). If you allow queueing, each completion yields one item. You could also integrate a quantity selection using QueueMaxQuantity if you want the player to input how many to make in one batch (the base game usually just makes you queue them one by one or as separate entries, so it's optional).

• After implementation, once "Advanced Alien Alloys" research is done, the player should see "Construct Exosuit Armor" available in Engineering. They assign engineers, spend alloys, and get the armor when done.

Let's look at a few real Xenonauts 2 project examples and how they utilize these data fields, to solidify our understanding:

• Alien Autopsy Project (Research) – e.g. "Autopsy: Symbiote" which corresponds to an alien called Psyon Symbiote:

  • Parent Template: Inherits from autopsy.json, which is a special research template for autopsies. That template itself inherits from a very short research (duration0) and sets a high progress requirement (8000 points), indicating a substantial research effort but presumably autopsies are balanced by other mechanics.

  • Prerequisites: Requires at least one Symbiote corpse in storage and the Abstract Xenobiology research finished to unlock. This ensures you can't start an autopsy until you have a specimen and have the general knowledge to perform autopsies.

  • Meta: Autopsies are typically one-off. The base autopsy template might allow cancellation, but not repeat (since you only do it once per alien type).

  • Effects: In current data, autopsies have a placeholder effect (granting 0 training points) – possibly a removed feature. More importantly, autopsies often unlock lore and sometimes small buffs (in Xenonauts 1, autopsies gave minor combat bonuses). Those could be implemented via effects (e.g. increasing damage to that alien type). A modder could add such an effect with a DeltaRangeEffect affecting soldier stats against that alien, for instance. The game might also simply rely on a completed autopsy to unlock related projects (like interrogation or advanced biology research).

• “UOO-1 Sabotage” Plot Research – a late-game story research:

  • Prerequisites: Requires Phase 4 to be reached and another plot research ("cleaner_6") finished. These are both ProjectPrerequisites gating it to the right campaign stage.

  • Effects: On completion, it triggers a special mission (likely the final mission or a critical plot mission) via CreateMissionEffect. There are no item or material costs – it’s purely a story trigger research.

  • Meta: It’s non-repeatable (like all research) and probably flagged to always show a notification when available (since it's critical).

• ARES Combat Platform (Engineering) – manufacturing a vehicle:

  • Parent: Inherits from engineering_duration4.json for a fairly lengthy build time (base progress 600).

  • Prerequisites: Requires the ARES research to be finished (Unlocks) and has Cost prerequisites: 250,000 operation points of work, 20 Alenium, 20 Alloys (all consumed). No money is listed, implying the limiting factors are time and alien materials.

  • Meta: Inherits Repeatable/Stackable, so you can build multiple ARES units (as many as you can afford).

  • Effects: On finish, uses GenerateAndRecruitActorEffect to spawn one ARES unit at the base that built it. After completion, if you want another, you start the project again (hence repeatable).

• Fusion Grenades Upgrade (Engineering) – upgrading existing items:

  • Parent: Uses engineering_duration3.json (medium project length).

  • Prerequisites: Requires Plasma Explosives research finished (to unlock), costs 300,000 operation points and 15 Alenium. No repeat, since you wouldn’t repeat the upgrade.

  • Meta: Cancellable and notifications, but not repeatable (this project is meant to be done once; it upgrades all your grenades).

  • Effects: On finish, executes several UpgradeItemsEffect entries – converting all Frag Grenades and Alenium Grenades in stores to the new Fusion Grenades, and upgrading all Demolition Charges to higher-tier charges. It also adds infinite availability of the new grenades’ ammo for the grenade launcher (via an AddItemToGeoBaseRequisitionEffect with infinite quantity, not fully shown in snippet above but present in the data). The result is that after the project, all your ground forces automatically have the better grenades, and any future grenades you acquire will be the better type.

• Laser Weaponry Research (Research) – unlocks a suite of weapons:

  • Parent: research_duration4.json (a mid-level tech).

  • Prerequisites: Requires Alenium Generator research done (meaning you needed to understand a power source before laser weapons).

  • Effects: Instead of directly granting items, it unlocks the ability to produce various laser weapons and provides infinite ammo. In data, this is represented by multiple DeltaItemEffect entries setting ammo items to infinite in stores, and AddItemToGeoBaseRequisitionEffect entries for those items. Essentially, once you complete Laser Weaponry, all laser weapon ammo is available (so your weapons can be used; presumably the weapons themselves still need manufacturing projects which are now unlocked because they have this research as a prerequisite).

  • Meta: Standard research meta (notifications, not repeatable).