Papyrus FAQs

Resources

Why doesn't the Creation Kit's script editor have syntax highlighting?

The Creation Kit allows you to open scripts with an external text editor from the context menu, so you should use an external text editor if you want syntax highlighting and other features.

Where can I find a list of functions and their syntax that I can use in my scripts?

You should refer to the wiki and ultimately the source scripts, like Actor.psc, ObjectReference.psc, and Utility.psc. These are the "classes" that your scripts typically "extend."

Where can I find examples of how to accomplish <something> or how to use a function?

Using a free third-party program named Agent Ransack, you can search through all of the base scripts almost instantly for examples, especially with a SSD.

To whom do I send fan/hate mail about Papyrus?

SmkViper created Papyrus and actively helps scripters in the official Fallout 4 Creation Kit forum.

First Steps

Where do I find the source scripts?

1. In the Data\Scripts directory, there is a ZIP archive named Base.zip.
2. Extract that file using 7-Zip, WinZip, or Windows' native ZIP handler to the same folder with paths.

Why can't the Creation Kit find the source scripts?

You should have the following folders in the Data\Scripts directory:

• Data\Scripts\Source\Base
• Data\Scripts\Source\User

In the Base folder, you should find all of the scripts you've extracted from Base.zip. The User folder is where all of your source scripts should and will be placed.

Where should compiled scripts be placed?

Compiled scripts do not belong anywhere in the Fallout 4\Data\Scripts\Source folder or subfolders. All compiled scripts should be placed in one of the following directories:

• Data\Scripts
• Data\Scripts\Fragments\*
• Data\Scripts\<namespace>\*

Compiling

How else can I compile scripts?

• You can compile scripts through the Script Manager. In the Script Manager, right-click the script and compile only that script.
• You can compile scripts outside the Creation Kit by calling the compiler directly from the command shell.

If I change the source script, do I need to recompile that script?

Yes. If you make changes to a .psc (Papyrus Source) file and never recompile, the game will always use the older .pex (Papyrus Executable) file, and your changes will never take effect.

When I try to compile scripts outside the Creation Kit, my scripts always fail to compile. I'm sure my syntax is correct!

For the sake of simplicity, use fireundubh's Windows batch script (.bat file) for compiling scripts outside the Creation Kit.

1. Save compile_fo4.bat to C:\Scripts. Create the directory if needed.
2. Update the paths at the top of the .bat script as needed.
3. Add C:\Scripts to your system's PATH environment variable. (Control Panel > System > Advanced System Settings > Environment Variables)

With this script, you can run the following commands from the command shell:

compile_fo4                       // compile all scripts in the current directory recursively and output the compiled scripts to the specified output directory  
compile_fo4 script.psc            // compile a single script in the current directory and output the compiled script to the specified output directory  
compile_fo4 script.psc --test     // the --test parameter will delete the compiled script after successfully compiling the script (useful for testing whether a script compiles)  
compile_fo4 C:\path\to\script.psc // compile a single script using the absolute path to the script and output the compiled script to the specified output directory  
compile_fo4 project.ppj           // compile the specified project file in the Projects directory  

What are all of the parameters for PapyrusCompiler.exe? What do they mean?

You can run PapyrusCompiler.exe on the command line without any parameters to get a list of all of the parameters and what they mean. That list has been replicated here.

Papyrus Compiler Version 2.8.0.4 for Fallout 4
Copyright (C) ZeniMax Media. All rights reserved.
Usage:
PapyrusCompiler <object, folder, or project> [<arguments>]

  object     Specifies the object to compile. (-all is not specified, with a
             .psc or no extension)
  folder     Specifies the folder to compile. (-all is specified)
  project    Specifies the project to compile. (Has a .ppj extension)
  arguments  One or more of the following (overrides project, if any):
   -debug|d
    Turns on compiler debugging, outputting dev information to the screen.
   -release|r
    Turns on release-mode processing, removing debug code from the script.
   -final
    Turns on final-mode processing, removing beta code from the script.
   -optimize|op
    Turns on optimization of scripts.
   -output|o=<string>
    Sets the compiler's output directory.
   -import|i=<string>
    Sets the compiler's import directories, separated by semicolons.
   -flags|f=<string>
    Sets the file to use for user-defined flags.
   -all|a
    Invokes the compiler against all psc files in the specified directory
    (interprets object as the folder).
   -norecurse
    Used with -all to tell the compiler not to recurse into subdirectories.
   -ignorecwd
    Tells the compiler to ignore the current working directory when searching
    for files. Otherwise it is implied to be first in the import list.
   -quiet|q
    Does not report progress or success (only failures).
   -noasm
    Does not generate an assembly file and does not run the assembler.
   -keepasm
    Keeps the assembly file after running the assembler.
   -asmonly
    Generates an assembly file but does not run the assembler.
   -?
    Prints usage information.

