Papyrus Project

The Papyrus compiler now supports project files in Fallout 4. A Papyrus Project is an XML format with a (.ppj) extension.

This allows you to easily build a set of files at once without having to run the compiler multiple times. This speeds up the editor build process when using the "Compile Papyrus Scripts" option, or building scripts after retrieving them from Perforce.

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.

Table of Contents

• Specification
• Examples

Specification

Papyrus projects are XML files with the (.ppj) extension. A PapyrusProject.xsd file has been provided in the compiler's folder for use with a 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.

Examples

Here are some examples of a Papyrus Project configuration.

Example 1

The project below 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\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>

Example 2

The project below 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.

<?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>