Script File Structure

<header line>
(<import>|<variable definition>|<property definition>|<state definition>|<function definition>|<event definition>)*

A Papyrus script is a text file with the extension ".psc" that consists of a header line at the beginning of the file, followed by a collection of imports, variables, properties, states, functions, and events. The order of these elements is not important as long as the header line is the first non-comment line in the file.

Header Line

<Header Line> ::= 'ScriptName' <identifier> ['extends' <identifier>] (<flags>)*

The header line of the script consists of the keyword "ScriptName" followed by the identifier of the script (which must match the name of the file).

If the script extends another script, then the name of the script is followed by the "Extends" keyword and the name of the script it extends. And finally, by any flags.

Script Extension

Extending another script will let you override its functions and events to do something different, or add additional functionality while keeping the functionality of the older script. The only limitations are that any function or event in the child script whose name matches one in the parent script must have the same return type and parameter list.

Examples

; MyScript.psc
ScriptName MyScript

; HiddenScript.psc This script is hidden from the editor's normal script list, and extends ParentScript
ScriptName HiddenScript Extends ParentScript Hidden

Contents

The rest of the file, after the header, consists of imports, variable definitions, properties, states, functions, and events in any order. You do not have to define script variables, properties, functions, states, and events before you use them in the script. (Variables in functions and events, however, must be defined before use)

Imports

'Import' <identifier>

The "Import" keyword lets you use global functions in a script without prefixing them with the name of the script they are in. Simply use "Import" followed by the name of the script to import. If a function with the same name exists in both then you will still have to prefix it with the name of the script which contains the version you want.

Examples

; Call MyGlobal() in Utility, with no import
Function MyFunction()
  Utility.MyGlobal()
EndFunction

; Call MyGlobal() in Utility, with import
import Utility

Function MyFunction()
  MyGlobal()
EndFunction

Whitespace

Whitespace in Papyrus is unimportant, with the exception of line terminators which are explained below. Whitespace may be inserted anywhere as long as it doesn't split up a keyword, operator, literal or similar.

Examples

; Valid use of white space (if perhaps not as readable)
x     =    (10+1*    2 ) as   float

; Whitespace between the two equals signs in an equality operator will be interpreted as two equals signs, and fail to compile
x = = 1

; Whitespace between the 10 and 12 is interpreted as two numbers, 10 and 12, and not a single number 1012, and fail to compile
10 12

Line Terminators

Papyrus scripts are delineated into lines which determine where one statement ends and another begins. However, if you have a particularly long statement that you want to put on multiple lines, then you can add a "\" character to the end of the line and continue it on the next line. Slash characters inside comments are ignored (because everything in a comment is ignored), but you can put a comment after the slash if you wish

Examples

; Two statements separated by a line terminator
x = 1 + 2
y = 2 * 3

; One long statement broken into two lines
x = 1 + 2 \
  + 3 + 4

; Slash in this line is ignored, because it is in a comment \
x = 1 + 2 ; This line isn't inside the above comment

Comments

Comments in Papyrus come in three forms: Single line, multi-line, and documentation

Single-line Comments

<single line comment> ::= ';' <any text> <end of line>

Single line comments start with ";" and go until the end of the line. They consume all text after the semicolon, including any backslash characters that would otherwise let you continue onto the following line.

Examples

; A simple single line comment

Multi-line Comments

<multi-line comment> ::= ';/' <any text> '/;'

Multi-line comments start with ";/" and consume any text (including newlines) until it finds "/;"

Examples

;/ A simple
Multi-line comment /;
;/ You can also have code in here, if you want to comment it out:
x = 2 * 1
y.DoCoolStuff()
/;

Documentation Comments

<documentation comment> ::= '{' <any text> '}'

Documentation comments are special and can only appear on the line following a script header, property definition, or function definition. Documentation comments start at a "{" character and go until the terminating "}" character, including eating newlines and such. These comments show up as tooltips in the editor when you mouse over the script in the script picker, or when mousing over a property in the property editor.

Examples

ScriptName MyCoolScript
{Documentation for my cool script here!
I can even use more than one line...}

int Property MyProperty Auto
{This property is fun, if you set it to 1, watch cool stuff happen!}