Big Changes - Better Code
As previewed and hinted at in a few other threads, the next patch (super soon) - is loaded with new or updated systems, tweaks, and reorganizations that should allow for a whole new phase of Mod development. These changes also lay the groundwork for some of our internal efforts, prepare for new Mod features, and point toward where (and how) further changes will be made.
Because these edits encompass a LARGE number of very major systems they are going to make future Mod authors squeal with glee, and current Mod authors maybe a bit grumpy. This has been a HUGE effort and is looking quite solid - but as with all large deltas (something like 350 files at this point), it may create new issues (hopefully minor) - and the additional flexibility really demands that Mod authors step back from the code/script and think. The patterns introduced here will likely spread to other systems, so taking the time to get behind our new way of arranging and parsing data is critical to your sanity as a Mod author
There are a handful of ‘new’ (to this codebase anyway) ideas, things that are repeated any place we’ve done edits. The features and choices that these new structures/systems create a given area vary, but generally the thinking behind these changes is consistent:
- Folder scans - The game gathers the things it can use at boot by searching for them. When possible, hard-coded ‘list’ lua files are GONE. Yes, race.lua is an example, I am sure you can think of others. The engine used to have some scans, but they weren’t consistent, and didn’t have the connections to related data that the new code utilizes.
– The idea here is that the old ‘list’ files meant Mods had to edit them, making stacking or minor mods VERY hard. Now, if you love a certain Mod, you can add new stuff for it without affecting almost any of the base files.
- Flexible data types - Tag (sorta a bool), Number (float), String (eh… string?). Now, when some thing you are working on (a Race, Game Rule, Ship, etc) needs to define most of its data, it will be stored in a sub-folder of that thing, inside a file by type (.tag, .prop).
– This means that you can edit properties of many things in the world without editing existing files (usually) - and it also means people can add data on top of your mod (or to complement) without worrying about changes from the base Mod clashing. Done carefully, this can be insanely useful, empowering, and also really help clarify where design edits have been applied.
- Tag filters - Most of the new files loaded by the game can be ‘removed’ from load by simply forcing them to fail a tag filter test. An easy example is one of the base HWRM races - Vaygr. If you just really don’t like them, you can have your Mod apply a filter (details below) to prevent them from loading. As long as nothing else you are loading requires them, the game will run fine, and they won’t appear. Your Mod can contain a special file that defines the tags to use when loading things. So, for a ‘TC’ style Mod, you can filter out all of the base content, and filter in only the content from your Mod. All without having to hack (ideally) any existing files.
– Again, when you don’t have to hack files, you aren’t at risk of an update breaking your Mod, or somehow having to ‘delta’ a patch from us against your Mod. Sure, features or syntax may need some updates, but knowing that your Mod is your files, and will work is a huge benefit.
So, with the base concepts out of the way, let’s talk specifics:
First and foremost ‘rubrics’ are GONE. The game has 3 major modes: Single Player, Skirmish, and MP. But those aren’t used or exposed to scripts/assets any longer. Instead, all modes must have a GameRule (GR). If you know much about the engine, you know this was already the case (sorta) - but the new system is making this the #1 rule.
Hello Game Rules (GR)
GR can ‘filter’ game content in a number of ways:
- Limit Races available
- Expand Rule-specific Race properties
- Limit Levels available
- Expand Ship-specific Ship properies
GR also have a number of new properties that can be seen and used by assets (.ship files) and in-game (the Rules lua, AI, etc)
- Tags - essentially ‘yes no’ flags, any you can imagine.
- Numbers - any you can imagine
- Strings - seeing a pattern yet?
The properties of a GR aren’t stored in a single file (though an initial single file is used to create a GR)… instead there are a series of folders that are searched for script/properties to add to the GR. This means modding a GR for almost anything is an ‘add a new file’ process - almost NEVER a ‘change this existing file’ or ‘nuke this file’ process.
When a GR is selected the tag filters it has for Races/Levels are applied to what the game has detected, so if a level doesn’t match the GR tags for levels, it won’t show up in any lists - ditto for Races.
Races, like GR, now have properties - Tags/Numbers/Strings - and like GR they are loaded by searching sub-folders. In addition, when a GR filters (and keeps) a Race, an extra set of folders defined by the GR is searched under the Race - allowing GR to actually mutate Races. Maybe you have a ‘Free for all’ GR for DM - and the Races are all balanced - but then a ‘Topple the Empire’ GR for DM where one Race is MUCH more powerful and players are supposed to gang up, etc. This is all VERY easy now. This also means that balance tweaks and Mods become less about hacking, and more about careful planning and properties building.
Unit caps now exist per-race and per-game rule.
AI used to be a ‘per level’ or ‘per game rule’ thing. The AI files were very heavily hard-coded for races as well. Yeah, that’s gone.
AI can still be per-level. But AI is now defined per-race (and yes, GR can override this per-race). AI scripts use the Race properties and GR properties… so instead of ‘if race is Vaygr do X’ you see ‘math value = SelfRace_GetNumber(“important_property”, 1.0)’ - no more hard coding, period.
AI also used to live in a bubble where they couldn’t see much about the world - and while this is still true (though I think we have a bit more to do there) - the new systems to query Race and GR values, on top of AI being able to vary (completely distinct code per Race if you wish!) is going to mean much smarter AI with way less hacking or hard-coding. I am excited not just for what we can do, but for what all of you will do.
If a file used to exist in some random folder (I’m looking at you BuildAndResearch!!!) - it’s now most likely found under a specific Race’s path. Almost every script or config asset has been moved and rebuilt to work properly. In theory adding a new Race will be CRAZY easy.
Oh, and that old ‘Random’ Race select in Game setup? ‘Random’ is now a type of Race - and it can choose to filter the other races. So while ‘Random’ can be a Race which selects any playable (and allowed by the GR) race, it can also apply stronger limits…
- Random HW1 Race
- Random HW2 Race
- Random Evil Race
- Races With Extra Arms
You get the picture. And as Mod authors, you can go nuts - without hacking.
Ship Properties From Outerspace!!!
As with GR and Races, Ships can now have properties that vary by the Rule being activated. Ships can also ask a Rule for properties. The important difference here is mostly name-space. Here’s an example:
A Scout is being loaded. It needs to define the maxHealth for the unit. The script can:
- 1 - NewShipType.maxHealth = getRuleNum(NewShipType, “health_for_scouts”, 100)
- 2 - NewShipType.maxHealth = getShipNum(NewShipType, “maxHealth”, 100)
For #1, that value will come from one of the files found in a ‘Props’ folder for the current GR. But for #2, that value will come from ‘Props’ in the Ship’s own folder, or a sub-folder for the current GR. It is local to only that ship.
Oh, and in-game, your code (UI, AI, and Rule LUA) can now ask for anything you define as a Property. You can add and define anything you want. This means you can decide that you wish AI would treat certain ships differently… and ask something like:
local myValue = Sob_GetStaticNumber("Hgn_Scout", "howUglyAmI", 3) if myValue > 4 then FREAK OUT
In this case the Sob type was hard-coded, but your code may have tables or other symbolic paths to this info. Now, you can author data about ships and change it per GR, all in a single Mod. For a TC mod this is a big deal… you can make a GR for ‘balanced’ play, another GR for ‘aliens vs robots’ where aliens are 5x stronger… or a GR called ‘rice paper hulls’ where ships are super weak and weapons are super strong. Again, without hacking the crap out of every file - and all in a single place.
A few random new edits (less systemic, etc)
- Research and Build items costing a single RU are now invisible - no need to force restrict them everywhere.
- ‘Attack Run’ has new properties to make it much more natural and useful. Edits for other flight behaviors are in the R&D phase.
- ATI scripts can now be selected from the UI. Colorblind or just preferential changes are easy and shouldn’t count as a ‘mod’. The toolkit will get edits for this shortly.
All of these edits and new systems enable Mods to do things that were simply unthinkable before:
- Add Races to existing Mods (and the base game!)
- Add Game Rules to existing Mods (and the base game!)
- Create ‘balance’ style Mods that work on top of existing files (best done with a new GR)
- Create Mods that Mix & Match different designs (space goverment vs ancient aliens)
- Create new AI that has more information and design flexibility than ever before
From Old Mod to New Mod
Depending on the details of what your old Mod had in terms of edits to our base files, there are likely quite a few areas where things no longer function. In most cases this is going to be an issue of simply moving your edits to the newly located files, or adding new files to contain your edits and allowing them to stack on top of the updated structure. Here’s a quick list of the most common issues:
Races are now distinct folders/scripts. Virtually any race property before is now in only the folder and data files for that Race. The structure is pretty clean and easy to follow. Race meta-data (name, desc, etc), any scripts, stuff that you used to find all over other files that said ‘if Race == Race_Vaygr’, etc - is now probably just in a single file for that race. Ditto for Unit caps. If a Race used to override or customize a specific cap or family for itself - it’ll be in that Race’s data files.
AI and related data (Restricts, Build & Research, etc) - also either cleaned of Race hard-coding and left where it was (LevelData\lib, etc) - or moved into a specific Race.
Rubric tests in .ship files - Rubrics don’t exist! You should see properties loading from either the Rule or Ship (as in the example above). Think hard about how you edit ships, and try to make your edits also use external properties - it’ll make future edits easier. As a further note, it is likely that .ship variables (the basic stuff you see as NewShipType.xxx) will go away in a future release… to be replaced by an ‘auto load’ of Props with the same name. The other commands (adding abilities, weapons, etc) will switch to being sub-files of the ship (and yes optionally game rule!) - allowing what defines a ship to be built up by additional scripts. This will hopefully include adding new hardpoints, moving or deleting others, etc.
The SinglePlayerOptions.lua file used to be where the SinglePlayer GR lived. No longer, it is now inside a correct folder along with all of the other new GR files. There are a ton of changes, most of them very clear and obvious. If you have issues, please ask if they aren’t answered. A much more detailed discussion of each file and the data inside will be added to this thread shortly.
MY MOD?! What did you do?!
Some older or abandoned Mods will probably need real work to update for this patch. In this case, I urge you to contact the authors of those Mods. We can’t add new systems and improve features without making edits someplace… and Mods no longer being maintained are at risk of causing issues.
On the Radar
Almost certainly some of these edits will have side-effects, we’ll find and kill those as needed. In addition, some of the ‘old’ code that was very hardcoded will relate to Races or other new flexible systems - that has been heavily audited, but some may not be obvious… We’ll nuke old stuff and move more into the Race folders are required. If you, as a Mod author can see a way to change something, or a LUA interface that would help you (and not cause issues, create cheating trouble, etc) - make suggestions. This is still an evolving project for everyone involved!
There are a rather large number of new interfaces to define, specs for scripts and meta-data to lay in a more technical manner, etc; so I will do that in the Mod support area. Once the patch is out (VERY SOON) - feel free to ask questions, try this new stuff out, etc. We aren’t done, and these patterns will continue to be refined and cleaned.