• We have updated our Community Code of Conduct. Please read through the new rules for the forum that are an integral part of Paradox Interactive’s User Agreement.

Stellaris Dev Diary #222 - Moddability Updates in LEM

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 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 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:

Code:
    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:

Code:
    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):
Code:
     resources = {
        category = planet_buildings
        cost = {
            trigger = { <triggers> }
            minerals = 100
        }
        multiplier = my_var/owner.trigger:num_pops
    }
  • In MTTH/AI Chance modifiers:
Code:
     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:
Code:
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 worked 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 the normal system (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:
Code:
    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.

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.
 

Attachments

  • 000_how_to_use_variables_in_script.txt
    4,1 KB · Views: 0
  • effects.log
    181,4 KB · Views: 0
  • localizations.log
    4,4 KB · Views: 0
  • scopes.log
    8,1 KB · Views: 0
  • modifiers.log
    294,3 KB · Views: 0
  • triggers.log
    128,3 KB · Views: 0
  • 60Like
  • 34Love
  • 15
  • 2
  • 1
Reactions:
This is how things should have been going. Neat work indeed.

EDIT: Can there be an official guide on how these stuff affect the game performance, like what should I use sparingly so it doesn't lag as hell, or what can be used recklessly as it involves very little work behind the scene?
 
  • 11Like
Reactions:
All of these changes look great! Especially how the army, fleet and other icons are handled.
I've also wondered, since Plantoid and Fungoid archetypes are recieving unique traits, is it possible that the other archetypes will be able to have their own unqiue traits modded in? (Unless you can already do that and I'm being stupid)
 
All of these changes look great! Especially how the army, fleet and other icons are handled.
I've also wondered, since Plantoid and Fungoid archetypes are recieving unique traits, is it possible that the other archetypes will be able to have their own unqiue traits modded in? (Unless you can already do that and I'm being stupid)
Yes, that's possible now - previously you could lock by archetype, now you can also lock by class. Also, civics can be locked by species class too, now.
 
  • 27Like
  • 6Love
  • 6
Reactions:
I've also wondered, since Plantoid and Fungoid archetypes are recieving unique traits, is it possible that the other archetypes will be able to have their own unqiue traits modded in?

As Caligula said, species traits now support a bunch of new stuff. Here's the list that were implemented when making the Plantoid traits (going by memory):
Code:
species_class = {} # List species classes here, ensuring the corresponding archtype is listed in allowed_archetypes = {  }

triggered_planet_growth_modifier = { # Won't show in trait tooltips, use custom_tooltip/custom_tooltip_with_modifiers
    potential = {  } # Trigger for modifier.
#    pop_growth_speed = value
#    pop_assembly_speed = value
}

triggered_pop_modifier = { # Won't show in trait tooltips, use custom_tooltip/custom_tooltip_with_modifiers
    potential = {  } # Trigger for modifier.
    # Should accept most trait modifiers.   
}

custom_tooltip_with_modifiers = loc_key #  # Unlike custom_tooltip, this shows in addition to the modifiers
 
  • 9Like
  • 6
  • 2Love
Reactions:
The randomness changes seem really positive!

Are there any particular things within the game that were affected by the "fake randomness"? I swear that I have noticed cases before where things in the scripts claimed to be a 30% chance, but I'd see them every single game. I'm just wondering if you know off the top of your head some events that this might have affected?
 
  • 1
Reactions:
Amazing stuff! Can't wait to toy around with this :D

Question about the sprite changes;

Sprite Sheet Changes

<snip>

This got rolled out to the likes of army types, colony automation types, bombardment stances, and (with great difficulty!) ship sizes.

Can this in the future also be applied to planet modifier borders? That is a single sprite too. With how they're used in static modifiers it's probably not an easy thing to do, but doesn't hurt to ask :)
 
E.g. A modifier gives a country +1% energy production. If one adds thecmodifuer to the country again it becomes 2% energy production, etc. (maybe create some (stackable modifier type, to avoid weird bugs with modifiers that are not intended for this).

E.g. I had a modifier which stacked one time for every year of consecutive peace, up to 50 times. Then I had to create 50 separate modifiers and a switch in between (I later skipped it since it was too messy...). It would be cool with an easy way to implement stuff like this.

I though modifiers already worked like this since 3.0? I can't remember clearly though
 
The randomness changes seem really positive!

Are there any particular things within the game that were affected by the "fake randomness"? I swear that I have noticed cases before where things in the scripts claimed to be a 30% chance, but I'd see them every single game. I'm just wondering if you know off the top of your head some events that this might have affected?
L-Gates opening to nanite dragons every time, for example.
 
  • 7Like
Reactions:
Amazing stuff! Can't wait to toy around with this :D

Question about the sprite changes;



Can this in the future also be applied to planet modifier borders? That is a single sprite too. With how they're used in static modifiers it's probably not an easy thing to do, but doesn't hurt to ask :)
Not sure which ones you mean, please say the file :)

Actually, planet classes also got the same treatment, now that I recall. (The bit where you see the planet's picture in the outliner)
 
  • 6
  • 5Like
Reactions:
Not sure which ones you mean, please say the file :)

Actually, planet classes also got the same treatment, now that I recall. (The bit where you see the planet's picture in the outliner)
It's the file Stellaris\gfx\interface\icons\planet_modifiers\modifier_frames.dds

and
Code:
    spriteType = {
        name = "GFX_modifier_frames"
        texturefile = "gfx/interface/icons/planet_modifiers/modifier_frames.dds"
        noOfFrames = 3
    }

in Stellaris\interface\modifiers.gfx



:) In practice, the border you need is referenced in \static_modifiers with "icon_frame =" eg;

compact_star = {
icon = "gfx/interface/icons/planet_modifiers/gpm_compact_star.dds"
icon_frame = 3
}
 
  • 1
Reactions:
Exciting update! I've been looking forward to it for a long time, the inconveniences bothered me many times!
But I want more improvements. “Progress is endless”. For example, for complex calculation, the rule of variable calculation in Stellairs is too... complex. You can't image what I've been going through when I try to write a script that just calculate square root.
Just keep going!