[2021] Stellaris Dev Diary #222 - Moddability Updates in Lem

Zomaar: Je kunt meer informatie over dit evenement hier op de aankondigingspagina vinden.

by Caligula

Welcome to another Stellaris Modding Dev Diary! Today, I’ll be talking you through some of the new scripting language features in the upcoming 3.1 patch.

We have already mentioned that Traditions are considerably more moddable [forum.paradoxplaza.com]now with the new system, with far less heavy lifting needed in the gui and loc files. I can also confirm that you can, for instance, now script in tradition trees that only become available if you make certain decisions during the game. But today, the main focus will lie on variables.

Variables
I mentioned last time[forum.paradoxplaza.com] that we have been looking to do more with variables. In the last patch, several more ways to save various bits of information in the game were added, but the biggest missing one was an easy way to get trigger values, like for example the number of pops on a planet. You also were still quite limited in where you could use variables, especially compared to PDS’ newer games like CK3. Also, the syntax for using them was not quite ideal, in many cases.

With 3.1, we have greatly increased the power of variables. First of all, the format: previously, when you wanted to get the value of a variable, you had to refer to… well, the variable itself, and that was all. Now, you can do a few more things:
value = my_var #gets the value of my_var variable set on the current scope

value = from.capital_scope.my_var #gets the value of the my_var variable set on from’s capital

value = trigger:num_pops #gets the number of pops in the current scope

value = from.capital_scope.trigger:num_pops #gets the number of pops in from’s capital So you can do dot scoping, which saves a lot of ugliness, and is a big improvement as it is. And as you can see, you can also refer to triggers, with trigger:<trigger>. This will support any trigger checking a number and just a number, with no { }.

