Reminder - in all my tutorials, green text can be skipped by modding vets, and red text can be skipped by beginners. These are side notes meant to clarify something I imagine certain readers will have questions on, and if they are not targeted at your skill level, you can skip them or ignore them if they are over your head or seem obvious.
The Unlock System allows you to trigger new content in response to practically any event with zero coding.
We're talking building plans, craftable items, new weapons, start quests, introduce characters. Virtually anything you can imagine that is possible to happen in Fallout 4 can be dynamically triggered by this system in response to practically any event or gamestate you can imagine.
Want to respond to a quest completing? Supported! Want to respond to the player having a certain set of buildings in their settlement? Supported! Looking to respond to the player destroying the Brotherhood, while wearing the Silver Shroud outfit, with Hancock as their companion, and exactly 4000 mutfruit in their inventory? Supported!
Let's face it. We are all dopamine junkies.
Getting a little reward pop-up, with a pleasant sound effect, and maybe some flashy graphics or animation just feels good.
Of course, it can get tiresome if done too frequently, so while I'm about to show you how to nuts with this system. Be sure to take a look at what the base of SS2 is unlocking, and what other popular addons are triggering when so that you don't overspam the player and make them wish to turn this little drug machine off.
Seriously, setting these up is addictive in itself. It feels too awesome to watch your stuff unlock in game!
Since it's inevitable we'll eventually overdue it, or players will grow tired of it interrupting their gameplay, player controls for when and how these are allowed to appear will be introduced in a future patch.
There are multiple variations on the Unlock form that you define to rig up your unlock (also the code is designed to be easily extended for you papyrus experts!). We'll go over a few of the variations in this document, and the others will be covered in the specific tutorials where they are relevant to that content.
In this guide, we'll walk you through the properties and what they do, and then show you the steps to inject an unlockable into Sim Settlements 2 which will ensure it triggers at the appropriate time.
The Unlock System has a base called Unlockable, you can find the base form by filtering for SS2_Template_Unlockable. All of the extended versions of this include everything that the base does, plus a little extra - we'll start with the base and then cover the extras some of the others add.
Unlockable script properties are broken into 3 groups: Notifications, Requirements, and Triggers.
Notifications handle how to let the player know the unlock occurred. This can include sound effects, message boxes, a featured item, or a combination of all 3. It can also include none if you'd like the unlock to occur silently in the background, which is what we do for our Unlockable Character system in the base of SS2.
- FeaturedItem: This gives the player an item upon unlock. The idea with this is to use the FeaturedItem keyword so that it is presented like most of our unlocks with the model large on screen. You can even point this field to the same form you are setting up these properties on and add the FeaturedItem keyword to it, which is actually what the SS2_Template_UnlockableFeatured was added for. You could also use this field to simply give the player an item by excluding the FeaturedItem keyword on your item, provided you use the bKeepFeaturedItem property as well.
- bKeepFeaturedItem: By default, the FeaturedItem is given to the player simply to trigger that vanilla UI system that shows those models on screen, then SS2 removes that item from inventory. If this property is checked, that last step is skipped and the player can keep the item.
- bPlaySound: When checked, the unlock sound will play. There is a default sound SS2 uses, or if the SoundEffectOverride property is set, that will be played instead.
- SoundEffectOverride: By default, SS2 plays a specific sound on Unlock to try and give a consistent feel, though if you have a particularly unique unlock that you want to stand out, changing the sound could help emphasize that uniqueness - which is what this field does.
- UnlockMessage: When set, this message will be shown after the unlock occurs. If a FeaturedItem is configured, this will be delayed until after that screen is closed. This can be a corner notification message, or a pop-up message.
Requirements determine when a particular unlock should trigger. These include a combination of gamestate checks, and even include a Requirements property to tap into the Usage Requirements Lock System.
You can configure as many different requirements as you like. Once all of them are simultaneously true, the Unlockable will be eligible and will be triggered at the next event that causes an Unlock check in the system.
Some requirements are more immediate than others. For example, things like Quest stage checks are monitored for and can be responded to nearly instantly, whereas things like Global checks will only be caught during the Unlock System's daily check to see if any new unlockables are eligible. So while testing your unlocks, after you are sure you have fulfilled all conditions, you may need to use the passtime console command to ensure the Unlock System tests all of the requirements you have configured.
If you need to guarantee your unlock appears at a specific moment, you will want to use Quest Stages to trigger them, even if it means setting up your own Quest to have a stage you can set. We also have a scripted method to force an Unlock, which will be made available after we release the source for SS2.
- ClearedLocations: This checks that the corresponding Locations have been cleared of enemies. This can hold any number of UniversalForm structures. If you include more than one, all those locations must be cleared.
- iMinOwnedSettlements: The minimum number of settlements the player must control.
- iMinPlayerLevel: The minimum level the player must be.
- MinimumCityPlansAtEachLevel: Each entry you add to this property represents the number of City Plans that should be at that level or higher. So if your first entry is 5, there needs to be at least 5 city plans at level 0 or higher (level 0 = foundation level). If your second entry is 8, at least 8 city plans must be at level 1 or higher, etc. To remember this easily, look at the index column in the property screen for this field and treat this as the level.
- MinimumPlotsActive: This checks that throughout the player's controlled settlements, there are at least this many Active plots (See Plot Status section) matching the settings for each entry. This can hold any number of PlotCount structures. If you include more than one entry, all defined plots must be present and active.
- MinimumPlotsBuilt: This checks that the throughtout the player's controlled settlements, there are at least this many plots matching the settings for each entry. This can hold any number of PlotCount structures. If you include more than one entry, all defined plots must be present. The Status of the plots is not considered.
- MustOwnSettlements: This checks that the player controls these settlements. This can hold any number of UniversalForm structures, these entries should be pointing to the Workbench reference for that settlement which has the WorkshopScript on it. If more than one entry is included, player must control all of those settlements.
- Requirements: Add a UsageRequirements form to have its defined requirements be considered. Note that the OwnerRequirements, PlotRequirements, and SettlementRequirements sections of the UsageRequirements script are not used by this system.
After reading this section, you may be wondering why some of these requirements available to the Unlock System weren't simply added to the Usage Requirements system and made more universal. We will eventually pursue that.
The two systems were designed at very different times of our development cycle for SS2, and it was an oversight to not better combine them. We ran out of time to rectify before release based on the schedule we had set up.
Triggers determine what should happen after the Notifications once the unlock occurs. In SS2, the most common use of this is to register new content with SS2, similar to how your addon configuration is used to do so throughout the various tutorials. Though many other things can be done with this system.
- RegisterForms: This will inject forms into Sim Settlements 2 using the same injection system the addon pack registration does. This can hold any number of FormlistInjection structures, in these, simply fill out the FormToInject and the TargetFormlistKeyword field pointing to one of the keywords prefixed with SS2_FLID_. If more than one entry is included, all will be registered.
Technically, you are not limited to the SS2_FLID_ set of Formlists. You can use literally any formlist for the TargetFormlist field. This means you can use this system to custom inject things into any system in the game, your own mod, or other mods that use Formlists! Which might be useful for those of you trying out advanced things.
Be weary of injecting into SS2's formlists directly, the FLID system was designed to prevent people accidentally injecting things into a list they shouldn't as we have a lot of similarly named lists.
- SetGlobals: This will set Globals to specific values. This can hold any number of GlobalVariableSet structures, for these the corresponding Global will be set to the fValue you enter. If more than one entry is included, all will be set.
- SetQuestStages: This will trigger Quest stages to occur. This can hold any number of QuestStageSet structures, for these the corresponding Quest will have the iStage field triggered. If more than one entry is included, all will be triggered.
One of the most common uses of the Unlock system I anticipate people wanting are to unlock buildings. I recommend for these you use the extended Unlockable form called SS2_Template_UnlockableBuildingPlan (this was added in patch 1.0.1b), which works the same as the base type, except that it has a few extra fields specific to building plans.
When using the UnlockableBuildingPlan type, instead of filling out the Triggers section, use the Settings section.
- BuildingPlan: This should point to the Weapon form that represents your Building Plan.
- iPlotType: See the Documentation String in the Creation Kit when editing this property.
- TargetBuildingPlanList: This should point at the formlist starting with SS2_BuildingPlanList_ that corresponds to the plot type and size your building plan belongs to. For example, if your building plan is for a 3x3 Agricultural plot, use the list SS2_BuildingPlanList_Agricultural_3x3.
Eventually we will be adding support for the FLID system here to make it less likely you select the wrong list - for now, just be sure there is nothing after the size in the formlist name you select. For example, do NOT select SS2_BuildingPlanList_Agricultural_3x3_AddonTemplate, as that won't do anything.
Technically, you can simply use the RegisterForms trigger to inject building plans as well. The advantage to using the UnlockableBuildingPlan and its custom fields instead, is that it will prevent unlocks of building plans for which the player has not yet discovered the corresponding Plot or Building Class type.
Instead, those will be delayed until after the player has unlocked the corresponding types, without you needing to worry about those things in your Requirements!
Something we made a lot of use of in SS2, and would love to see the community engage in more (In fact, I plan on writing tutorials on the future to help with making new settlers - in the meantime, check out my Bethesda Mod School series, and check out the ones with Quest Making and Dialogue in the titles which covers the basics of quest and dialogue, respectively.), is the Unlockable Character system.
In addition, this system will even allow converting NPCs from the base game, DLCs, or other mods into Visitors and/or Settlers! (SS2 does not require the workshopNPCScript on NPCs, so literally any Unique flagged NPC can work with this) Of course, you'll want to be sure to lock their triggers behind whatever quests those characters are involved with so you don't break them.
With this, rather than conditioning based on specific events, your character can appear through our Unique Visitor, or Settler Recruitment systems.
This allows you to introduce a random element to when and where they appear. Your Requirements section ends up defining the earliest moment they show up, and then for characters that are meant to show up at settlements, you can set requirements for settlements they might be able to show up at (for example, you could limit them to only show at settlements with a certain number of Agricultural Plots).
Character Unlocks work in multiple stages:
- The character starts locked and is ineligible to appear in the world.
- Once any Requirements are met, the character is put into an eligible state.
- If a player's settlement triggers one or more Unique Visitors to appear, the Character_SettlementRequirements (you'll read about those shortly) are checked to see if that settlement is elgible for the character to appear, if so, they are queued up for release at which point the appropriate Character_Triggers are fired.
- If the player uses the recruitment service from our main quest line, this can also force trigger a random eligible character to become released and fire it's appropriate Character_Triggers. This character then becomes tracked in a quest to make it easier for the player to find them since the character could end up any eligible settlement, not just the one the player arrive in as they do in the Unique Visitor system.
The form SS2_Template_UnlockableCharacter is where to start for an unlockable character. In addition to the base unlockable fields, you have two additional sections you can configure to custom tailor when your custom character will appear.
This determines which settlements the NPC can appear at. If multiple are eligible, the NPC will be given an AI package to wander between several of them periodically. If nothing is set here, every settlement the player controls become eligible.
All properties you fill out must be true for the settlement for it to be considered an eligible location for a character to appear.
- bBeaconRequired: When checked, only settlements with a recruitment beacon (or Communications class building) are eligible.
- bConsiderAllRequirements: When checked, anything you set up in the Requirements section that could be considered on a per settlement basis will be used here as well. This includes the MinPlotsActive (this many matching active plots must exist at this settlement), MinPlotsBuild (this many matching plots must exist at this settlement), and MustOwnSettlements (these settlements only) properties.
- bPlayerOwnedOnly: When checked, only player controlled settlements are eligible.
- EligibleFactions: Only if the settlement is controled by one of the factions entered here. Faction Control is technically an element of Workshop Framework that no mods are using, but that SS2 will make use of when we eventually port Conqueror forward. This accepts any number of UniversalForm structures.
- fMinHappiness: The settlement must have a happiness score of at least this number. (In SS2, we frequently used this field to delay characters that were more "high society", as they would have felt out of place in an extremely barren settlement, and happiness tends to be a decent proxy for a successful and filled out settlement most of the time)
- IneligibleFactions: The settlement will NOT be considered if it is controled by one of the factions entered here. Faction Control is technically an element of Workshop Framework that no mods are using, but that SS2 will make use of when we eventually port Conqueror forward. This accepts any number of UniversalForm structures.
- LimitToSettlementsInWorldspaces: The settlement must be in one of these Worldspaces to be eligible. This is a good way to limit NPCs to the Commonwealth, or a certain DLC area. This accepts any number of UniversalForm structures.
- NormalSettlementsAllowed: When checked, settlements that are NOT Outposts and NOT Vassals from the NukaWorld system (and eventually the Conqueror system) are eligible.
- OutpostsAllowed: When checked, settlements that are flagged as Outposts from the ukaWorld system (and eventually the Conqueror system) are eligible.
- VassalsAllowed: When checked, settlements that are flagged as Vassals from the ukaWorld system (and eventually the Conqueror system) are eligible.
This section allows for having characters appear in various ways, or even manipulating the way the Triggers section functions. It also includes a few fields that are used by our systems that must be filled out (these will be in red in the CK).
- bCanBeRecruited: When true, this allows the character to be used as part of the Settler Recruitment systems, otherwise they will only be useable by the Unique Visitor system. If your goal is to have a character who appears, but does not become a settler eventually, you should uncheck this box.
- bDelayNormalUnlockTriggersUntilReleased: When true, the Triggers section is not handled until after the character is released. Otheriwse, the Triggers section will occur as soon as the character is eligible to be released.
- bEnableCharacter: When true, the character will be enabled if they were placed in the world disabled. This can be a good way to handle characters you want appearing in specific locations of the world as opposed to being sent to settlements.
- bHandleSpawning: When true, this will spawn a copy of the CharacterForm property. This should only be used if you didn't place them in the world somewhere already.
- bMakeASettler: When true, instead of being treated as a Visitor, the NPC will immediately be made a settler at the first eligible settlement they are released too.
- bMustHandleImmediately: When true, this character will always jump the queue created by the Unique Visitor system and be released as soon as they are flagged as eligible.
- bSendCharacterToSettlement: While throughout this section, I've spoken as if all characters are sent to a settlement automatically, that can actually be disabled to allow the character to hang out wherever you want them to (through AI packages). To do so, uncheck this box. This is used well with bEnableCharacter. (See BenniStrong for an example from SS2 of using these two flags like this)
- CharacterForm: This should point to the ActorBase record of the NPC this unlockable is for. Note that this system requires a Unique flagged actor! The field accepts a UniversalForm structures.
- iPrimaryStatIndex: See the Documentation String of this property in the CK for how to fill it out. Effectively, you're telling SS2's Recruitment system which SPECIAL stat of the character should be considered most important as the Recruitment system allows the player to choose that when deciding what kind of person they are after.
- TrackAliasInsteadOfCharacter: When tracked through the Recruitment system, this alias will be used instead of the Character themselves. This is useful if you want to lead them to a clue, or quest chain, instead of the final character. This alias can be pointing to literally anything in the game, but you have to set up the quest yourself to manage the alias (for more info on Aliases, check out the Quest Making videos in my Bethesda Mod School series on Youtube OR you can use the next property instead!) For an example of this in SS2, check out the character FishFood.
- TrackRefInsteadOfCharacter: Same as the TrackAliasInsteadOfCharacter, except that you can point it directly at the object reference in the gameworld, without needing to rig up a quest alias. (The downside to this method is that references kept in scripts are persisted in memory forever, but used sparingly, that's not a big deal.)
Once you've decided on what you want to unlock, find the appropriate SS2_Template_Unlockable under Items > MiscItem, duplicate it, and edit your copy. Use the information in the above sections to fill out the script properties.
Beyond the script properties, the only reason you need to fill out the rest of the form, is if you are using it as the FeaturedItem, which is something we commonly do in SS2. In that case, you'll want to be sure to fill out the following fields on the form itself:
- Name: This will display at the top of the Featured Item UI.
- Preview Transform: This helps to ensure the model is centered. (Preview Transforms are beyond the scope of this tutorial, but to point you in the right direction, you can create your own under Miscellaneous > Transform, and use the Preview Object dropdown to use your model directly for figuring out the positioning).
- Featured Item Message: This is an optional field to show additional information below the name on the Featured Item UI. You can create new messages for this under Miscellaneous > Message. See our SS2_FeaturedMessage_ message forms for examples of how to fill those out.
- Keywords: Be sure the FeaturedItem keyword is on your record.
- Model: Point this to the model you want to show the player.
Once your Unlockable records are created, you need to register with them the Unlock system of Sim Settlements 2.
- In the Object Window, filter for SS2_Unlockables_AddonTemplate under Miscellaneous > FormList. Right-click and duplicate it, then double-click your copy.
- Change the ID field to something like yourPrefix_Unlockables.
- Leave the first entry in place, that keyword always needs to be the first entry, and then drag the title bar of the formlist window off to the side.
- In the Object Window, filter for your unlockables under Items > MiscItem, then drag them onto the formlist. Then press OK to close the formlist, answering No to creating new, and Yes to rename.
- In the Object Window, filter for your addon config under Items > MiscItem and double-click it to open it, then double-click the script on it to bring up the Script Properties screen.
If this is your first time working on an addon, or you haven't created addon configuration data yet, check out this tutorial).
- Double-click the property MyItems, then click Add on the far right and find the formlist you created in step 1.
Your Unlockables should be registered shortly after booting up the game, and if you've loaded into a save with the criteria already met, it should trigger the unlock shortly after loading (if not, try the passtime 24 console command).
To fully test in game, you'll need to play the game until the gamestate matches the Requirements section of your Unlockable.
Another way you can approach this, is to set up your Notifications and Triggers first with no Requirements, so that they will automatically trigger right away when loading your game so you can confirm those portions work how you want them to and quickly test again after each tweak. Then once you're satisfied with those portions, add in the Requirements and test that they work how you expect.
There are other possibilities with this system beyond what we've covered here thanks to the extendable nature of the script. Several are documented in other areas, such as the Discovery System, we've also emulated this system for our Newspaper and Magazine printing buildings (you'll learn about those in the corresponding tutorials).
So keep reading through the tutorials for more ideas of how you can trigger your content through SS2!