Modders Guide

Modders Guide This page provides information for players looking to create mods for the game. We have separate guides for the Map Editor and Scenario Editor Ashes of the Singularity gives you access to a powerful strategy game engine to create your own scenarios, objects and worlds. The designers have had a lot of fun creating scenarios for the game, and you will have access to the same features they had to create your own. There is a lot to do in Ashes. But it was also built from the ground up to be mod friendly. Modders have access to the gameplay elements to change and tweak as they desire. This document will introduce some of what is possible, and we will make a map and a mod to take advantage of this. This is not always going to be a managed and curated editor with limited options. You can mod the game the same way the developers make changes to the game. Editors are nice because they typically keep you from doing “bad” things. But they also keep you from doing incredibly good things. An editor only allows you to do the things the developer set up for you to change. With direct access to the files you can do things the developer never expected. Sometimes that turns out horribly (okay, a lot of the time that turns out horribly), but sometimes it turns out brilliantly. We believe power trumps ease of use. Moddable Game Files Just as with the Map Editor, to enable the game modifications add the “-modding” (without the quotes) to the Launch Options for the game (in Steam, right-click the game, go to Properties, click Set Launch Options in the General tab). That will add a Modifications button to the main menu of the game. You will not be able to play multiplayer if you are using Mods. The game supports modding the directories modders would be most interested in. These are: GameCore- The home of the most critical files, definitions for all the games units, buildings, weapons, orbital abilities, etc. This directory isn't additive, you make changes by replacing the file you want to change with a new one. For example, if you want to modify the hit points on the Zeus your mod will need to include a new UnitTemplates.csv file with the hit point value for the Zeus changed. Maps- For adding new maps with the mod. Scenario- For adding new scenarios with the mod. It is possible to modify existing scenarios with mods (by using the same name as that scenario file) but adding new scnearios with new names will be more common. UI- So a modder can add new art referred to by the Scenario file. UIText- For adding or changing existing text. Files placed here are additive (they don't need to replace an existing file). If you want to change a text string from the base game just include that string in your new text file and it will overwrite it. To create a mod add a directory in your My Games/Ashes of the Singularity - Escalation/Mods/ directory with the name of the mod you would like to use. In the above example the name of the Mod is BalanceMod. There is an index.ashesmod file that is a text file that contains the details about the mod. When you start the game it will create a generic one for you but the format is as follows: [AshesMod] Name=Balance Mod Author=Rob Brink Description=This is a Balance mod that also includes the Weehawken Scenario. Version=1.1.10 This is purely informational, its what is displayed by the mod on the mod screen. ModScreen.png Note: Ashes can’t use a file if it is locked. If you have a file open with Excel and try to start Ashes, the game will likely crash. Close the file before starting Ashes. To use a mod go into the Modification screen from the main menu. You will see all of your Mods here and you can enable or disable them, and change the order they load in. This can also be changed by editing the My Games/Ashes of the Singularity - Escalation/Mods.ini file. Notable Files for Modding All files for modding are found in the Steamapps\Common\Ashes\Assets\ directory. Any text editor can be used, but I'd recommend using a free program called CSVed as it'll make viewing and modifying values much easier. (If using CSVed enable "Use Start Row as Column Captions) The following files are the primary ones responsible for major gameplay changes: \GameCore\BuffTemplates.csv - Controls the value of Dreadnought buffs. \GameCore\BuildingTemplates.csv - Controls build time, cost, armor, HP, and more for all buildings. \GameCore\BuildingUpgrades.csv - Upgrade path for base defenses. \GameCore\DefaultPlayerAI.xml - Controls difficulty handicaps, personality types and armies built by the AI. \GameCore\Research.csv - Pricing of Quantum Upgrades. \GameCore\UnitPanel.csv - Controls the interface of build menus. \GameCore\UnitTemplates.csv - Controls build time, cost, armor, HP, and more for all units. \GameCore\WeaponVisual.csv - Controls visual weapon alignment and other weapon cosmetics. \GameCore\ModuleTemplates\BuildingModules\Sample.csv - Controls which weapons and ConstructionModules structures have. \GameCore\ModuleTemplates\UnitModules\Sample.csv - Controls which weapons, ConstructionModule and SteeringModules units have. \GameCore\ModuleTemplates\ConstructionModuleTemplates.csv - Controls which ConstructionLists a ConstructionModule uses. \GameCore\ModuleTemplates\DroneBayModuleTemplates.csv - Controls which drones or other units are spawned by units such as Drone Hives. \GameCore\ModuleTemplates\ResourceModuleTemplates.csv - Controls the amount of resources and storage generated by structures and upgrades. \GameCore\ModuleTemplates\SteeringModuleTemplates.csv - Controls the movement behaviour of units when engaging the enemy such as desired attack range. \GameCore\ModuleTemplates\WeaponModuleTemplates.csv - Controls rate of fire, range, targeting priority, damage, and everything else for all weapons. Orbital Abilities and healing weapons are also included here. \GameCore\ModuleTemplates\ConstructionLists\Sample.csv - Controls what units and structures are build able in a ConstructionLists. \Formations\FlockerTemplates.csv - Controls movement profiles for units. \Physics\RigidBodyTemplates.csv - Controls physics for units, affecting things such as pathing. \UIText\BuildingText.csv - Holds text strings used for in-game display of building names and descriptions \UIText\UnitText.csv - Holds text strings used for in-game display of unit names and descriptions \UIText\ModuleText.csv - Holds text strings used for in-game display of weapon modules and Orbital Abilities \UIText\Text.csv - Holds text strings used for game UI and other miscellaneous things. File Mod Example There are a lot of files, with a lot of fields that can be tweaked and changed. For this demo we are going to mess with my favorite file, UnitTemplates.csv. UnitTemplates.csv In this screenshot the file UnitTemplates.csv is opened with Excel, because it makes it easier for me to work with, but Excel isn’t required. Notepad could be used to modify the file. If you use Excel remember to save it as a csv file. There are a lot of fields that can be modified. In this screenshot you can see: Max HPs Max Energy Energy Per Second Armor Heal Rate Max Shields Shield Regen Rate Radar Radius Cost Metal Cost Data Cost Energy Cost Logistics Construction Time Some of these fields aren’t named the same as they are in game. Names change during the course of development, and we didn’t want to go back and change all these definitions to match each time they do. Because of that you may have to experiment a bit to see how things match. For example, PHC_Smarty is the Smarty System, and Cost Data is actually the Radioactive cost of the unit. You can check out the translation tables in ..\Ashes of the Singularity\Assets\UIText\ directory to see how raw assets relate to in game assets. Using this file alone, and just the things in this screenshot (there are many more fields in UnitTemplates.csv) we can dramatically alter the balance and design of the game. Let’s use the above to create a new game variant I call the Swarm Mod. I love the scale of Ashes, I love large battles. So this mod is going to make even larger battles possible and we are going to get into them fast. To do that I’m going to make the following changes: UnitTemplates.csv, modded I’ve reduced the Metal, Radioactives, Logistics and Construction time costs by 90%. I’ve reduce the Logistics costs of T1 units to 0 (so you can have as many as you want). With these changes factories should produce 10 units in the time it took to produce 1 before. As long as you can keep feeding the (dramatically reduced) resource costs, units should come out of factories in an endless stream, like a tower defense game on steroids. There are a lot of ways to tweak this concept. I could have kept the Metal and Radioactive costs the same and then the player would be strongly incented to claim and upgrade regions to keep his factories fed. I could have just halved the costs rather than dropping them by 90%. I could have increased the resource gathering rates of upgraded metal and radioactive mines rather than lowering costs to incent players to invest in their regions. But for this we are going crazy. Everything gets very cheap. Massive armies can be built from the start of the game. Those poor creeps won’t know what hit them. And be prepared to be sieged by thousands of units. Swarms of frigates! This is 5 minutes into the game. I only have 2 factories putting out an endless stream of Brutes. I make an army out of them and in the time it takes to do that there are a bunch more waiting to be added. So I find that it works just as well to set the rally point of the factory to where I want to attack, so that my river of death flows out to destroy it. Pew! Pew pew! The AI has adapted to the new lower costs and is meeting my endless streams with its own. Unlike me it has opted to go with some cheaply produced dreadnoughts. The game lasts for 45 minutes, and there is a battle waging between my endless armies and his at this chokepoint for nearly all of it. It isn’t until I win more minor battles on some of outskirt regions (to take the resources which even at 90% off still become critical) and I send a strike force around to take out his factories that I cause his production chain to falter and begin to break through. Pewpewpew! I had to adjust away from my typical Artemis (long range missile ships) to Nemesis (which are really good against enemy dreadnoughts) to be able to begin killing them faster than he could produce them. I also needed to invest heavily in anti-air Apollos to counter the AI’s strike fleets of aircraft that nearly cost me the game. Once the lines were broken I turned the biggest Ashes armada I had ever controlled against his Nexus. There were a lot of dreadnoughts fighting their way up that hill, and the explosions, missile trails and laser blasts cut through and won me the game. Overall it is amazing how much game play can change with these changes. If I were to do it again I might keep the reduced cost overall, but maybe just 50% off rather than 90%. I liked the larger armies, but it was a crazy experience more like fighting a fire than playing chess. If you decide to modify the csv files with a text editor (Notepad++ is my text editor of choice) you can do everything I was doing in Excel, it just isn’t formatted into columns to be easy to read. Instead it is raw text like the following: A .csv file in Notepad++ Modifying the files this way works, you just need to count the amount of fields, remembering that commas separate the fields (CSV stands for Comma Separated Values) to get to the right values. Adding a new Map to a Mod It is also possible to add a custom map to a Mod. The in-game map editor will always create a map in the default \Assets\Maps\<mapname> directory. To include that map in your mod, once created you'll need to move the entire map directory into your <ModName>\Maps directory. Once the map is in the mod directory and the game is restarted, the Map Editor will be able to edit the map directly from the mod directory. Current Limitations (Ashes 2.7) The Ashes developers are working to expand Modding support, however there are a few significant limitations to the existing modification support. The following files from the Ashes \Assets\ directory are currently NOT modifiable. \Audio\: Contains the audio used for in game effects and voice overs. \Units\: Contains the models and textures for all the units in the game. \Buildings\: Contains the models and textures for all the buildings in the game. Several gameplay features are currently drawn from game code and not able to be modified via the csv files: Dreadnought Upgrades Values for Dreadnought upgrades such as the rate of regeneration or weapon damage can be modified, but changing the upgrades and their unlock sequence is not configurable. Orbital Abilities Values for Quantum Upgrades such as the damage and cost can be modified via WeaponModules.csv, but changing the utility and availability is not configurable Quantum Upgrades Values for the Quantum Upgrades such as the cost and bonus can be modified, but changing the utility and availability is not configurable Safe Mode If your Ashes installation with Mods gets into a state where the game fails to load. It is possible to still load the game via safe mode. Safe mode will not load any mods, but will still present the user interface for enabling and disabling mods. You can open the interface, disable the offending Mod, and restart Ashes in the normal mode. To start safe mode, select the option from the launch menu in steam, or add "-safe" to the command line arguments. Creating New Units (Work-in-progress) With Escalation 2.4, modders are able to introduce their own custom units into the game as mods. Adding a new unit to Ashes can be a complicated process, so to make it easier for modders to follow along with this guide, we have provided a sample mod of a custom unit called the "Little Boy". The Little Boy <ref name="Little Boy">Little Boy - https://en.wikipedia.org/wiki/Little_Boy</ref>, named after the first atomic bomb deployed during World War II, is a Tier 1 unit that shoots nuclear warheads from its single turret. Download the tools required to build a unit mod from here: http://downloads.ashesofthesingularity.com/AshesModdingTools.zip Download the "LittleBoy" sample mod from here: http://downloads.ashesofthesingularity.com/AshesSampleMod.zip The Anatomy of a Unit In order for a unit to appear in-game, a series of data (used to configure the visual aspect of the unit) and texture files must exist in the mod's folder structure. These files are: {AssetName).FBX Textures (these are .dds files in various formats) Ambient Occlusion Diffuse Curvature World Space Normals Material Masks Team Color Masks {AssetName}.MeshDesc {AssetName}.Palette {AssetName}_TimelineSet.xml Unit.AssetGroup Design Guidelines for the 3D Model Unit of Measurement: Centimeters (as a point of reference, the Nemesis is 56.75 cm long) Ideal Triangle/Quad counts: T1 Units: T2 Units: 5,000 - 15,000 tris / 2,500 - 7,500 quads T3 Units: 40,000 - 60,000 tris / 20,000 - 30,000 quads T4 Units: 40,000 - 60,000 tris / 20,000 - 30,000 quads Buildings: 45,000 - 55,000 tris / 22,500 - 27,500 quads or less All models must be exported as a .FBX file with the triangulation option enabled. If the geometry is not triangulated, an error will be occur during the baking process. Each mesh should have its own UV sets. In general, every unique mesh should have it's own "palette" (which is represented as a record in an asset's .Palette file) and set of textures. Though, there are some cases where multiple meshes should share the same palette and texture files (i.e. a unit that has multiple guns that are identical). Each mesh is required to have a 2nd UV set. This 2nd UV set is used to map a faction specific overlay texture to the model. This overlay texture provides additional details to units (i.e hull patterns). More information about this 2nd UV set will be provided in later sections of this guide. Best practice is to have the 2nd UV set be a copy of the primary UV set. Whenever making changes to the UVs, be sure to reflect the changes in the 2nd UV set (this will likely involve deleting the existing 2nd UV set and recreating it as a copy of the 1st). Every model must have a top-level mesh called "Root". All other meshes (i.e. guns, turrets, arms, etc.) must be child meshes beneath this parent "Root" mesh. Texture Authoring Guidelines and Best Practices Author your textures in 4K resolution (3840 x 2160) and scale them down from there when getting them into the game. It is advised to NOT use 4K textures for your units in-game as they will likely have a negative impact on the performace of the game due to the large amount of VRAM needed. Export your textures from whatever authoring software you are using (i.e. Maya, Substance Designer, etc.) in 3-channel (RGB, no alpha) .tif format. Ashes: Escalation expects all textures used in-game to be in .DDS format, but it is a good idea to maintain a "source" copy of your textures in .tif format as they're much easier to iterate on than .dds files. When you're ready to get your textures into the game, you should follow the process described in the following Required Textures and How to Convert Them To DDS Format section for how to generate the .dds version of your textures. The best size for your textures covering the main body portion of your new unit (most likely the "Root" mesh) is 2K. Of course, there is nothing to stop you from scaling textures down even further if they looks good enough in-game at a smaller size. But, 2K is a good starting point, and at the same time it is definitely a size you don't want to surpass. The textures for all the other parts of your unit that are small, like turrets, should be at least 1/2 the size of the main body textures. So, if your main body textures are 2K, your turrets should be no larger than 1K. If the turrets are small enough, it is a good idea to experiment with smaller sized textures, like 512 and 256. Be sure your textures are sized in increments of the power of 2 so that MIPs can be properly generated during the DDS conversion process. Required Textures and How to Convert Them To DDS Format The following textures are required to be defined in the unit's Palette file, and must have the provided DDS format: Ambient Occlusion - BC4_UNORM (ex. Root_AO.dds in the LittleBoy mod) Diffuse - BC7_UNORM (ex. Root_Color.dds in the LittleBoy mod) Curvature - BC5_UNORM (ex. Root_Curvature.dds in the LittleBoy mod) World Space Normals - R10G10B10A2_UNORM (ex. Root_Normals.dds in the LittleBoy mod) Team Color Masks - BC4_UNORM (ex. Root_TeamColor_MaskArray.dds in the LittleBoy mod) Material Masks - BC4_UNORM (ex. Root_Material_MaskArray.dds in the LittleBoy mod) As a best practice, it is recommended that you export your textures from whatever graphics authoring tool you are using (i.e. Photoshop, Substance Designer, etc.) as .tif files WITHOUT the alpha channel. TIF files make a good medium for iterating on textures, as opposed to trying to make edits to the texture in DDS format (which can be difficult to do, depending on the format). The Team Color Masks Texture When setting up a Skirmish or a multiplayer game, the player gets to select up to 3 colors to represent their team. It is the purpose of the Team Color Mask texture to control how those 3 colors are shown on the unit in-game. A combination of these 4 separate masks make up the Team Color Masks texture: TC1 - The primary team color mask. Anywhere there is white in this mask, team color #1 will show up. TC2 - The secondary team color mask. Anywhere there is white in this mask, team color #2 will show up. TC3 - The trim team color mask. Anywhere there is white in this mask, team color #3 will show up. Decal - The decal mask. Anywhere that this mask is white, the Diffuse texture is used directly as the color. This mask is will appear on top of TC1, TC2 and TC3 and is the way you would include markings (or "decals") and any other area on your unit that should remain the same color, regardless of the team colors picked by the player. Using the OxTextureTool.exe tool, these 4 masks are combined into a single DDS file representing the TeamColorMasks texture. Within the package of files for the LittleBoy mode you will find the \SourceArt\maps\MakeTeamColorMask.bat script file. Open up this file to see the process for converting the TC1, TC2, TC3 and Decal mask files into the correct DDS format and then how to merge those 4 DDS files into a single "mask array" texture file. Here are the steps (you can follow allong in the MakeTeamColorMask.bat file): (Lines 1-9) Run the texconv.exe tool against each set of TC1, TC2, TC3 and Decal mask files created for each of your palettes (reference the \Units\PHC\LittleBoy\LittleBoy.Palette file for which Palettes have been defined for the LittleBoy mod) (Lines 12 & 13) Run the oxtexturetool.exe tool against each set of converted TC1, TC2, TC3 and Decal files output by the texconv.exe tool. Note that the -o argument passed to the oxtexturetool command is the name of the output mask array file you want generated. It's important to note that the file names used in the \SourceArt\maps\MakeTeamColorMask.bat script file of the LittleBoy mod are specific to the LittleBoy unit, and that you may name these source files however you like. The Team Color Masks texture is set in the unit's Palette file via the "TeamColorMasks" column. Whatever you provide as the file name that the OxTextureTool.exe tool outputs (via the -o argument) must match what you provide for "TeamColorMasks" column in your unit's Palette file. What you provide for the "teamColorMasks" column in your unit's Palette file must be a path to the file, relative to the root mods directory. The Material Masks Texture PHC Unit Materials MM1 – Painted Metal This is meant to represent a painted surface. Most of a PHC unit uses this material. This material responds to the TeamColor_MaskArray texture as follows: Base color of Painted Metal is a constant mid-grey color (hard coded) TC1 – Team color 1, the primary team color. Anywhere this is white, teamcolor 1 will show up. TC2 – Team color 2, secondary team color. Anywhere this is white, teamcolor 2 will show up. TC3 – Team color 3, trim team color. Anywhere this is white, teamcolor 3 will show up. Decal – Decal mask, anywhere that this mask is white it uses the ColorMap directly as the diffuse color. This overrides all the other teamcolor masks. Unlike material masks, you won’t get overbright textures if these masks overlap, you’ll just get overlap like layers in Photoshop, in this order (top down): Decal TC3 TC2 TC1 Base color Painted Metal is affected by the Curvature Map in that edges will be worn off to expose MM2 (Bare Metal). Painted Metal also uses the panel detail texture found in Assets/Material/PHC_Unit_Panels.dds that has the following channels: R – Panel dirt G – Panel edge-wear B - AO A – Overall color variation White means lighten the color 50% Grey means do not change the color Black means darken the color MM2 – Bare Metal Dark silvery material. This material uses the Curvature map and panel-detail map to darken the metal in crevices and shine and brighten it on edges. This material does not respond to the Color map in any way. MM3 – Emissive Glowing parts of the model (running lights, etc.) The brightness of the emissive lights is set in the material. However, the material reacts to the Color map by multiplying it in. You can set up the color you want the emissive to be by coloring that area of the Color map. Generally those have been set up with a fade around the edges to make the glow look softer and mip-map more nicely with distance. MM4 – EngineEmissive Glowing parts of the hover pods/engines This works much the same way the MM3 Emissive material works, but it uses the color map slightly differently. It multiplies the Color map as a grey-scale value with the engine color for that team (set up with the team colors). You still get the effect of the edge fading like regular emissives, but not the color tinting. The overall brightness of the Engine Emissive material is scaled by the amount of “thrust” being applied to the object. Engines brighten when the unit is moving itself, darken when it’s not. Dust – This is not directly controlled by artists. A combination of factors determine where dust is applied, the dust overlays all other materials (except emissives). The FBX File The models for all buildings and units in Ashes: Escalation were authored in either Maya or 3dsMax. Of course, this does not mean that other tools like Blender or Modo can't be used. Be aware though that there are minor differences in the ways that each of these 3D modeling tools export FBX files and that their output can be inconsistent between what each tool outputs. This can have the effect of introducing flaws into your model when bringing them into the game. Troubleshooting Fatal Error: Assert Fail: pMesh->GetPolygonSize(0) == Model::eNumIndiciesPerPoly File Models are required to have triangulated polygons. When running the Texconv, OXTextureTool or EasyBake tools, if you are prompted with an error dialog saying MSVCP140D.dll or VCRUNTIME140D.dll or VCOMP140D.dll is missing: You will need to install the Visual C++ Redistributable for Visual Studio 2015: https://www.microsoft.com/en-US/download/details.aspx?id=48145 <references />