Print

Please login or register.
1 Hour 1 Day 1 Week 1 Month Forever
Login with username, password and session length

[Thaago]

Hi everyone. As part of getting back into modding SS I’ve decided to write up tutorials of what I’m doing. The mod is attached in this post and does one small thing: it adds a menu option to all planets that have markets that will change their allegiance to the Hegemony. Going through the mod should teach the basics of how the rules.csv system works, how to write a script that is called from rules.csv, and what the basic structure of markets is in SS.
 
Full disclosure: the script that changes the faction is heavily based on (ie only mildly edited to remove extra parts) code from Nexelerin, which I’m studying to learn how to do things. So thanks to Histidine, Zaphide before him, and the rest of the mod mafia for creating excellent mods for me to pore over and learn from.


Here is the first Tutorial: Tutorial #1!


Questions, comments, and requests are welcome.

[attachment deleted by admin]

[Ryxsen1421]

Thanks for sharing your techniques. I'll be sure to check it up and hopefully know a thing or two at the end.

[Morrokain]

Hey I was just coming here to get some info on rules.csv. Thanks!

Finally ready to dive into those waters!

EZ faction has all my factions in the campaign but in order for their backstory to be authentic and immersive I have to break into rules.csv for custom interactions and flavor dialogue.

Question:

Is is informative enough that I will be able to understand how to connect custom defined entities to the economy as a market? I am still getting a gauge on how many markets I can realistically add, but I want at least a couple directly inserted into the core worlds and they will have to be tied to the economy there.

[toast]

Very much appreciate the tutorial -- it was a big help getting started with modding.  Thanks!

[Morrokain]

Had some time to go through this and thanks a ton for taking the time to write this up and create the mod! Its well-written, concise and provides an easy way to get started with rules that doesn't completely overwhelm you with all you can do. 


Triggers seem pretty self-explanatory, but for specific conditions, am I right in what I read that there isn't any documentation other than the file itself for examples (and your mod of course)?

So if I wanted a list of the various ways you can structure conditions I just need to find something in the rules file that does something similar to what I want?

Sorry if this seems like a silly question, but looking to see if I can compare variables already present in the engine (as referenced in the API) or if 'conditions' are only predetermined booleans with presets already defined in rules itself.

I know I could probably for sure do this in the script itself too, but I'm not sure how efficient that would be compared to a condition check in rules.

[Thaago]

I didn't notice this a few days ago! Thanks for the replies .

Thanks for sharing your techniques. I'll be sure to check it up and hopefully know a thing or two at the end.

You're very welcome!

Hey I was just coming here to get some info on rules.csv. Thanks!

Finally ready to dive into those waters!

EZ faction has all my factions in the campaign but in order for their backstory to be authentic and immersive I have to break into rules.csv for custom interactions and flavor dialogue.

Question:

Is is informative enough that I will be able to understand how to connect custom defined entities to the economy as a market? I am still getting a gauge on how many markets I can realistically add, but I want at least a couple directly inserted into the core worlds and they will have to be tied to the economy there.

You know I'm not entirely sure - this example switches a market but there might be some initial setup I'm not aware of. I would check some of the mods that add a system - those probably have what you want. Still, I'll look around, and maybe put this in the next one .

Very much appreciate the tutorial -- it was a big help getting started with modding.  Thanks!

You're very welcome! I'm glad it helped.

Had some time to go through this and thanks a ton for taking the time to write this up and create the mod! Its well-written, concise and provides an easy way to get started with rules that doesn't completely overwhelm you with all you can do. 


Triggers seem pretty self-explanatory, but for specific conditions, am I right in what I read that there isn't any documentation other than the file itself for examples (and your mod of course)?

So if I wanted a list of the various ways you can structure conditions I just need to find something in the rules file that does something similar to what I want?

Unfortunately yes - the 'base' triggers aren't really documented and to be honest I don't know if they will be stable in the future. The good news is that the base game rules.csv is relatively straightforward - I open it in excel and search for terms like 'market' etc. What I'm planning on doing is hooking my rules into triggers at an early level (like populate all in this example) and then making the rest of the sub-menus run on my own custom triggers.

Sorry if this seems like a silly question, but looking to see if I can compare variables already present in the engine (as referenced in the API) or if 'conditions' are only predetermined booleans with presets already defined in rules itself.

I know I could probably for sure do this in the script itself too, but I'm not sure how efficient that would be compared to a condition check in rules.

