Developer note: This manual was originally created before the existence of PJM’s xEdit script set that build 69 was built with, and should be referenced instead of this older document, at least until I get around to rewriting it. The link can be found a few paragraphs below.
A small preface before I begin: I’ve never been that good at documenting in a clear and concise manner, so bear with me as I do my best to explain the process. This living manual is not going to be very pretty at this stage as my current goal is to explain the methods used as best I can to those that don’t know that much on how to use the Creation Kit.
To start, what are previsibines exactly?
Before we get too in depth, there’s a few things that need to happen to get your game to be able to deal with this effectively. At the bare minimum, you need the following:
There’s a set of optional scripts floating around that makes this easier to work with and I’ll point out the options as they are relevant - this includes the previously mentioned pack above. Also, I personally use CK Fixes 2.0.1 Some don’t like it and it’s got bugs in odd places, but it does the job for me, it is required currently due to the recent previs API fix. If you have more than three masters, the CK will not get past the root cell check in the previs phase without that plugin. My recommended config to use with it is on the PRP mod page in the Misc section, replacing fallout4_test.ini
If you are building for XB1 players, a setting has to be manually patched to the 0x02 format. Set the first of the two options in the ini to 2 to make this work and build filtered for precombines.
Now we are going to do a sanity check. Open your Data folder or Mod Organizer 2’s mods folder and make absolutely sure that the texture .ba2 archives you need are activated. This means the archives for any mods you’re using during previsibines generation, as well as all their masters. Optionally, create a textmp folder in Data/ while you are here. The reason we do this sanity check is that if you don’t have textures present during generation, the meshes tend to break in unexpected ways. This is a theme one will notice as they read this, as this isn’t the only time.
For the preparation stage, open FO4Edit like one would usually do for editing. To minimize confusion, select your mod and any dependencies that you want to include in generation. The tool should have already selected anything that’s in the plugin’s master list by default. I highly recommend at least loading all the game’s .esm files (Fallout4.esm and all the DLC) in addition to the Unofficial Fallout 4 Patch. Add all relevant dependencies including the ones just mentioned as masters via Add Master. Then use Sort Masters right afterword.
Then, in the plugin you are working on, find the File Header (click the + icon if you don’t see it.) On the right side, the Record Header section, there’s a set of Record Flags. Do the following: If ESL is checked, remove the check, and also check ESM. Do the same for any other plugin that’s a master of the plugin you are working on that isn’t already. Then close xEdit, letting it save the changes. If you are worried about losing the ESL flag and shipping it out as a master file, it’s only for the duration of this manual’s method. You can always change them back at any time, but for the purposes of this manual, we assume they aren’t changed until otherwise noted later on. One note, if you do not tag this plugin as a master or any other dependency as such, the Creation Kit can and will drop the master assignment from your plugin. As a result, any generated records will default to slot 01, which will have undesirable effects, most of which result in crashes to desktop.
Regarding the Unofficial Patch in the context of previsibines: as of the current release and older versions that aren’t the upcoming 2.1.4, that plugin DOES add previsibine changes to cells that might be affected by your mod. If they conflict in a way that you know you haven’t tried to move or touch, forward the changes to your mod. This also applies to my Previs Pack Fixes mod, but using that is out of scope of this document for now. If you are reading this in the future and 2.1.4 is out, the relevant records have been removed and currently live in the Fixes plugin I mentioned. The reason for the removal is because UF4OP doesn’t touch previsibines by choice and by network bandwidth requirements. We don’t have to worry about that here. note: Create separate documentation on what Previs Pack Fixes actually fixes and also link to any relevant UF4OP bugs as they are tracked. Personal reminder to future self. PRP-Bugtrack.txt has some of that info. Further note, file created as PRP-Bugtracker in repo, link needs updated
At this point, if you haven’t closed it and forced a save to the plugin, re-open FO4Edit again. One of the scripts in Pra’s pack is called Apply Material Swap. Not to be confused with 50_FixMaterialSwap from Searge’s script pack, which is non functional (it’s literally missing two lines compared to Pra’s script). You essentially apply the script through FO4Edit by selecting your plugin. What this does is explicitly set Material Swaps in assigned statics. The reason for this is to get around the Creation Kit not using Material Swaps during the previsibine generation phase. There’s no good way that I’ve found to omit the newly created sub record bloat as a result of this. note: May require a rewrite if others chime in on a workaround
You have two options at this point. One: Use the Copy Version Control info script on your plugin and copy from the source .esm files if you haven’t made any new records. This is required for the purposes of the Creation Kit to correctly grab all the records for the purposes of our work. All records must have a valid date and cannot be showing None. Turn off the “only show conflicts” right click filter if you can’t find them. The alternative is to simply load the plugin in the creation kit, and save after it finishes loading.
Now to actually generate previsibines through the command line. (By the way, I personally use Con Emu for this, but any command line or Powershell will work for this purpose.) The typical command line is:
CreationKit.patched.exe, CreationKit.exe, or f4ck_loader.exe (CKFixes only currently recognizes the second name, keep this in mind if you have patched the EXE. Use the third option if you use an enb and not Searge’s patched CK, third one requires an additional download for the f4ckfixes. Third one is not needed if you remove your enb files) -GeneratePrecombined:pluginname.esp clean all
That command line above can be changed a bit as follows: clean or filtered (Clean mode generates like the base game and DLC while drastically reducing the filesize compared to the filtered mode which is equivalent to the Creation Kit’s Graphical User Interface.), and ints or exts or all note: Verify this, going off memory (Tells the command line which group to build, useful if you have less RAM to work with. There’s also something about sets, but I don’t have the information on that at the moment. note: Research) A note here: if you aren’t using CK Fixes, you cannot have spaces in your plugin name.
If successful, you’ll see the CreationKit start to load the plugin and go through a long process. CK Fixes users should look at the attached log window for what it’s actually doing, those not using it can just review the log generated. Depending on the plugin size, this will take a while. A typical Previs Repair Pack build at this stage takes two hours, and that’s the entire game with my somewhat powerful machine. Don’t touch the CK window or anything related to it. It will close on its own when it’s finished, presuming it doesn’t spit out an error code of some sort. If you get such a thing, check the consistency of your plugin. Common problems are missing meshes or internal plugin information related as such.
Once a run is successful, depending on the method used, you should see some new files in a few places. For clean mode and filtered mode both, there will be at least one previsibined Mesh inside Data/Meshes/Precombined/. You want to keep those, as they are part of the magic that improves your mod’s FPS footprint. Clean mode generation uses should also find a file in Data/ that is the same name as your plugin but with a .psg extension. What is psg, you ask? previsibined Shared Geometry. This is why the clean mode meshes are so small compared to filtered. They are all considered and deduplicated into that file. The engine actually won’t use it in its current state, but we’ll deal with that in a moment.
There’s an additional plugin that’s always generated if successful called CombinedObjects.esp. Pull up FO4Edit and load that, which should automatically select your existing plugin. You’ll immediately notice a few things about it. Any cell or worldspace chunk that the plugin had edited has new records or updated records in previsibine related sections and also NULL as the lighting for some reason. This is the information that tells the game what previsibine meshes to load for what block of the world in the game. It’s not wise to try and manually merge that information cell by cell. We have scripts for that. You have two options here:
03_MergeCombinedObjects.pas to your plugin. NOT the newly generated CombinedObjects plugin. Exit and save afterward.Regardless of which option you chose above, the next step is to optionally clean Identical to Master previsibine meshes. note: Obviously need to fill this in proper. Script is 04_FO4previsibinedDataEditor.pas from Searge’s pack or if you are crazy and want to do it per cell, the original is still on the nexus by Zilav.
At this point, unless you have a certain number of meshes below 8192 in count [note: Verify exact number. Related to file handles], you need to pack up the meshes and any supporting files into a .ba2 archive to get around the Creation Kit file handle limits. You have a few options to do this. I personally use Pra’s Collect Assets script for this purpose [note: script creates .ba2 in asset-collector-output and needs manually copied or moved over], but there’s the manual method, and possibly Cathedral Assets Optimizer, though I haven’t used it. [note: check status of tool, last heard not recommended with FO4] Highly recommend leaving the archive uncompressed, especially if you also have sound or music included.
Once your archive is successful, clean out the loose files from the appropriate directories in Data/. This will usually be just Data/Meshes/Precombined/ if you have nothing else included.
The following steps only apply if you generated with clean mode. Filtered mode generations can skip ahead a bit to the Previs phase.
First of all, that .psg file that got generated needs to be compressed. This is thankfully very easy to do. CreationKit.exe -CompressPSG:pluginname.esp is what you use to do this. The Creation Kit will pop open while it works, and disappear when finished. If it does nothing, double check the command you typed. You’ll see a smaller sized .csg next to the .psg file. Distribute that with your mod. Delete the .psg if you like at this point.
You also need to generate a cell index file. CreationKit.exe -BuildCDX:pluginname.esp will do this and take longer than the previous step. If you are watching the log file or window and start to see things about dummy data, your previsibine meshes did not generate properly and you will have to start over. When it’s done generating, make sure you also pack this with your mod.
Now, before you start the previs generation run, there are two things to note. This is the part that takes the longest, and is about six hours for the entire game on my system. If you want to save some memory usage, temporarily move ALL texture .ba2 archives to that textmp folder you were asked to create earlier in the manual. The CK is dumb and tries to load all archives during the generation and for previs. For this step, textures aren’t a requirement, so we can safely remove them from the process.
Once you have done this, the command line is CreationKit.exe -GeneratePreVisData:pluginname.esp clean all. You may notice that the options that were discussed on the previsibine phase are valid here as well, and recent discussion recommends using clean mode regardless of what you used to build previsibines on. I personally haven’t seen much a difference between the two modes, but I suspect that filtered previs is equivalent to the first CK GUI mode and shouldn’t be used. [note: Verify this]
Go make some coffee or something. As previously stated, this is going to take a while. The CK will close when it finishes like before. If successful, you’ll see a new subdirectory in Data/ called Vis/.
Take a moment to move the texture .ba2s back to the Data/ folder before you continue so that future runs aren’t broken due to this. Trust me, I’ve made this mistake before.
The CK also generated a file called PreVis.esp. This file is the previs equivalent to the CombinedObjects.esp file above and the same information applies to it. Use 05_MergePreVis.pas from Searge’s scripts or do the CK resave dance and merge with the same master list fixed script as before.
Also, repack your archive to include the newly generated Vis/ file contents, which all end with .uvd. They are Umbra tomes and are the important information the game uses to figure out where to occlude and render correctly for optimum frames per second. Delete the Vis/ subdirectory after once you’ve confirmed they are in Main.ba2.
At this point, you are done with the generation part. It’s technically ready for release provided you include the plugin, Main.ba2, Texture.ba2 (if applicable), and supporting files (such as the .csg and .cdx) Also, your plugin name is hashed in the meshes, so do NOT rename your plugin, or else you’ll have to rebuild again.
Start testing the mod and check to see if it’s all looking okay, as the Creation Kit has known issues in places with generation and there’s only so much we can do about it. Run Quick Auto Clean and Identical to Previous Overrides if needed on the plugin and release if it passes testing.
[note: need to fill in common pitfalls and known technical issues like the 3 master limit on unpatched CK]