¶ Intro
Sim Settlements 2 includes a powerful conditioning system using objects called Usage Requirements forms. These allow for controlling availability based on a variety of events or game states, such as quest completions, plot counts, settlement leaders, etc.
Virtually anything that can happen in a player's game can be used as a requirement, or be used as a pre-requisite for something to work or appear in Sim Settlements 2 - all without any scripting required by you!
In addition to the UsageRequirements object, there is also an Unlock System which provides even more custom event driven behavior. So if this section doesn't cover what you're after, check out the Unlock System documentation.
On top of this system giving you a ton of power and flexibility without any scripting, it's heavily re-useable. Once a UsageRequirements object is established, it can be used to trigger multiple things or be duplicated and edited to nest a variety of requirements.
For example, a common event that people want to respond to, or make a requirement, is the appearance of the Brotherhood of Steel. It's silly for you guys to each individually be researching how to determine that, so we've set up the the UsageRequirements object SS2_UsageRequirements_PrydwenArrived, which can be used by any system in SS2 with a UsageRequirements property.
We've set up tons of UsageRequirements objects that you can make use of to cover major events in Fallout 4.
¶ Basic Technical Info
If you haven't done much Papyrus scripting, skip this section!
At it's core, the system is simply evaluating whether or not everything defined on the UsageRequirements form is true. If yes, SS2 will use that entry, if no, SS2 will skip it.
This is done through a function called CheckRequirements (SimSettlementsV2:UtilityFunctions.CheckRequirements) which will accept a form with the UsageRequirements script, as well as optional parameters for a plot, actor, and settlement workshop, if any of those apply in that situation. All of the properties that are filled out on the UsageRequirements form are then evaluated, and if everything is true, the CheckRequirements function returns true, otherwise it returns false.
Each UsageRequirements object can have virtually unlimited requirements defined, and the content will only be available when ALL of the requirements are true, giving you incredible fine-tune control about when you want your content to be available.
Yes, you can use this in your own code! We will eventually make the source of SS2 public so that you can more easily tap into this system yourself. For now, here's the definition of this function which you would call via SimSettlementsV2:UtilityFunctions.CheckRequirements
Bool Function CheckRequirements(SimSettlementsV2:MiscObjects:UsageRequirements akRequirements, SimSettlementsV2:ObjectReferences:SimPlot akPlotRef = None, ObjectReference akOwnerRef = None, WorkshopScript akWorkshopRef = None)
¶ Where Can I Use It
Throughout SS2, you will find script properties called Requirements, UsageRequirements, or something similar. These will have a Documentation Screen mentioning SimSettlementsV2:MiscObjects:UsageRequirements, anywhere you find this, you can use this system to control when or whether the thing you are configuring should be used.
The most common uses are for unlocking new things, like Building Plans, craftable items, newspaper articles, etc. You'll also find it in more granular things, such as controlling whether a particular item spawns on a building plan, or where a particular construction cost should be used.
In the future, we will continue to look for additional use-cases to give you more unscripted means of tieing your content to gameplay!
¶ UsageRequirements Forms
UsageRequirements are stored as simple MiscItem records that are completely blank and just hold a script. You can duplicate the SS2_Template_UsageRequirements form to get started with a new one, and you'll see it leaves every field blank. These objects will never appear in the world, they are simply used to hold some information that you configure on the script properties.
At the time of this writing, the script properties are broken into 4 sections: OwnerRequirements, PlotRequirements, SettlementRequirements, and Ungrouped Properties (that last group will very well receive a name in some future update).
The Ungrouped Properties work in a universally applicable way, whereas each of the Owner/Plot/Settlement sections are configured similarly, but is applied in a context sensitive way. Below, I'll describe the most common way each is used, once you understand these common methodologies, exceptions should start to feel intuitive.
Any exceptions that manipulate the system in an unintuitive way will be explicitly documented in the corresponding Documentation String on the script property asking for a UsageRequirements form.
Each of these sections will continue to be expanded in the future to give you more power. If you ever find something you'd like to condition to that appears to be impossible with the current properties, definitely reach out to me to suggest expansions to this system!
¶ QuestRequirements
This is the most common way to react to events that occur in the player's game. It works by checking whether or not a particular stage has occurred on a quest.
This is one of the more user-friendly ones to work with as well, since you can learn about what stages of a quest represent what event in game by looking at websites like fallout.fandom.com/wiki which have sections detailing what each quest stage represents.
¶ Property Breakdown
The QuestRequirements property allows for any number of QuestStageSet structures to be included. If you include more than one entry, ALL of them must be true before the QuestRequirements property will evaluate to true.
- bNotDoneCheck: Changes the check from looking to see if the stage has happened, to checking that the stage has NOT occurred.
- iStage: The actual stage on the quest to check.
- QuestForm: The quest to check the stage of. (Use this OR iFormID/sPluginName, not both).
- [Advanced Use Only] iFormID: Hex ID of the quest converted to an integer.
- [Advanced Use Only] sPluginName: Plugin filename the quest can be found.
¶ GlobalRequirements
This checks the value of Global forms to see if they meet certain criteria.
There are many Global variables used by the base game to mark certain events. For example, there is a series of "PlayerKnows" globals that are set when the player first encounters various creatures and factions, which can help with immersively conditioning things.
This is also a good way for you scripters out there to arrange for complete control over a requirement as you can point something at your own Global form which you set with your script in response to anything you want.
¶ Property Breakdown
The GlobalRequirements property allows for any number of GlobalVariableSet structures to be included. If you include more than one entry, ALL of them must be true before the GlobalRequirements property will evaluate to true.
The OwnerRequirements, PlotRequirements, and SettlementRequirements, are fairly advanced and require some underlying knowledge of how the game functions. Don't be surprised if these are difficult to use without specific guidance.
If you think these would work well for what you have in mind, but are uncertain how to approach them, start by digging through some of the SS2_UsageRequirements MiscItem records to find examples to learn from. You can also ask on our Discord server, where many fellow add-on authors will be working together to push this system to extremes!
¶ PluginRequirements
This field checks if certain plugins are enabled for the player. It is used to put a soft requirement on particular content, without needing to parent a lot of DLC or other mods to yours.
¶ Property Breakdown
- PluginName: Filename of the plugin to check for.
Some mods are released with multiple versions having different file extensions. Particularly on nexusmods.com where users tend to want more fine-tune control over their installations. You will occasionally find optional files with things listed like "ESL Version", or "ESL Flagged ESP". This property is designed to handle those cases.
The below flags are only used if you exclude the file extension in the PluginName field. For example, if a plugin named SuperDuperDeathclaws.esp also has a SuperDuperDeathclaws.esl version available, you would enter SuperDuperDeathclaws as the PluginName, and check in the ESL and ESP boxes.
- bAvailableAsESL: An ESL version of this plugin exists.
- bAvailableAsESP: An ESM version of this plugin exists.
- bAvailableAsESM: An ESP version of this plugin exists.
¶ OwnerRequirements
This is used whenever the content in question involves something with a specific actor in control. The most common places this was designed with in mind were plots and settlement leaders. Where this could be used to ensure only specific NPCs being in a certain role would cause something to happen.
For example, perhaps you want to set up a special plot item on a building plan that only appears if someone with Strength greater than 8 is assigned. Or perhaps you want a City Plan to only be available when a Robot settler is the leader.
In some cases, things can look to the owner of a related plot. For example, the Location Discovery system, which allows for Caravans to discover new things while searching for resources via the Mark 1 Beacon gameplay, in this case the OwnerRequirements section applies to the particular Caravan Services worker that was sent to retrieve things.
¶ Property Breakdown
- bIgnoreOwnerRequirementsIfNoOwner: If this is set to true, and no owner is found all of the other checks in this system will be skipped and the entire section will be evaluated to true.
- OwnerAVRequirements: This checks that the corresponding actor has AV values matching these settings. This can hold any number of ActorValueSet structures. If you include more than one, all of them must evaluate to true before this property evaluates to true.
- OwnerKeywordRequirements: This checks that the corresponding actor has these Keywords applied. This can hold any number of UniversalForm structures. If you include more than one, the actor must have all of the Keywords.
- OwnerKeywordRestrictions: This checks that the corresponding actor does NOT have these Keywords applied. This can hold any number of UniversalForm structures. If you include more than one, the actor must have none of the Keywords.
¶ PlotRequirements
This section is more particular in design, and is therefore used less than some of the other sections. It applies when a particular plot would be involved. These are checking that a plot has a particular characteristic about it, such as a specific building class keyword applied, or an ActorValue set.
Using this generally requires a fairly deep understanding of the code that runs the plots, and so it is anticipated this section will only be useful for advanced users.
¶ Property Breakdown
- PlotAVRequirements: This checks that the corresponding plot has AV values matching these settings. This can hold any number of ActorValueSet structures. If you include more than one, all of them must evaluate to true before this property evaluates to true.
- PlotKeywordRequirements: This checks that the corresponding actor has these Keywords applied. This can hold any number of UniversalForm structures. If you include more than one, the plot must have all of the Keywords.
- PlotKeywordRestrictions: This checks that the corresponding plot does NOT have these Keywords applied. This can hold any number of UniversalForm structures. If you include more than one, the plot must have none of the Keywords.
¶ SettlementRequirements
This allows for limiting to settlements with specific characteristics, which includes checking on core characteristics, such as whether its an Interior settlement, what state the settlement is in such as its current happiness level, and even advanced checks such as querying SS2 for specific script variable values - like what level the City Plan is at.
¶ Property Breakdown
- SettlementAVRequirements: This checks that the corresponding settlement workbench has AV values matching these settings. This can hold any number of ActorValueSet structures. If you include more than one, all of them must evaluate to true before this property evaluates to true.
- SettlementKeywordRequirements: This checks that the corresponding settlement workbench has these Keywords applied. This can hold any number of UniversalForm structures. If you include more than one, the settlement workbench must have all of the Keywords.
- SettlementKeywordRestrictions: This checks that the corresponding settlement workbench does NOT have these Keywords applied. This can hold any number of UniversalForm structures. If you include more than one, the settlement workbench must have none of the Keywords.
- [Advanced Use Only] SettlementDataRequirements: This is an extremely powerful and complex option designed to be used by people who have a good papyrus background. It will require viewing the source of Sim Settlements 2 to make full use of. SS2 uses a data storage reference for each settlement, this property allows for evaluating the value of script properties on those references. This can hold any number of ScriptPropertySet structures, note that the CheckForm will always be sent as the SS2 Data Storage ref, and should be left blank in your structure. If you include more than one, all of them must evaluate to true before this property evaluates to true.
- [Advanced Use Only] SettlementWorkshopRequirements: This is an extremely powerful and complex option designed to be used by people who have a good papyrus background. It will require analyzing the WorkshopScript.psc file from WorkshopFramework. This property allows for evaluating the value of script properties on the settlement workbench, which represents the settlement itself. This can hold any number of ScriptPropertySet structures, note that the CheckForm will always be sent as the settlement workbench ref, and should be left blank in your structure. If you include more than one, all of them must evaluate to true before this property evaluates to true.