What is a Scripted Mod?

Introduction

When a mod description refers to a “scripted” mod, it is letting the player know that the mod the player is downloading a mod using the Papyrus scripting language. Some mods, however, do not say they are scripted even if they are, and this can be confusing to a new player – and sometimes even a veteran.

What is Papyrus?

Papyrus is an object-oriented scripting language that is the basis for quests. Object-oriented programming models the language around objects and data instead of functions and logic. Other languages that are object-oriented include C++ (which is the language of Fallout 4's game engine) and Python (which is used by the Dragon Age Toolset and the xVASynth app).

Papyrus is what turns the game objects into something we as players can experience. The developers created the language for Skyrim and further refined and updated it for the Fallout 4 engine. It focuses on player actions and then responds with specific events in the game as the player continues their journey.

It is the force behind many of the complex behaviors in Fallout 4 such as Followers, Survival Mode, Dogmeat’s Behaviors, Legendary Effects, Power Armor Enchantments, Timers, Workshops, Perk Abilities, and Animated Events. Animation events include drinking from the water fountains found around the world, clicking a switch, and the crows flying off when the player comes within range.

What in the World Is A "Script"?

A script is just a plain text document compiled into a readable format for the game to interpret and do. New scripts are “external assets” and therefore restricted by SONY.

When a mod adds a script to a vanilla object it stays with that object for the entirety of the playthrough – unless it is poorly implemented or the player hasn’t received the proper instructions (or misinterpreted the instructions) on how to install the mod and the script never runs in their game or if it does, does so in a way never intended by the mod author.

Saving and Scripts

Players are able to save at any time, whether it be by hitting Quick Save, creating a Manual Save, sleeping in Survival Mode, or simply by opening the Pip-boy inventory menu. The script virtual manager is designed to freeze scripts during saving and then resume after the save is complete. The data is then dumped from memory once the script process completes.

Let's say, for example, you're tired of playing with a mod and want to remove it, but it is scripted. You've just made a save and have frozen that script. It is waiting to resume its processes. You cannot simply remove it and continue on the same save without the savegame becoming bugged or strange behavior occurring on the save. The script external asset might be deleted, but that script will still exist on any object it was attached to waiting to continue the process for the rest of the whatever was deleted. This can result in the object not functioning like it was supposed to, runtime errors contributing to save bloat, and crashes – some that seem random, some that occur almost immediately after returning to the save.

💡

Be aware that poorly implemented scripting or even a single typo can also contribute to runtime errors, crashes, and objects not functioning as intended, such as those that can happen with "infinite loops". When reporting unexpected behaviors, know that mod authors do not set out to damage your game. They released their work so you can have fun and not all mod authors have the funding for a QA department. Help them find any issues by first reading documentation prior to reporting to see if they already know about the situation and if they are giving technical support for their work. Be sure to provide detailed information so they can replicate the issue on their end if they are doing so.

What Types of Mods Could Be Scripted Mods?

Any object in the game can be extended with scripting so therefore any mod could be scripted even if it doesn’t specifically say so in the mod’s description – even on Playstation. Mod authors have access to the full library of vanilla scripts that can be used in their projects, and these scripts are packaged with the game itself and therefore not “external”.

Creation Club Virtual Workshop added a new set of “hidden” scripts to the vanilla game that mod authors can use even if the player doesn’t have that particular Creation Club creation.

💡

PlayStation players, especially, should use caution when attempting to disable mods and continuing on the same save because Bethesda never intended for their scripts to be removed and therefore there are no “uninstall” functions for PlayStation. Always return to a save that never had the mod or start fresh.

Notable Types of Scripted Mods

Read the descriptions and look for “script-inject” or “uninstall” in the wording. All mods that have an uninstall function with a holotape or chem or add a holotape or chem will be scripted. All quests that give the player objectives will be scripted.

Armors
Chems and Consumables
Followers
Holotapes and terminals
New Settlements, player homes
NPCs, Settlers
Perks
Power Armor
Quests
Radios
Robot armors
Survival Mode or survival mode mimicry
Weapons
Weather and climates
Workshop Menus

Perk mods that add new perks to the player do so with a script–either one from Automatron or self-written–or armor enchantments. Once a perk is added to the player it is baked into the save. Armor enchantments that are perks can be removed by unequipping the enchanted item. Armor enchantments include mods that add new legendaries or a buff such as resistance to ghouls.

Weapons and armors that are scripted–and most are unless they’re hard edits to vanilla forms–have no way to uninstall safely. Console players have no way of knowing if a weapon or armor mod has merged their naming rules with that of vanilla or AWKCR’s ruleset.

💡

Weapon and Armor mods that have Far Harbor or Nuka-World as a master may have re-used vanilla scripting to merge their naming list so PlayStation players should be aware of the possibility of using a scripted armor or weapon.

Any quest will be 100% scripted and many mods contain quests that are set up as “dummy” quests to simply push a script– such as one that “script-injects”. Mods that add new dialogue or radios are also Quest Mods. Depending on what the mod with a quest is doing it may not have a safe way to uninstall.

Radios have additional scripted scenes that loop and require hidden NPCs to function. If they are improperly set up or have no additional scripting to loop them, they will shut off after the first scene (which is usually the music playlist). There is no way to restart them on consoles but PC players can force a radio quest to restart with console commands.

New settlements are complex triggers and keywords with a quest that hooks into the primary settlement system. The workshop object that a player activates in order to build objects within that settlement has persistence in order for the player to be able to view their caravan lines (among other things) in the Pip-boy when they are nowhere near the settlement. There is no safe way to uninstall a new settlement or a mod that uses the settlement system.

Script-Injection

When a description says “script-injection”, this means that the mod author has used a script to add new items to the player character, leveled item lists, NPC spawn lists, or workshop menus and FormLists.

There are two means of script-injection in Fallout 4. One uses a function called AddForm. This is the most commonly used (examples include: adding settings holotapes or new items to the player character or a leveled item list, adding a new workshop menu, or adding new NPCs at spawn points).

The other uses a function called MergeWith(). This function is only used for weapons and armor mods to update base game instance naming rules of their new gun or armor they’ve added to a leveled item list using AddForm(). The instance naming rule list is the list that tells the game what to call a weapon or armor set when you add it to the base weapon or armor piece.

These could be names of linings and materials on armors that will show up at the top of the screen tacked onto the piece you’re modifying. So let’s say the mod you’ve downloaded adds a new chest piece that allows you to craft welded materials and asbestos lining on it and it also adds this chest piece to the level list for raiders. For this example, we’ll say these new materials and lining are totally brand-new to the mod and don’t use the same keywords as vanilla or AWKCR (or another crafting mod). The name, when it spawns, will be Welded Asbestos-lined Chest Piece (or something like that) because the keywords on the new armor mods are script-injected onto the instance naming ruleset list using MergeWith().

Scripted Mods Best Practices

Don’t disable/uninstall and continue on the same save.

Bethesda never intended for plugins (either vanilla or mods) to be uninstalled during a playthrough. Scripts can leave behind operations that could still run in a very fragmented, broken way. Because of really bad modding practices by players in the PC modding community, mod authors were forced to implement “uninstall” features in their mods. This has unfortunately carried over to console.

Furthermore, the Creation Engine and how it indexes the unique PRIDs of each playthrough is not designed for plugins to be turned off in the middle. These PRIDs are recycled if uninstalled, creating a timebomb if they return “None” when the original save thinks there’s supposed to be something there. But more on that at a later date.

Know when to install a script-injection mod.

Script-injected mods should be installed prior to new game start. Some older scripted mods are implemented poorly and script-inject items onto the player at the wrong time during the prologue. These mods should be avoided until the author can fix them. Many mods come with a craftable holotape, chem, or aid item in case papyrus backs up during start-up.

Know when to update.

It is better to wait for the next playthrough with a fresh character to update a mod. As a general rule of thumb, only update scripted mods during a playthrough if they contain a holotape that re-initializes the script. Not reinitializing a script could result in a script malfunctioning during gameplay. Without debug functions to reset a script, this is very problematic on consoles.

💡

Some mod descriptions suggest using a ‘clean save’ to reinitialize the scripting, however, this is a bad modding practice of poorly implemented scripting and is not recommended. Not everyone has the same programming skillset required for Papyrus nor are there enough tutorials on the subject for novice mod authors. Some poorly implemented scripting may contain "infinite loops" or may not "unregister". The script not being able to "unregister" properly may occur if uninstalled, resulting in runtime errors and other bugs if the save is re-entered afterward.

Know the various types of scripted mods.

Chems and Aid Items - Some Mods come with chems or aid items to be built in the Chemistry Station. Read the directions for use prior to using them. Some will uninstall the Mod from your game and will need to be uninstalled and reinstalled from your load order to function properly again. This is not a safe practice.

Settings Holotapes - Read all documentation when mods come with holotapes. Some mods require using the holotape to turn off the script in order to remove the mod. Some are only settings and do not have an uninstall feature at all. Mods like Cheat Terminal add the holotape to the player character when you first open the Pipboy.

Leveled Item Lists - Once you install a scripted level list mod, do not uninstall it in the middle of a playthrough. It will permanently break the level list(s) it edits. As a general rule of thumb, install level list altering mods at the start of a new game. Certain level lists are only called once per playthrough. If you install mid-play, the level list may not be altered properly and either will not work or cause issues later in the play-through.

💡

These types of mods generally do not come with an uninstaller because there is no safe way to uninstall due to the limitations of Papyrus. This is a limitation, not a mod author error.

Leveled Actor Lists - Once you install a scripted level actor list, do not uninstall it in the middle of a playthrough. These NPC spawn lists will permanently break. Leveled Actor Lists have no uninstall but a function called Revert – which can break any other mod that script-injects its NPCs into the same list as the mod you want to uninstall. As a general rule of thumb, install leveled actor lists at the start of a new game. Certain lists will be called once per playthrough and each enemy spawn point in the game has a turf controller that controls enemy AI. Both installing and uninstalling mid-play could cause oddities with enemy spawns.

Form Lists - The same applies to form lists as it does to leveled lists. Form Lists permanently break if objects are not removed from them before uninstalling. Workshop menus are form lists, but there are other lists such as lists of voice types for robots or master AI package lists. Settlement Menu Manager provides a safe method of installing a menu via scripts. It also provides a holotape to attempt to save menus that are broken if a mod is accidentally uninstalled. See SMM’s mod page on both Nexusmods.com and Bethesda.net for more information.

Perks - Do not uninstall in the middle of a playthrough. Perks are commonly attached to the player character or other actors similar to magic effects. While perk script fragments are discouraged for use unless absolutely necessary, there may be a mod that requires such a practice in order to function.

💡

Mods with too many perk fragments can overload the Papyrus engine as most perk entries except “Activate” fire faster and with little regard to everything else. This is both a limitation and a mod author error; however, there is little official documentation on the subject so can happen quite easily, especially on console, where the graphics engine takes precedence over the Papyrus engine. It is up to the player to test mods prior to including them into their load order.

Quests - Quests are the heart of the game. There are many different types of quests, not just the ones that the player sees. Scripts are used to start and progress them. Do not uninstall in the middle of a playthrough. There is no way to safely remove a quest mod for several reasons, including scripting. Dummy quests are those with just a script for script injection or mod maintenance purposes. Dialogue quests add new dialogues to vanilla NPCs or new NPCs. New followers will have several sets of quests running simultaneously to hook into the Followers System. New quests can be those that add objectives for the player to do during gameplay or add new random encounters. Most new quests that give the player something to do function better near the end of your load order. Some of those quest mods also come with a holotape that players will need to use to turn off the script when not in use.

Workshop/Settlement Building Mods - Many settlement workshop mods add menus by way of script injection and come equipped with either a holotape or a chem to be built in the Chemistry Station. Many also require Settlement Menu Manager. This requirement is a scripted hook that looks for SMM in your load order.

💡

Some building mods add new lights, light switches, or other objects that hook into the power grid system. Read all documentation prior to installing as uninstalling could lead to power grid corruption.

Further Information

If you have any questions about Papyrus or scripted mods in your load order, come join us on Discord.