AI War 2:Xml Modding Modular Ships

Modular ships have come to AI War 2 as of version 3.900! This guide is meant for folks who already understand how to design a non-modular unit, and it explains all the differences and new things that are specific to modular ships.

Overview

• Modules are defined as an inseparable part of the ships that use them.
  • If you want to share a module between multiple ships, you'll either need to use copy_from (xml inheritance) or literally copy the xml.
• Modules are all systems, but not all systems are modules.
• There is a general limit of 254 systems, which also means 254 modules.
  • That said, if you're adding more than 50 or so, the player is probably going to have a bad time.
• You can include non-module systems on a modular ship, and you can also default modules on at certain mark levels.
• The ship will have a certain starting budget for modules (that can be zero), and a certain number of added module points per mark level (can also be zero, but both can't be zero for the ship to still be modular).
  • Players allocate these module points on modules of various costs, and that's how they customize their ship.
    • This is done from a new Module button in the Fleet Management window.
• Modules are ship-line-wide, not ship-specific. So for instance if you have a bunch of spire cruisers that you want to customize, you have to do them in groups from each city that is bolstering that fleet.

Defining A Unit As Modular, And Giving It A Budget

Before you can do anything with the systems themselves, and before a ship will show the Module button in the fleet management window, you need to mark a ship as modular. To do that, you give it a module budget, either right off, or over time as mark levels increase.

It is possible to design ships that don't become modular until some mark level by giving a zero or negative starting module budget, and then giving positive module points per mark level. Let's not make it too complex on players, though.

• module_points_from_start: This attribute goes on the modular unit, and says its starting budget. It can be any number, and the scale does not matter. If you want players to spend 50 points per module, and 100 for expensive ones, you can do that. Generally I would say smaller numbers are easier to understand, however.
  • Usually module costs of 1 for cheap, 2 for normal, 4 for expensive, and maybe something higher for Very Expensive (tm) seems like it will handle most cases.
  • You can use different module point scaling on different units, if you need to. All of the modules are baked into the unit they are a part of, as is the module budget, so it's a self-contained formula per unit.

• module_points_added_per_mark_level: This is optional, but lets players earn more module points as their unit marks up. This is generally going to be highly desirable, but it's going to lead to extra power creep. Each module is getting more powerful as the player levels up, AND they're getting more modules? Make sure to account for that in your balance if that's how you do things.
  • An alternative to the power-creep approach is having everything be available from mark 1, and it's just a matter of which loadout is chosen. This duplicates the concept of things like the Riot Control Cruiser from AI War Classic, whereas the "more module budget over time" is more like champions.

Anyhow, for the ship itself, this is literally all you need to add, so that's pretty simple. The complexity comes in the systems.

Defining Systems As Modules

Normally, when a unit is assigned a system, it will always be a part of that ship (or available on that ship for only certain mark levels, perhaps). These types of systems are still present of course, and you can have these on a modular ship, too. For any system that is just to be an inbuilt normal part of a modular ship... do everything normally! Skip anything module-related and it will just be a core part of the ship and not available on the modules select screen for players.

For any modules that you want to define, however, those will all be systems. And THOSE systems have a number of specific attributes that are required to correctly identify them as a module, as well as stating how the module will be used.

• module_point_cost: This is the first key attribute that tells the entire system that "hey, I'm a module, I am normally not going to be a part of this ship unless a player selects me. And if the player selects me, this is how many module points it will cost."
  • It is not possible to scale module costs by mark level. However, if you wanted to do something like that, the best approach would be the usual min_mark_level_to_function="X" (to make something not available until a later mark level) or max_mark_level_to_function="X" (to make something phase out at higher mark levels).
    • Personally, I think that min_mark_level_to_function="X" and then having a blatantly more powerful module available later is creating busywork for players. It's fun to get new things as a ship line marks up, but it's probably more fun to mix and match than to just select the new singular most powerful item.
    • For similar reasons, I'd honestly suggest staying entirely away from max_mark_level_to_function="X" on modular ships if you can. Phasing out old modules will leave the interface cluttered and prevent players from customizing as much as they might want to. But you certainly CAN do it, it functions.
  • However you handle your costs, please make sure that it is feasible and reasonable for the player to always spend all of their points at all times! The game shows a warning to players who have not spent all their points, and so if you make it impossible for them to select the new cool thing plus spend the remainder of their points, they're going to complain because they now have a permanent notification sitting on their screen.
    • No there's not a workaround for this, either, haha. If we say "this is fine being un-spent," then when they get new points via an upgrade, it won't show them. If we say "allocate X points for now as okay" then that could in theory solve it, but that's more complex and far less interesting than you just giving them some neat cheap options to fill out any build they have going on.

• unique_module_index: In order to save data under the hood for which modules are enabled or disabled, this must exist for each module, it must be between 0 and 254, and there must be no duplicates for a given ship.
  • The order of these is fairly irrelevant, but if you don't specify any other sorting, then the interface will sort by the name, and then this if the names are duplicative.
  • With that said! Please don't change the unique module index after a savegame has gone to the wild! The savegames will remember which indices were active, not which modules by name, so if you renumber all your modules, that's scrambling player saves something fierce.

• module_screen_sort_group: This is an integer that lets you visually sort ships into groups, or visually sort each and every one.
  • This is a great way to say "the default is always first (at sort 0), then the basic options are next (at sort 10), then the expensive stuff (sort 20 maybe), and then the auxiliary stuff (at maybe sort 90).
  • If you want to hand-order your module options, you can also do that with this, just giving each one a specific number. If I may make a suggestion? Skip by 10s or 100s if you do that, so you have room to insert new entries later. You can enter any numbers here, so don't just go 1, 2, 3, or you might find yourselves painfully reordering them later.
  • Do NOT reorder systems themselves in the xml, by the way! If you do, that's a potential scrambling of existing saves, too. Once systems are added, they are what they are. You can change the visual order with this. If you need to remove one... try to avoid needing to do that. Replace it with something else instead. Removing one would reorder all the ones lower in the xml than it, scrambling savegame data again.

• module_is_enabled_by_default_at_mark_level: Unless you have some non-modular weapons that are applied from the start to a unit, it's very likely you want to apply a starting weapon or weapons to a ship, or it will seem to be unarmed when the player first gets it.

Modular-Only System Features

• There are new systems called module stat adjusters, which can currently adjust the hull health or shield health of units.
  • module_stat_adjuster (values: None, HullHealth, ShieldHealth, BubbleForcefield)
  • module_stat_adjuster_multiplier is then used to set a multiplier.

• There are now modular forcefields in the game.
  • To add these, simply use module_stat_adjuster="BubbleForcefield" module_stat_adjuster_multiplier="[YourMultiplier]" module_stat_adjuster_radius="[YourRange]"
    • Having a multiplier of 1 is fine if you just want to use the module to convert personal shields into bubble. This can be combined with other modules that increase shield strength, assuming the player has enough points.
    • The range expressed does not change with mark level, unlike non-modular forcefields.
    • The type of forcefield is still determined by stats on the main ship itself. So if you want to have a forcefield module that players can get, and it should be a hardened great-shield, then set those attributes on the core ship and then later add the shield just as a module.
    • It's possible to have multiple forcefield modules on a ship at once, but all it would vary is (in theory) the radius and the strength. If players turn on both at once, it gives you the combined strength multipliers, plus the largest radius. It is NOT possible have the shields on a ship vary in whether they are hardened, great-shields, electrotoxic, or whatever else. Those are centrally-defined only.

Modular Ship Prefixes

• On modules, there is now an optional modular_full_name_prefix and modular_sidebar_name_prefix that you can specify in order to have the sidebar and other locations refer to the unit a certain way when configured different ways.
  • Essentially, modular_full_name_prefix only gets appended when this is the "full name" that is shown, which is mostly tooltips and tech windows and such. This is an appropriate place to put adjcetives, like "Ensnaring " or similar, all with a trailing space as shown there.
    • Every last module that is enabled on a ship and which has one of these specified will add to the list, so it can be quite long. It's a good idea to not give minor modules a prefix, since they are just details and not the core identity.
  • modular_sidebar_name_prefix works the same, but is meant for adding onto the short-name that is shown in the sidebar, in lists of fleet memberships, and so on.
    • These should generally be something like "E" or "Es" or something like that. No trailing spaces or spaces at all, as that will be handled by the parser itself.