Papyrus Projects

Overview

Papyrus projects allow you to specify several script files to compile at once with various settings. This not only makes the command line a little cleaner, but also can speed up compilation of several files at once, as the compiler can use multiple threads and re-use compilation results. Command line options given to the compiler override any conflicting settings in a project file.

Building With a Project

To build with a project, use the following syntax:

PapyrusCompiler MyProject.ppj [other options]

The extension must be specified (it's how the compiler differentiates between a script and a project). Any command line options passed to the compiler will override the settings in the project.

File Format

Papyrus projects are XML files with the .ppj extension. A PapyrusProject.xsd file has been provided in the compiler's folder for use with your favorite text editor to provide validation and auto-completion (depending on your editor). The basic project file consists of the <PapyrusProject> root element, followed by an <Imports> block, then a <Folders> block, and finally a <Scripts> block. (Any of which can be omitted if not necessary)

Please note that XML elements are case-sensitive, though the paths and filenames they refer to are not. Also, relative paths in the project file are relative to the project file itself, not the directory where you ran the compiler from.

PapyrusProject Element

This is the root element of the project file and will also usually contain the XML namespace attribute, set to "PapyrusProject.xsd" (case-sensitive). Other possible attributes are as follows (all optional):

• Output: The folder to output all compile results to
  • Default: Current working directory where the compiler was run from
• Flags: The flags file to use
  • Default: ""
• Asm: Specifies the assembly mode, which is one of the following:
  • None: No assembly produced and assembler not run (no output, compiler will do all validation, but not output any results)
  • Keep: Keep assembly output from the compiler
  • Only: Output assembly from the compiler, but don't assemble it into a pex file
  • Discard: Discard the assembly output after assembling it into a pex.
  • Default: Discard
• Optimize: Specifies whether to optimize the output of the compiler (XML boolean value)
  • Default: false
• Release: Specifies whether to do release processing on the compiler output - removing debugOnly functions (XML boolean value)
  • Default: false
• Final: Specifies whether to do final processing on the compiler output - removing betaOnly functions (XML boolean value)
  • Default: false

The project element then may contain a <Imports> element, a <Folders> element, and a <Scripts> element, in that order. (At least one folder or one script must be specified)

Imports Element

The imports element, if it exists, must be the first in the <PapyrusRoot> element. It consists of several <Import> elements which specify the folders the compiler should use for importing, paths relative to the project file (not the current working directory). Neither <Imports> nor <Import> have any attributes.

Files in import folders listed first will override matching files in import folders listed last. This is useful if, for example, your mod is dependent on a DLC or another mod with scripts, so you'll want to list the root folder for the item you're dependent on before the base script folder.

Folders Element

The folders element, if it exists, must be after the <Imports> element in the <PapyrusRoot> element. It consists of several <Folder> elements which specify the folders containing scripts the compiler should compile (path relative to the project file).

Folder Element

The folder element exists in the <Folders> element and gives a single folder the compiler should build (path relative to the project file). It contains only one optional attribute: NoRecurse, which is an XML boolean that prohibits the compiler from recursing into child folders when building. (Defaults to false)

Scripts Element

The scripts element, if it exists, must be the last in the <PapyrusRoot> element. It consists of several <Script> elements which specify the script files the compiler should build. Namespaces may be specified using path separators or colons. File extension is optional.

Project Examples

 <?xml version='1.0'?>
 <PapyrusProject xmlns="PapyrusProject.xsd"
   Flags="Institute_Papyrus_Flags.flg"
   Output="C:\Program Files (x86)\Steam\steamapps\Fallout 4\Data\Scripts"
 >
   <Imports>
     <Import>C:\Program Files (x86)\Steam\steamapps\common\Fallout 4\Data\Scripts\Source\User</Import>
     <Import>C:\Program Files (x86)\Steam\steamapps\common\Fallout 4\Data\Scripts\Source\Base</Import>
   </Imports>
   <Scripts>
     <Script>MyQuestScript</Script>
     <Script>Alias1Script</Script>
     <Script>Alias2Script</Script>
   </Scripts>
 </PapyrusProject>

The above project builds MyQuestScript, Alias1Script, and Alias2Script as a set, using imports, output, and flags file that most Institute builds will use.

 <?xml version='1.0'?>
 <PapyrusProject xmlns="PapyrusProject.xsd"
   Flags="Institute_Papyrus_Flags.flg"
   Output="C:\Program Files (x86)\Steam\steamapps\common\Fallout 4\Data\Scripts"
   Optimize="true"
   Release="true"
 >
   <Imports>
     <Import>C:\Program Files (x86)\Steam\steamapps\common\Fallout 4\Data\Scripts\Source\User</Import>
     <Import>C:\Program Files (x86)\Steam\steamapps\common\Fallout 4\Data\Scripts\Source\DLC01</Import>
     <Import>C:\Program Files (x86)\Steam\steamapps\common\Fallout 4\Data\Scripts\Source\Base</Import>
   </Imports>
   <Folders>
     <Folder>.</Folder>
   </Folders>
 </PapyrusProject>

The above project builds all scripts in the project's folder, recusing into child folders, using settings common to Institute builds, but also optimizing and building for release. It will also pull in any DLC01 source files which will override same-named files in the base folder.

See Also

• Papyrus Compiler Reference