There has been some pretty significant interest in the repair function I used here, and how to use it in your own mods. Most notably by tenhats and Aurelianis, though I have been approached by others. The script I made and used in this mod is free for anyone to use, but that does not necessarily mean it is intuitive and easy to use. This tutorial is something I'm putting together in the hopes that it helps people use the script, and thus results in more settlements with the repair feature.
This tutorial assumes you have the following:
- An installation of Fallout 4 in good working order
- The Fallout 4 Creation Kit
- The miscellaneous "Structure Repair Script Modding Resource" file from my Natick Substation mod page.
In this tutorial, I will be making the mailboxes in Sanctuary repairable, so that the player can replace them with their pre-war variants.
Note: This process involves convincing the game that an object is "broken", the same way that water pumps and power generators can be broken by settlement attacks. The game has some hard-coded behavior for broken objects, such as blocking the player from using them. Thus, "breaking" a container such as the mailboxes I've selected will make it so the player cannot loot them. Breaking a door prevents it from being opened or closed, etc. For things like walls and other building parts, this is not a concern to worry about.
Step 1: Safe Scripting
An important thing to remember is that mod files can conflict with each other, and so it is a good idea to make sure that your copy of the script does not get overwritten by anyone else's copy of the same script, just in case it gets updated or changed. For that, we're going to be using namespaces to hide the script away in a folder for your mod.
Since this mod is making the mailboxes in Sanctuary repairable, I will make my namespace "RepairableSanctuaryMailboxes". To do that, I go to my data folder, create a folder called "Scripts" (without the quotes), if it doesn't already exist. Then I create a folder inside "Scripts" named "Source", a folder inside "Source" named "User", and a folder inside "User" named "RepairableSanctuaryMailboxes".
This is to make it much less likely that another mod will have the "same" script, according to the Creation Kit. You should make sure your namespace is something that is reasonably unique, and ideally it would also be something reasonably associated with your mod.
Once I have that done, I will put the script I downloaded, which is named "BrokenStructureSwap.psc" (you may not see the .psc, depending on computer settings) into the "RepairableSanctuaryMailboxes" folder. Once I've done that, my folder looks like this:
Don't mind if the icon is different from what you have, that's just because I have papyrus scripts associated with a program called Notepad++.
Now that I have the script in its new home, I right click it and select "Open with -> Notepad". Depending on your computer, you may need to manually select Notepad rather than it being available automatically.
Once the file is open in notepad, I find the following line of code:
Scriptname CHANGEME:BrokenStructureSwap extends ObjectReference
The only part of this line we want to edit is "CHANGEME". I will change it to "RepairableSanctuaryMailboxes", and you should change it to whatever you named your folder. For me, that part of the script now looks like this:
Note that the colon is still there, between "RepairableSanctuaryMailboxes" and "BrokenStructureSwap". That colon is what tells the game that "RepairableSanctuaryMailboxes" is a namespace rather than part of the script's name, so make sure not to delete it.
After that, I open up the Creation Kit. If this is your first time opening the Creation Kit, it may bug you about extracting scripts. Tell it to extract those, you'll need that to be able to compile things. Extracting scripts may take a few minutes, depending on your computer. When the Creation Kit has finished opening, I select Gameplay->Papyrus Script Manager from the menu at the top, which opens up the script manager window. That window may take a moment to open, that is unfortunately very normal.
Once it opens up, you're going to see a very, very long list of script names. Ignore that list, and type "BrokenStructureSwap" in the textbox at the top. Once you do, the list should be filtered down to just scripts with that in the name, like so:
Next, I right click RepairableSanctuaryMailboxes:BrokenStructureSwap and select "Compile" from the menu. That will pop open a new window, which closes on its own if the script compiled successfully. If the script fails to compile, the window stays open with an error message describing what when wrong. If this happens, you likely made a mistake and should double-check the instructions above to make sure you didn't miss anything.
If you get that one to compile, repeat the process with "ProtectedReference.psc" and, if you are making complex repairs that use a separate enable parent, with "ProtectedEnableParent.psc"
Now that the scripts are compiled, you're good to move on to the next step!
Step 2: Creating Your Mod
The rest is actually kind of easy, but also quite time consuming. First, we need to actually have a mod to work on. To do that, I select File->Data... from the menu at the top, and double-click on "Fallout4.esm", which leaves the load window looking like this:
If you're going to modify a settlement from one of the DLCs, make sure you have that DLC selected too. Once you've got everything selected, hit "OK" and give the Creation Kit time to load. It needs a lot of time to think on this sort of thing. You'll get used to it eventually.
Note: If the Creation Kit complains about multiple masters and closes, you need to follow the instructions found here. Once you've done that, you can backtrack and try loading again.
Now that I have the creation kit loaded up, I hit the save icon in the top left and save my mod. The name doesn't specifically matter, but it would be a good idea to make it something recognizable. I named mine "RepairableSanctuaryMailboxes". After that, I go back to the File->Data... menu at the top left, select "RepairableSanctuaryMailboxes.esp" from the list, and hit the "Set as Active File" button in the bottom left. This is how you load up your mod for editing, rather than setting up to create a new mod.
Since I'm here anyway, I'll go ahead and edit the "Created By" box with my username, and the "Summary" box with a quick summary of my mod. Before I hit OK, the window wound up looking like this:
Step 3: Creating Repairable Objects
The first thing I need to do is make a "repaired" mailbox for me to use in this mod. Luckily, the game already has the model I need. I type "Mailbox" in the "Filter" textbox of the object window, and then expand the "WorldObjects" list and select "Static". That will give me the following:
Depending on what you want to make repairable, there may already be an appropriate object that exists. There also might be an appropriate model in the wrong type of object. Unfortunately, there also might not be anything you can use, and you might need to create a model yourself. In my case, I have the right model but the wrong kind of object.
I will double-click "Prewar_mailbox02" and copy "SetDressing\Mailbox\Prewar_mailbox02.nif" out of the "Model" textbox. It's in the middle left for static objects, but that will vary by object type. After that, I select "Container" from the tree menu on the left of the object window. With the filter I typed earlier, that leaves me with just these visible:
Now, I'll right click some of the empty space below "SanctuaryMailboxEmpty" and select "New". I give the container the id "RSM_SanctuaryMailboxRepaired" and the name "Mailbox". The ID is important - the creation kit requires that every object has its own unique ID. That's why I put a prefix at the start, to reduce the likelihood that my ID will overlap with someone else's.
Once that's set, I click "Edit" to the right of the Model textbox and paste the filename I copied earlier in. After that, I "OK", and then "OK" again on the container window, which closes both the model and container windows.
Next, I want to create a copy of the original "SanctuaryMailbox" and "SanctuaryMailboxEmpty" objects. I could work with the ones Bethesda made, but that means that my repair recipe might interact with other mods and cause issues. I prefer to use standalone objects in order to avoid that.
In order to copy an object, I select it, press F2, change the name, and press Enter. A window pops up asking if I want to create a new object. I select "Yes", and this creates a copy of the original mailbox with my new editor id. Once I've done that, I am left with the following list:
The next thing I need to do is make a list of objects to be repaired. I could make a recipe for each individual mailbox by right clicking them and selecting "Create Recipe", but I'd rather only make one recipe if I have to. In order to do that, I expand "Miscellaneous" in the tree menu on the left of the Object Window, and then click FormList. Since I still have my filter in place, I'm left with a big empty window that looks like this:
Depending on your filter, there may already be items here. Regardless, the next thing I do is right click the empty space and select "New".
After that, I fill in the ID and name for the list. Notably, you are required to give this FormList a name as well as the ID, otherwise the Creation Kit will not let you pick it for the repair recipe in the next step. Once I have the name and ID, I go back to WorldObjects->Container in the Object Window, select "RSM_SanctuaryMailboxRepairable" and "RSM_SanctuaryMailboxEmptyRepairable", and drag them into the big empty box on the FormList window. This leaves me with the following:
With the FormList set up, I hit OK, and then move on to "Items->Constructible Objects" in the tree view on the left of the Object Window. I'll right click the empty space, select New, and wait a moment for the creation kit to open the window. After that, I'll give it an ID, select "WorkshopWorkbenchTypeSettlement" from the Workbench Keyword dropdown, and then select my FormList from the Created Object dropdown.
After that, I need to actually make the recipe. Since this is a simple steel mailbox, I want it to cost two steel to repair. The game automatically adjusts the costs of repairs by making an item cost 1/10 as much to repair as it takes to create, so the recipe should actually call for 20 steel if I want the player to spend 2 to fix it. To do this, I right click the box below Required Item List, hit New, and select "c_Steel" from the dropdown. Then I enter 20 when it asks for a number, and hit OK. This leaves me with the following:
Then I hit OK, and that's it! I've created a repairable object that I can use in my settlements. Sort of. The next step is going to be important for actually using it.
Step 4: Repairing a Settlement
Now that I have everything I need, I go to the Cell View window, select "Commonwealth" from the "World Space" dropdown at the top left, and find SanctuaryExt in the list. The specific cell you want is going to vary by settlement, so if you don't already know what cell you need, you may need to do some research. Most fallout wikis will tell you the cell name for a place somewhere in the little infobox at the top of their articles.
In my case, that little window looks like this:
From here, I double-click SanctuaryExt and give the Creation Kit some time to think. It always takes a bit to load cells, so don't worry if it seems slow. The more stuff there is in the area, the longer this part takes.
Once it's loaded, I find my first mailbox and select it:
Selecting it is mostly so I have a clear visual indicator of what I'm looking at. After that, I'll go back to WorldObjects->Container on the object window, select my RSM_SanctuaryMailboxRepairable, and drag it into the render window. I'll just drop it right on top of the big green mailbox you see above, and then I'll do the same thing with RSM_SanctuaryMailboxRepaired. That gives me the following:
Looks amazing, right? The best repair ever made. Anyway, let's fix this. Right click the original mailbox and select "Edit", and then do the following to both new mailboxes. You'll be left with three of the following window, stacked on top of each other:
The next step is pretty simple. You want to copy the X, Y, and Z for both Position and Rotation out of the original mailbox and into both new ones. Do the same for Scale. Afterward, make sure you click on a different box to make sure the Creation Kit "remembers" the last bit of text you entered. Otherwise you may lose the last bit of information you pasted.
Note: You can also perform the above step by selecting the object you want to move, pressing "CTRL+A", and clicking the object you want to copy the location of. Then repeat the process with "CTRL+SHIFT+A" to copy the position.
It may be worth checking the "Extra" tab to see if a material swap is set on the original object. If it is, make sure your repairable object uses the same swap. If not, just jump back to 3D data.
If you want "repairing" an object to fix its position, you can move the repaired object to be wherever you want it. The above is mostly so you can perfectly maintain alignment for building pieces.
In 3D data for the original mailbox, the one you're replacing, set Z to -30000. After that, select the "Initially Disabled" checkbox from the big list of options at the bottom. Once that is done, dig through the list of tabs (you probably need to use the arrows on the right edge of the list) and select the "Enable Parent" tab.
On the Enable Parent tab, type "Player" into the filter box, select "(any)" from the cell dropdown, and then select "PlayerRef ('Player')" from the Reference dropdown. It should be at the very top of the list. Once that's done, select the "Set Enable State to Opposite of Parent" checkbox and hit OK. With that, you've safely removed the original mailbox in a way that won't break other mods or peoples' save files. In my case, the window looked like this before I hit OK:
Now that the old mailbox is out of the way, it's time to make it so the new mailbox shows up with the "Repair" option in the workshop. To do that, I'll go all the way to the very last tab on the reference window, labeled "Scripts". Once I'm there, I click "Add" and wait for a moment for the script box to pop up.
I'll type "BrokenStructureSwap" into the Filter box, and then double click "RepairableSanctuaryMailboxes:BrokenStructureSwap" in the list. Remember, the first half should be the namespace you set up at the very start of the tutorial. When I double click the script, a new window pops up with "EnableParent" and "Workbench" in red.
For EnableParent. I will be selecting the repairable mailbox I'm currently editing. To do that, I click the EnableParent line, then click Edit Value on the left. Normally, I would select a reference in the render window, but since I already stacked these two together, that gets awkward. So instead, I need to manually pick my mailbox by selecting the current cell, and then selecting the repairable mailbox from the dropdown. Make sure you pick the right one! I certainly don't want to make it so that repairing one mailbox fixes the one next door instead, so I'll have to be careful once I have more than one mailbox.
Note: If you want multiple "parts" to be repaired as a single object (for example, you can have several tires and a car get repaired together), place an "EnableParent" static object and use that as your EnableParent reference rather than using the repairable object. If using a separate enable parent, attach the "ProtectedEnableParent" script to the EnableParent reference to prevent Workshop Framework or Sim Settlements from breaking the repair system.
This next step is absolutely critical to making the mailbox repairable. Select the Workbench line, and click Edit Value. Move around in the cell view window until you can see the workbench for the workshop you're editing. After that, select "Pick Reference in Render Window" and double click the workbench. Once I wrapped up with that, my script window looked like this:
Now, I just hit "OK". That should leave you with your fancy new script in view in the script tab for the reference window.
Note: If you have multiple parts being repaired as a single object, you need to use the Enable Parent you made earlier. To do that, go back to the mailboxes and enable parent in the render window, so you can see them on screen. Then go to the "Enable Parent" tab on the repairable mailbox's reference window, and select the enable parent object you placed as the reference. You can use "Select Reference in Render Window" for this, exactly like you just did with the workbench.
Now that you've set up the old, broken mailbox, click OK to close its reference window. At this point, if you save the mod and load it ingame, you can repair the mailbox. Unfortunately, it will just vanish as soon as it gets repaired. Let's fix that!
You should still have the reference window open for the "repaired" version of the object. If not, you'll need to open it back up by selecting the object (either in the big list in the cell view window, or via clicking it in the render window), and the right click and select "Edit".
The first thing you should do is go to the "Scripts" tab all the way at the end, click "Add", and the "ProtectedReference" script. You may need to change the search filter to see the script in the list. When you add the script, it will open the same Properties window as before, but you should just hit cancel on that window since there is nothing to do there. This script helps prevent Workshop Framework and Sim Settlements from breaking the repair functionality by un-pairing the objects when they get used in a city plan or settlement layout.
Once you've done that, go over to the "Enable Parent" tab, and select the repairable mailbox. If you're making multiple pieces repair as a single object, select the enable parent you made earlier instead. After that, check the "Set Enable State to Opposite of Parent" checkbox and the "Initially Disabled" checkbox. For me, that looks like this:
What those do is make it so that the "repaired" mailbox is only visible when the "broken" one is not. After that, hit OK, and you're done! You have successfully made one repairable object, in a standalone fashion that doesn't affect other mods. At this point you can save, add the mod to your load order, and next time you visit the settlement ingame the object should be repairable.
Due to how this works, if I load into an existing save where I'm already in Sanctuary, it will look like my mod didn't actually work. That's a minor issue with how the game handles "Load" events with scripts. All I need to do is go somewhere else for a bit and come back, and then everything will be set up exactly as expected.
Once you're done with your mod, I highly recommend cleaning it with FO4Edit. It would a good idea to double-check your mod with PJM's Previs Patching Scripts, because if you used this tutorial for static objects, you probably broke precombines in the process. It's also likely you'll be able to turn your mod into an esl, so that could be worth considering. And finally, you may want to pack up any models and assets you used in the mod, such as the script that makes everything work.
If you want to share the mod, make sure you include the compiled script in the upload. For me, that script wound up in the folder "Scripts\RepairableSanctuaryMailboxes", though for you that will be in a folder with the namespace you picked. The script is 100% necessary, and without the compiled version the mod just won't work. You can include the uncompiled version if you want, but that isn't required in order for things to work.
0 comments