What is "debug code" and "beta code"?

Two new properties have been introduced in the Fallout 4 version of Papyrus: DebugOnly and BetaOnly. These properties can be declared at the function and script levels.

• When release-mode processing is enabled, the compiler will remove DebugOnly functions from the compiled script. The source file will remain untouched.
• When final-mode processing is enabled, the compiler will remove BetaOnlyfunctions from the compiled script. The source file will remain untouched.

These properties are useful when you want to run code during development that you don't want to run when your mod is in the wild.

Why doesn't my script output any debug messages to the Papyrus log?

The compiler is processing your script in release mode. The Debug script has the DebugOnly property, so all Debug functions (e.g., Debug.Notification, Debug.Trace) will be removed from your script when compiled.

The batch script provided above, and the Papyrus Project template provided below, enables release-mode and final-mode processing. To use DebugOnly and/or BetaOnly code, you'll need to modify these files as needed.

None of my scripts are running! / The Papyrus log indicates they're missing.

Add to %USERPROFILE%\Documents\My Games\Fallout4\Fallout4Custom.ini:

[Archive]    
bInvalidateOlderFiles=1

This will allow the game to load "loose files," which includes your scripts. Also, ensure that the paths to your compiled scripts are correct.

What is a namespace? How do I configure my mod to use a namespace?

For our purposes, a namespace is just a subfolder where your scripts are located for a specific mod in the User folder. Namespaces help you stay organized.

To set up a namespace, follow these instructions:

1. While in the Creation Kit: go to File > Preferences and find the Scripts tab.
2. In the box labeled Default namespace, enter the name of your namespace without any spaces or special characters.
3. Click Apply and then Close.

From now on, any scripts you create with the Creation Kit will be placed in that namespace folder, and the ScriptName declaration in each script will be prefixed with the name of your namespace.

When I try to compile namespaced scripts outside the Creation Kit, my scripts always fail to compile. Help!

Namespaced scripts and scripts with paths, usually fragment scripts, should be compiled using a Papyrus Project file, which is a plain text XML file with the .ppj extension that the Papyrus compiler natively understands.

PapyrusProject.xsd in the Fallout 4\Papyrus Compiler directory defines the XML schema for Papyrus Project files. Here is an example of a Papyrus Project file:

<PapyrusProject xmlns="PapyrusProject.xsd" Flags="Institute_Papyrus_Flags.flg" Output="D:\Steam\steamapps\common\Fallout 4\Data\Scripts" Optimize="true" Release="true" Final="true">  
  <Imports>  
    <Import>D:\Steam\steamapps\common\Fallout 4\Data\Scripts\Source\Base</Import>  
    <Import>D:\Steam\steamapps\common\Fallout 4\Data\Scripts\Source\User</Import>  
  </Imports>  
  <Scripts>  
  <Script>AutoLoot\Fragments\Terminals\TERM_dubhAutoLootMenuAdvance_0100272C.psc</Script>  
  ...  
  </Scripts>  
</PapyrusProject>

Logging

How do I enable the Papyrus log?

You can enable the Papyrus log by adding the following lines to %USERPROFILE%\Documents\My Games\Fallout4\Fallout4Custom.ini:

[Papyrus]
fPostLoadUpdateTimeMS=500.0000
bEnableLogging=1
bEnableTrace=1
bLoadDebugInformation=1

Can the Papyrus log help me figure out why Fallout 4 is crashing?

The Papyrus log is not a crash log. There is a warning at the top of the log now that states this quite clearly. The Papyrus log is not likely to point at what was going on near the crash because if a crash occurs, the game will be unable to write to the log.