(Note: the previous, ugly format for copying variables across different scopes has been removed. The one where you'd specify "value = { scope = x variable = y }")

3.0 already had an effect, export_trigger_to_variable, but it only worked with fleet_power. That was the prototype; the functionality has been expanded to all such triggers. Importantly, that effect lets you get values from triggers that are a bit more complex, with { }, that are still comparing a single number:
export_trigger_value_to_variable = {
trigger = num_assigned_jobs
parameters = {
job = miner
}
variable = num_miner_jobs
} 3.0 also, to mention it again, added a bunch more ways to get game values such as modifier numbers and resource stockpiles to variables. It also added a few more places where you could use them: multipliers in add_resource and add_modifier, for instance. With 3.1, we have added a lot more things that you can use a variable for:

• As values in triggers checking single numbers, e.g. "num_pops > my_variable", "intel = { who = from value < trigger:num_pops }"
  
• As values in effects using a single number, e.g. "add_experience = my_variable".
  
• As a multiplier parameter in triggered resource tables (e.g. in a building):

resources = {
category = planet_buildings
cost = {
trigger = { <triggers> }
minerals = 100
}
multiplier = my_var/owner.trigger:num_pops
}

• In MTTH/AI Chance modifiers:

ai_chance = {
factor = 1
modifier = {
add/factor = my_var/trigger:num_pops
is_variable_set = my_var
}
}

• add_modifier now has a time_multiplier as well as a multiplier parameter, you can use it there. E.g. for death cults, this is used to apply a modifier for 10 years X edict_length_mult
  
• In ordered_script_lists: a feature yoinked from our newer games. I’ll let the trigger docs entry explain:

ordered_owned_fleet - Iterate through each fleet owned by the country - executes the enclosed effects on one of them for which the limit triggers return true. Picks the specific object according to the order specified (position 0, order_by = trigger:num_pops would run the effects on the X with the most pops)

ordered_owned_fleet = {
limit = { <triggers> }
position = <integer, starting with 0>
order_by = <variable>/trigger:<trigger>
inverse = yes/no (default: no - if yes, then 0 is lowest rather than highest)
<effects>
}

Supported Scopes: country If your variable is too exact a number, you can now use round_variable_to_nearest to round its value to e.g. the nearest multiple of 10.

A summary of these functionalities have been added to an information file in the events folder (and attached to this post). Also, I could well imagine further expanding on these usages of variables, so it’s quite possible there will be even more coming along these lines in future. The changes have already proven extremely useful to us, e.g.:

• Improving Death Cult rewards: cut about 1000 lines of script and still ended up with the new version taking more factors into account to determine the adequate reward for you!
  
• Fixing Golden Rule cash payouts: the previous solution was to fudge the numbers and give you an amount with a rather tenuous connection to the actual pay-in. This is no longer necessary.
  
• Improving Federation Science Leadership Challenge: adding the actual number of techs and repeatable techs you have researched as a factor
  
• And more.

Sprite Sheet Changes
That was already quite a lot, but there’s a few more things that I’d like to highlight. Firstly, certain older elements of the game used sprite sheets for their icons - a system where a list of icons would all be in a row on one image file, and we’d specify that we’d want to use, say, the 5th icon on the list. We had a few issues with these inhouse (the colony automation button currently accidentally being a robotic cow springs to mind), and modders have pointed out that they are a pretty bad overwriting bottleneck, since only one mod can overwrite the sprite sheet at a time, and therefore only one can add extra types of that object that add new graphics at a time.

We figured out a way to change index references to icons in sprite sheets into normal key references, which meant that we could convert these elements of the game to use string references to sprites (with no need for new icons to be inside a sprite sheet). This got rolled out to the likes of army types, colony automation types, bombardment stances, and (with great difficulty!) ship sizes.

An example:
spriteType = {
name = "GFX_ship_size_military_1"
sprite_sheet_sprite_type = "GFX_ship_sizes"
default_frame = 2
} In the case of ship sizes, it was a bit tricky, since the icon_frame index number then specified which icon it would use on multiple sprite sheets. In the end, we left that system in place for starbases (since very few tend to add a new type of starbase) and made the line “icon = ship_size_military_1” tell the game to refer to several sprite keys: GFX_text_ship_size_military_1, GFX_ship_size_military_1, GFX_ship_size_military_1_top, GFX_ship_size_military_1_top_damaged

This will need some updating for mods which change the affected objects, since the old format no longer works, but in the long term it will hopefully solve a lot of compatibility headaches!

Randomness
Some have noticed that, in certain cases, the randomness of script functions such as random_list is not very random. Specifically, events fired from on_game_start had this issue (and various other on_actions, but that was the one that hurt the most). This was pretty unfortunate, since this effectively meant that certain things that were meant to be different each game... simply were not. Relatedly, we also revisited some more longstanding issues like where if you used while loops or every_x loops, each time the effect happened within that loop, the random result would be the same. (As in 25x random_list resulting in 25x the same result rather than 25x a random result).

We fixed this quite exhaustively:

• The lack of randomness in on_actions like on_game_start is fixed. If we in future make the mistake that caused this to happen again, the game will warn us, so hopefully it is banished for good.
  
• While loops and every_x loops have improved randomness
  
• For good measure, we added a reroll_random effect

Other Cool Stuff
On another note, we can now add triggered pop modifiers to traits, so for instance, you can add a trait that gives a bonus on one planet class and a penalty on another. The potential that this unlocks is quite considerable - for instance, it allowed us to stop using the somewhat unintuitive (and eminently cheeseable) stopgap solution of giving Void Dwellers two traits, and instead giving them one that applies differently depending on what sort of planet they are on.

As some have noticed, the Clone Army origin does several cool, new things that we haven’t really explored in the game before. A lot of what we added for it could have further cool uses in the future, for instance:

• You can now gender-lock species
  
• You can set an empire limit on how many instances of a building you can build. (And alter it during the game).
  
• A game rule, “should_force_decline_species”, has been added. It will make a species for which it returns true decline on a planet, triggering an alert based on whatever tooltip is specified in the game rule. It is also hooked up to stop pops from migrating/being resettled/etc to a place where they would immediately start declining.

Finally, we added a bunch of new effects, triggers and modifiers, as usual. A couple to highlight are:

• set_visited = <system> - reveals a system to you, without you having surveyed it
  
• set_saved_date - lets you save a specific date (can be in the future) so that you can use it in locs, similar to variables: [This.my_saved_date].
  
• Technically, the last effect is actually adding a <scope>_flag, so the standard flag effects and triggers have been ported over to all scopes
  
• You can now use [loc] commands in button effects, which apparently will be very useful for dynamic modded UIs
  
• You can define descriptions for districts, buildings, jobs and special projects through desc = { text = X trigger = { Y } } now. They also now take loc commands.
  
• We deleted has_non_swapped_tradition and has_tradition_swap, and consolidated them into has_active_tradition. Modders: do a search-replace!
  
• Every scope that lacked script flags (e.g. country_flag) now has them. Also, variables work in all scopes now too.
  
• Note for updating mods: count_diplo_ties is now count_relation, count_armies is count_owned_army or count_planet_army (depending on the case). any/every/random_mining_station/research_station have also been removed, because they were nonsense. Use simply mining_station/research_station/orbital_station scope change instead. Also, observation_outpost no longer takes a "limit", but you can say "exists = observation_outpost" as compensation.

Adding all these new functionalities has been a boon for us in the Custodian team, and we are gradually rolling them out to older parts of the game which can benefit from them. It’s something I look forward to doing more of in future, and equally, I am excited (and, I’ll admit, a tiny bit afraid) to see what modders will do with them!

One last thing: the old trigger_docs.log has now been deprecated, and instead we now have a more wieldy and more comprehensive script_documentation folder, the contents of which are attached to this post[forum.paradoxplaza.com].

And as some of you are probably aware, we did some early access for Modders for the Nemesis update. We had ~10 mods update on release day, servicing around 1.6 million subscribers, overall we were very happy with the results and the community reaction, and if this continues to go well we’re looking to gradually expand this experiment to more of the Modding Community. For Lem, we’re looking to add another 10-ish Modders to the early-access experiment. If you’re interested you can fill out the Modder Early Access Request form.[docs.google.com]