Not a silly question at all: You can as long as the variable in question is stored in the memory map that rules.csv can access - but most of the data in the main SS api is not available that way. You could in another script store these variables yourself for later use - say a setup script that uses the API to get values not defined in the rules memory map by default and saves them to $Global.Modname.data1... (Uhh, wait, I don't know if the sub-dot notation works. Probably safer to use $Global.ModnameData1 or similar).

To find what values are available in vanilla takes a bit of work but isn't too bad: If you enable dev mode (in starsector-core/data/config/settings.json) and go to any menu you have the option to 'dump memory' - this will give back a giant list with all of the memory that rules.csv has access to.

For example, if I fly to Tibicena the local entries (there's a set for every key in memkeys - the local ones have no prefix) are:


If you wanted your menu option to, for example, only be available when there is market, it is friendly, and stability is high, you could write:

$hasMarket
!$isHostile
$stability >= 7

In the condition line (and yes, you need new lines between the conditions, which is why a spreadsheet editor like excel is super handy even though something like N++ is usually better).

I hope that helps.

[Morrokain]

I hope that helps.

Very much so! Thanks again!

I wanted to add a bit to this too:

So, as it turns out, from reading Alex's documentation: http://fractalsoftworks.com/forum/index.php?topic=8355.0

You can actually make your own custom triggers and conditions calling whatever variables you want, so you aren't limited by which ones currently exist.


New custom Triggers can be called by any string representing an id, then defined using a plugin (not as clear as for conditions but I believe this is the case if you kind of read between the lines a bit)

These ones:

Spoiler

OpenInteractionDialog ­ fired when a dialog is first opened  
DialogOptionSelected ­ fired when a dialog option is selected  
BeginFleetEncounter ­ fired when the fleet interaction dialog is opened  
OpenCommLink ­ fired when the player opens a comm link (whether during a fleet encounter, or elsewhere)

[close]

are just the hardcoded ones.

For conditions, you can add variables to the memory map accessible by rules through a campaign plugin that utilizes methods to manually update the variables ("facts") there.

[Thaago]

Yup! You don't even need a plugin; it can be done directly from the csv. For example if in the script column you write "FireBest MyCustomTrigger" it will look through and find "MyCustomTrigger" in the triggers column and evaluate it.

Variables can be edited in the scripts column without a standalone script as well, but I don't know if the conditions will throw an error if a variable is undefined when its checked, so it might not be wise to do so by itself. Or have a "on new game" function in the ModPLugin that populates whatever variables are needed to make sure not to get errors.

[Alex]

No errors if variables aren't initialized, btw.

[Thaago]

No errors if variables aren't initialized, btw.

Gotcha - do they evaluate to false then?

[Alex]

False, 0, and empty string, respectively.

[Morrokain]

Ah ok good to know! Are variable names case sensitive?

I only ask because there is reference to both $personRank and $PersonRank in seemingly identical contexts.

[Alex]

They're case-sensitive, yes. When you see these kinds of case differences, it's indicative of whether the first letter in the variable is capitalized, but that's just an internal convention, not anything hardcoded. So you'd use one vs the other depending on whether it's the beginning of a sentence or not.

For example, if you look in
com.fs.starfarer.api.impl.campaign.CoreRuleTokenReplacementGeneratorImpl

You'll see $personRank and $PersonRank being set. Note that those aren't actually variables, but tokens only used for text replacement.

Variables can be used in text as well, though. See: CoreCampaignPluginImpl for the "standard" variables being defined, i.e. aside from ones defined in the rules themselves or in rule commands.

(Generally speaking, if I was modding rules, I wouldn't mess with the text-only-tokens and would just use variables. The tokens are a holdover from a point in the implementation where variables could not be used in text like that, iirc.)

[Morrokain]

com.fs.starfarer.api.impl.campaign.CoreRuleTokenReplacementGeneratorImpl

You'll see $personRank and $PersonRank being set. Note that those aren't actually variables, but tokens only used for text replacement.

Variables can be used in text as well, though. See: CoreCampaignPluginImpl for the "standard" variables being defined, i.e. aside from ones defined in the rules themselves or in rule commands.

(Generally speaking, if I was modding rules, I wouldn't mess with the text-only-tokens and would just use variables. The tokens are a holdover from a point in the implementation where variables could not be used in text like that, iirc.)

Phew glad I asked then if tokens (what I HAD in fact been using) will soon be unstable. haha 

Thanks for the path to the definitions too!

[Morrokain]

Hm ok, so in regards to using variables instead of tokens, that works pretty well until I need a $heOrShe token or a &shipOrFleet token.

I can't see anything that would replace these in CoreCampaignPluginImpl

Will these, at least, be relatively stable in the future?


Also I'm surprised $player.name isn't a variable and you still have to use a $playerName token when $local.name and $local.rank work just fine to replace $personName and $personRank respectively.

Is there a $global.playerName or something that I just missed?.. hmm come to think of it, may try that one.

**edit**

Nope, that one doesn't work either. Token it is for now.