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.
¶ Intro
The World Repopulation system brings the world outside to life as the player successfully builds up settlements! This system is very addon friendly allowing you to add your own custom designs to the mix.
You can even combine these with the Unlock System to tie your designs to specific events happening for the player, such as completing quests, or reaching certain settlement milestones!
In addition to designing your own interiors that can be injected in the system, if you want to help expand the system, this guide also includes sections for designing new templates, and planting additional door spawn points in the world!
¶ How it All Works
Before starting on building new interiors, you should probably understand how the system works to help you figure out what you may want to build first.
Throughout the game world* we've placed invisible markers at the doorways of various buildings that are otherwise just closed models you can't explore. On their own, these markers do nothing, but as the player gains surplus resources in their nearby settlements** they'll share them with the surrounding areas causing doorways to appear at these markers.
*At launch we focused on Concord as the primary area to plant these doors as a test bed. Overtime we'll expand this throughout the Commonwealth.
In addition, this system can be brought to other Worldspaces by add-ons! (Check out the Adding More Doors section below if this is something you're interested in pursuing)
**To share excess Food and Water with the surrounding areas, settlements must be in a Caravan Services network, ie. they must have a Municipal plot with a Caravan Services building and be connected to at least one other settlement that also has one. Excess power can also be shared via the Municipal Power Transfer buildings.
The doors will be partnered with a unique interior cell registered to the World Repopulation system that matches the shape of the building. Then an appropriate number of settlers will move into the cell and occasionally even sandbox outside in the world near their door. Each night, the settlers will come home and lock their door.
The settler auto-move in can be disabled for any Interior! Which means you could plant your own custom NPCs, or even have none (perhaps you want to use it to make a dynamically spawning dungeon!?). As can the time the inhabitants treat as night, and a bunch of other settings that will likely be expanded over time - the section The WRCell Record will go over the details.
Since many buildings throughout the gameworld use the exact same building structure size (and therefore share template matching in our system), the interiors can end up paired with different doors each playthrough. Combine that with the unlimited possibilities of addons - and every player's game should evolve differently with this system!
¶ Building a New Interior
A New Cell for this system can technically be anything at all, with the only real expectations: an XMarkerHeading that the player and NPCs can be teleported to when they enter, and an actual door they exit.
Ideally, each new cell will match the size, shape, and design of the building it’s designed to emulate. To help speed up the process, we’ve create some templates for a handful of the building models Bethesda used most in the gameworld, though anyone can make a complete custom cell from scratch - and they can even add more keywords and doors in the world (though optimally, we’ll keep all of the keywords and doors in the SS2 plugin, so that every mod injecting into this system can work together).
The template cells start with SS2WRCellTemplate. Simply right-click on one and choose Duplicate to create your own copy, you can then rename the cell by clicking the name once to highlight it, and then again to allow the text to be edited (not actually double-clicking, which just opens it).
From there, you can edit your copy however you like, there are no sacred items in this, though player expectation will be that it roughly matches the building’s exterior. You can even change the door, and SS2 will ensure the Door that is spawned in the outside world matches.
¶ Registering with SS2 (WRCell Records)
Once you’re happy with your design, you need to register it with SS2.
To start, you’ll define a MiscObject that contains all of the data about your Cell. You can duplicate the SS2_C2_Template_WRCell to get started, and rename it. The naming scheme we follow is: SS2_C2_WRCell__. For example: SS2_C2_WRCell_Bld01FreeBrickRes01_Generic01.
Open the MiscObject and give it a name in the Name field, this will help you find it in game through console commands for testing, and will show up in-game to players so they can reference your cell by a name.
After filling out the name field, you’ll find a script you can edit the properties on to set it up how you want. Below are how all the properties work, with the important ones in blue text.
CellTemplateKeyword: This is the keyword used to match your cell with the appropriate door markers. The available keywords start with SS2_WRCellTemplate_, and the rest of the name will match the model of the building, which is also used in the name of the cell you duplicated if you started with a template cell.
DoorOffsetsFromController: This will ensure that whatever door you set up as the exit can be correctly placed in the outside world as well so that they line up correctly.
To figure out how to fill out this field, hide all your items in the cell using the Layers panel, then place the Door SS2_C2_WR_DoorController in your cell at 0/0/0, with no rotation. Then place a copy of the door model you used for your exit door on top of it and line it up as best as you can, then enter the position X/Y/Z and rotation X/Y/Z values here, in that exact order. After you’ve finished, you should delete that DoorController and the extra door copy you added.
EntryMarker: This should point to an XMarkerHeading static that you place just inside the entrance door - it represents where the player and NPCs will be placed when they use the door in the outside world.
ExitDoor: This should point to the door players should use to exit the cell, presumably the one by the EntryMarker. (This system does not currently support multiple entrances/exits, but that may be added in the future.)
ExteriorDoorDecorations: This can be used to have the door in the outside world, or the area surrounding it, have additional items added. For example, this could attach signs, decorations, or lighting. This can be tricky to use, since you won’t necessarily know which specific location your cell ended up attached to a door. So best practice would be to keep things touching the door.
To set this up easily and figure out the coordinates you should enter. You can use a similar trick for filling out DoorOffsetsFromController. Make a new layer and Make it Active, and then duplicate your door where it stands, and change it’s position to 0/0/0. Now decorate what would be the side facing outward, and use the position data of those items to fill out this field.
bAutoMoveOwnersOutsideOccasionally: This is true by default, and causes the system to periodically have the owners of the cell move out into the world and sandbox nearby.
bAutoReturnOwnersHomeAtNight: This is true by default, and will return all of the owners of the cell to it during night hours, which can actually be defined in these properties as well if you want to create some people who prefer to be out at night, or only during very specific hours of the day.
bItemsOwnedByNPCs: This is true by default, and will flag any loose items, and furniture as owned by the NPCs. This will ensure the player has to treat it like someone’s home in the game and deal with theft consequences.
bLockDoorAtNight: This will lock the door in the world during night hours (these can be defined in other properties).
sVendorID: This can be set to an ID representing the vendor type you’d like the residents to act as. The property description will detail how to fill this out.
iShopKeeperLevel: 1, 2, or 3 corresponding to the level of inventory a corresponding settlement vendor would have.
bMakeOwnersActAsMerchants: This defaults to true and will ensure the NPC gets the appropriate factions and keywords to trigger vanilla dialogue for shopkeepers.
bMakeClinicADoctor: If the sVendorID is 4 (ie. our code for Clinic), this NPC will be given not only clinic inventory, but also doctor services.
bSpecificOwnersUseDefaultAI: If the SpecificOwners field is set, this field will give those NPCs an AI package that makes them hang out in the cell and occasionally just outside, depending on the bAutoMoveOwnersOutsideOccasionally. Effectively, this setting allows you to create some custom NPCs to live in your cell, without you having to worry about programming AI for them - they will simply behave the same as the dynamically generated NPCs (from a sandboxing perspective, this doesn’t prevent you from making them custom dialogue or using them in quests).
fNightHourStart and fNightHourEnd: These default to 11 PM (2300) and 8 AM (0800), respectively, and determine both when NPCs will return home if bAutoReturnOwnersHomeAtNight is set, and the hours the door is locked if bLockDoorAtNight is set. It may be used for additional features in the future as well.
iPopulationSupported: Defaults to 1. If SpecificOwners are not specified, this is the number of dynamic NPCs will be spawned to live in this cell (that’s not to say these cells have to be homes, but the default AI package for this system will have these NPCs spend all of their time in them).
SpecificOwners: If set, any number of NPCs you point this field at will be treated as the owners of the cell, and no dynamic settlers will be spawned to live in it.
bMustHandleImmediately: If using this cell in tandem with SS2’s Unlock system, this flag will ensure the cell gets paired to a door immediately (assuming an unused, matching door is available). Otherwise, it will wait in the queue for when appropriate gameplay mechanics have been met for a corresponding doorway - which is the default behavior.
¶ Shopkeeper Support
In patch 3.2.1, we added support for making the residents Shopkeepers (or Vendors as referred to in code). In addition to the above new properties related to this, there's another element to discuss here: animation markers.
In order to make shopkeepers useful to the player, they need to not wander around everywhere and should stay inside their shops. To that end, a new AI package was added that makes NPCs spawned in a cell with the sVendorID field prefer markers that have a new keyword we added: SS2_Tag_WorldRepopVendorMarker.
You can simply clone any existing Furnitrue reference and add that keyword to your copy, and place those new forms in your cell. The NPCs will now stick to those as much as possible.
We included one we anticipate most folks would want: SS2_WorldRepopVendorMarker_StandCounter. If you were to just place that one at your counter, the NPC would generally stay that during all of their daytime hours!
¶ Location Preferences Section
There are a series of options that allow you to have some amount of control over which doors this cell will pair up with, beyond just having a matching building keyword. Cells with preferences are always paired first to ensure the matching doors aren’t used up by cells that can be paired with a larger variety of locations.
LocationKeywordsRequired: Only doors in locations where the location has all of these keywords applied to it. Most locations have a variety of keywords on them that indicate their setting, region, and type of enemies that inhabit the area. (Locations can also have keyword data set at runtime which can also be read by this system so that they can be used in tandem with more advanced systems).
PreferredLocations: If set, this Cell will only ever be paired with Doors in one of these locations.
PreferredDoors: This allows pointing to specific invisible door markers, the cell will then only ever be paired to one of those doors.
bOnlyUsePreferred: Defaults to true. If PreferredDoors or PreferredLocations are set, this cell will not be used except with a door matching one of those properties. In other words, the cell will wait until one of those becomes available, rather than being used at the first door with a matching keyword. If set to false, it means this cell can also be paired to any matching door.
¶ Injecting Your Interiors
Once your WRCell records are created, you need to register with them with Sim Settlements 2.
- In the Object Window, filter for SS2_C2_WRCells_AddonTemplate under Miscellaneous > FormList. Right-click and duplicate it, then double-click your copy.
- Change the ID field to something like yourPrefix_WRCells.
- 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 WRCells 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.
Once your content is registered with SS2, its time to test!
To speed up testing, there’s a console command you can use to immediately pair your cell with a door, and teleport you in front of it so you can enter and see your cell.
Head to an area with a lot of buildings setup for the system, such as Concord, then run:
cqf SS2_C2_WorldRepopulationManager TestCell X
Where X is an 8 digit ID made up of the two load order hex digits of your plugin, and the last 6 digits of the form ID of your misc object. To help find this, if you fill out the name field of your misc object, you can search for it in the console by running: help “NAME” 4 misc (with NAME being part of the name you typed in that field). This will search the game for records and reveal the full 8 digit ID you need to use.
If the system found a door with a matching template keyword to pair to, you'll be teleported right in front of it.
If not, you'll need to find a location that has such a door. You can right-click on the the template keyword you used in the Object Window under Miscellaneous>Keyword and choose Use Info. A pop-up should list the various door references in the bottom half of the pop-up. Double-click any of these to be taken to the location in the CK so you can see where in the world it is, then in-game head over to it before running the test command.
¶ Creating New Templates
Templates and the corresponding keywords are best placed inside the SS2.esm, and not parented to the Chapter plugins. If you'd like to contribute to the base mod's template collection, see the Merge with SS2 section at the bottom!
The template cells are effectively a faux interior for one of the building models in the Commonwealth we want to hook the World Repop system into. Effectively, you take the model found in the world, drop it into a cell, and do your best to build a basic interior for it. In this section, I’ll walk through some of the steps that must be done, give you a rough idea of how to get started, and talk tips for this as there’s no exact science to this part after those first couple technical steps.
Really any building can have a template made for it, but I’ve identified the building models that appear the most frequently in the world so we can start with those, head to this spreadsheet and pick a row that doesn’t have the Cell Template column filled out yet: https://docs.google.com/spreadsheets/d/1ZY-BJtyPLhRiZQX_PTMgWMY8hXWdZuMNCUCOlit6yC8/edit#gid=0
- In the Object Window, go to Miscellaneous > Keyword, then right-click and choose New.
- For the ID enter SS2_WRCellTemplate_ followed by the form ID of the building model this is for, if you are making a template for one already in the spreadsheet, it’s column E.
If this is a building not on the spreadsheet, please add it (contact kinggath to update if you don't have write access). Column E is for the first building with that shape, and I’ve found that often there are multiple buildings with identical shape and slightly different variations that could use the same template and those end up in the columns after E. - Press OK to create the Keyword record.
- In the Cell View window, find the cell SS2WRCellTemplateBld01FreeBrickRes01, right-click it and choose Duplicate Cell.
- Select the duplicate cell in the Cell View window and click the name again so you can edit it. Rename it to match the building model its for - ie. remove the Bld01FreeBrickRes01Duplicate000, and enter the form ID of the building model you’re making the template for. Press Enter to save the name change.
- Double-click the new cell to open it.
- Select the Bld01FreeBrickRes01 model and hit Ctrl+F on your keyboard, then swap it for the model you’re building the template for.
- Hide the model you just swapped in, by selecting it and pressing 1 twice on your keyboard.
- Select the blue COC Marker and hide it as well.
- Now delete everything else (unless some of those pieces are useful to you for the template you’re working on).
- Unhide the outer building and COC marker by pressing Alt + 1 on your keyboard.
Setup a layer to work on and make it active by clicking in the A column next to it.
You’re now ready to design the building’s interior!
I’ve found two ways to approach getting started on these:
1- Duplicate the exterior model and use Alt + Mousewheel to scroll through the different models. Bethesda tends to name all of their stuff by building kit, so you’ll likely find similar looking pieces you can use to build an interior for these.
2- Head to an area in game with a lot of these and look for any doors you can enter in a building that looks similar. Then you can use Better Console F4SE to figure out what cell you are in, run the console command prid 14 and press control on your keyboard. A bunch of data will appear on the left, one of which is the Cell - so you can go into that cell in the CK and see all the pieces Bethesda used - might even be a large chunk you can copy and then paste into your cell!
Some notes about approaching this:
- Your interior doesn’t have to match the exterior size perfectly, in fact, it probably won’t.
- You should focus on making an even grid more than trying to match the building perfectly. So if you place down two floor tiles and they go over the edge of the building model, use the two floor tiles as your width instead - the player won’t notice the slight increase (or decrease in size).
- Sometimes your hand is forced by the size of things like roof pieces, and you have to go off-grid size, though don’t be afraid to scale those odd pieces up or down if necessary - players aren’t going to know.
- Your goal is to set up something that looks fairly generic, provides the structural basics (ie. walls, floors, roof, stairs if multifloor), and is fully useable as is. These will act as a jumping off point for hardcore designers, and folks who just want to place furniture and clutter can do things like Alt+Scroll or Ctrl+Alt+Scroll to quickly change walls and floors to different styles and get a very unique looking base for themselves.
- By fully useable I mean should have a door placed, and an XMarker heading, some very basic lighting, and there should be no visible void if you coc into the cell.
¶ Adding More Doors
Doors to vanilla buildings in the Commonwealth worldspace are best added to the SS2.esm plugin directly to avoid multiple addons trying to place doors in the same place. If you'd like to contribute to the base mod's door collection, see the Merge with SS2 section at the bottom!
The easiest way to find buildings that might need doors is to use our spreadsheet of building models to find the building form names, and then the CK’s Use Info feature to find the references.
- Open the spreadsheet to find a list of building statics for a particular cell template: https://docs.google.com/spreadsheets/d/1ZY-BJtyPLhRiZQX_PTMgWMY8hXWdZuMNCUCOlit6yC8/edit#gid=0
- From columns E on are the editor ID’s of building statics, pick one you want to work on and filter in the CK’s Object Window under WorldObjects > Static for that ID.
- Right click the form that comes up matching that ID and choose Use Info, you’ll get a pop-up like this:
- In the bottom half of that screen are the references where this building model can be found. You’ll want to target the ones that have Commonwealth in the Worldspace column. Double-click one to have the CK load up that location.
- After the location has loaded, you should find yourself near the reference you just double clicked, and it should be selected and highlighted.
If the door is in a state where someone could move into it - ie. not sunk into a swamp or buried in rubble, you’ve one to place a door marker at! Otherwise, try the next reference down the list until you find a habitable building before continuing to step 6. - In the Layers panel, click New Layer and enter SS2_C2_Doors it should come back asking you to use the existing layer with that name, answer Yes to this prompt.
Next to that layer name, click under the A column to make that layer active. Then right-click the layer and choose Freeze All Other Layers, this will prevent you from accidentally introducing vanilla edits. - In the Object Window, under WorldObjects > Door, filter for SS2_C2_WR_DoorController. Place one of these doors in one of the doorways of the building (we only want one door per building currently, as syncing multiple up will require a much more complex configuration).
- The arrow should be facing out, and the door should be pulled out toward the front edge of the frame rather than close to the plywood, or whatever other boarded up form the doorway has. See image below for example.
- Next, place an XMarkerHeading just in front of the teal door marker and rotate it so the arrow marker is pointed away from the door - this represents the exit point the player or NPCs will be moved to when exiting the building.
- Be sure this marker is on the navmesh. You can temporarily visualize the navmesh with the hotkey Ctrl + E when the Render window is active (click the title bar of the little window you can see the worldspace in to make it active).
If the XMarkerHeading is not on the navmesh (the red areas that appeared), take note of the closest place in front of the door the navmesh exists, then exit Navmesh view mode with Ctrl + E again, and after it all disappears, move the XMarkerHeading to a spot it was and press F (this pushes the object down so the origin is on the nearest navmesh spot).
- Double-click the door controller reference, to open the reference properties.
- Uncheck Respawns. Otherwise whenever the area resets, the door will effectively become useless!
- Go to the scripts tab and double-click the script on it to open the properties window.
- Set the CellTemplateKeyword to the one matching the Cell Template column in the spreadsheet.
- Set the ReturnMarker property to point to the XMarkerHeading you placed.
- Press Ok on the script properties and on the Reference window, and save your work.
- You’re done! (well aside from testing...)
¶ Testing Your Door
Assuming a cell in the system matches this door, you can test it by loading your working plugin in game. Take note of the cell name you’re in, it should be listed as the title of the Render Window. You can use that with the coc command in console, ex. coc SanctuaryExt
This will teleport you to that cell, you can then use the console command:
cqf ss2_c2_WorldRepopulationManager TryToPairDoorToAvailableCell X
Where X is the ID of the door marker. You can find this by double-clicking the door reference in the CK, and looking at the top-right hand corner of the Reference window - there you’ll see an 8 digit hex number. The first two digits you’ll need to swap out for the load order of your working plugin.
If you go to the building, you should see a door there. Check that a lantern spawned to the left of it, and isn’t buried into the building model, if it is buried partially into the building model you’ll need to setup override position data - steps below on how to do this.
Enter the building and then exit it again to make sure you were correctly teleported back out to roughly the same spot as the XMarkerHeading you placed.
¶ Lantern Positioning
To update the position of the lantern, do the following back in your plugin:
1. In the Object Window, under WorldObjects > Activator, filter for SS2_C2_WRLantern, then place one where it looks good just to the left of the teal doorway marker.
- You’ll need to provide it something to hang from, the default system uses a scaled down version of SS2_metalBarb jammed into the wall so its sticking out enough to hang the lantern. Though you can use anything you like to hang it from.
- Double-click the door marker to bring up its Reference window, and slide that off to the side, then repeat for the lantern and object it’s hanging from so you have all three open.
- On the lantern and hanging object windows, go to the 3d Data tab as you’re going to need their coordinates. On the door marker’s window, go to the Scripts tab and double-click the script to open its properties.
- Double-click the Advanced heading to expose more properties, then double click the property DefaultExteriorDoorDecorationOverrides, and click Add to add a new record.
- This will bring up another properties screen where you will fill out the fPos, fAngle, and fScale fields to match the 3d data of the hanging object, and finally set its ObjectForm field to match the form of the object you used. Then press OK to save that entry.
- Repeat steps 4 through 6 for the lantern.
- Then click OK on the properties screen and close the 3 Reference windows you have open, and save your progress.
- Now delete the lantern and hanging object from the world (or if you’re worried you may have messed up the data entry, mark them as Initially Disabled on their Reference window for now until you can test that the door places them where you wanted).
- When you test, the door should now use your placement info instead of the lantern that had been stuck in the wall.
¶ Alternate Lantern Positioning Method (Added 3.2.1)
With version 3.2.1 of Sim Settlements 2, a new setting was added to the Door script called PairedEnableParent, this can be used to replace the need for DefaultExteriorDoorDecorationOverrides.
To use this, simply position the Lantern, Rod, and any other items desired to appear with the door, and connect them to an Enable Parent. Here's how to do that.
- Repeat steps 1 and 2 in the previous section for setting up the lantern.
- Add a EnableMarker static to the world.
- Select all the items you placed in step 1 (you can hold Ctrl to select multiple things, be certain you don't also have the EnableMarker selected, then click the - key on your keyboard, this will bring up the Reference Batch Action window.
- On the right-half of the window, dot in the Set enable parent option.
- Near the bottom of the window, click the Select Reference in Render Window button, then double-click the EnableMarker you placed in the world.
- That EnableMarker should now be listed as the Reference in the dropdown menu at the bottom of the Reference Batch Action window, if not, try repeating step 5 until you click the correct item.
- Click the Do button.
- Exit the Reference Batch Action window.
- Double-click the Enable Marker, check in Initially Disabled, and uncheck Respawns.
- Click OK to close the Reference window.
- Double-click the door marker to bring up its Reference window, then go to the Scripts tab, double-click the WorldRepopulationDoor script to open the properties.
- Double-click the PairedEnableParent property, then click the Pick Reference in Render Window button that appears on the right.
- Double-click the Enable Marker you created in step 2.
- Once again confirm you clicked the correct thing, like you did in step 5.
- Click OK to close the properties, and again to close the Reference window.
- You're done!
If you need both the PairedEnableParent and still want to make use of the DefaultExteriorDoorDecorationOverrides property, you can also uncheck the bPairedEnableParentUsedInsteadOfDecorationOverrides property.
¶ Adding More Influence Regions
An Influence Region is simply a location record registered with SS2's empire code so it knows whether that location show be included in its calculations. Those calculations are used to trigger things like the World Repopulation system, and will have further future utility with the 3.0.0 mechanics.
As of the 2.0.0 patch for Sim Settlements 2, only Concord is set up as an influence location. It is anticipated sometime between the time of this writing and the 3.0.0, most of the Commonwealth will be added to this as well. Therefore, this section is primarily for authors looking to add Influence support to other Worldspaces, such as NukaWorld, Far Harbor, or a custom mod-added world.
Since this system is based on Location records, random "Wilderness" untagged cells are not supported, but for things like World Repopulation Doors - the door itself can be force tied to a nearby location on the script properties screen.
Once you've determined the locations you want to register for influence:
- In the Object Window, filter for SS2_C2_InfluenceSupportedLocations_AddonTemplate under Miscellaneous > FormList. Right-click and duplicate it, then double-click your copy.
- Change the ID field to something like yourPrefix_InfluenceLocations.
- 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 the Location(s) under WorldData > Location and 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.
¶ Merge with SS2
If you'd like to help us expand the base system with more doors in the world and more templates available, please contact kinggath on the forums! The World Repopulation system will function best if all of the doors and templates are part of the base mod, as opposed to being in individual addon packs - and we'd love your help covering the entire Commonwealth!