Skyrim Papyrus Module

Compile, decompile, validate, and generate Papyrus scripts using Spooky's AutoMod Toolkit.

Prerequisites

Run all commands from the toolkit directory:

cd "<TOOLKIT_PATH>"
# Example: cd "C:\Tools\spookys-automod-toolkit"

External Tools

Tools are auto-downloaded on first use:

Important: The toolkit uses russo-2025's modern compiler, NOT Bethesda's original PapyrusCompiler.exe.

Check tool status:

dotnet run --project src/SpookysAutomod.Cli -- papyrus status

Command Reference

Check Tool Status

dotnet run --project src/SpookysAutomod.Cli -- papyrus status

Download Tools

dotnet run --project src/SpookysAutomod.Cli -- papyrus download

Compile Scripts

dotnet run --project src/SpookysAutomod.Cli -- papyrus compile "<source>" --output "<dir>" --headers "<dir>"

Headers Path:

IMPORTANT: Script compilation requires Papyrus script headers (.psc files) from the Creation Kit.

Recommended approach:

1. Bethesda base game headers: Copy to ./skyrim-script-headers/
2. SKSE headers (optional): Copy to ./tools/papyrus-compiler/headers/skse/
3. SkyUI headers (optional): Copy to ./tools/papyrus-compiler/headers/skyui/
4. Use --headers "./skyrim-script-headers" in compile commands
5. See main README "Papyrus Script Headers" section for setup instructions

Alternative: Reference Creation Kit directly:

• Steam: C:/Program Files (x86)/Steam/steamapps/common/Skyrim Special Edition/Data/Scripts/Source
• GOG: C:/GOG Galaxy/Games/Skyrim Special Edition/Data/Scripts/Source

SKSE/SkyUI Headers:

• Required for mods using SKSE functions or MCM (SkyUI) menus
• SKSE SDK includes headers for native function calls
• SkyUI provides MCM Helper headers

If headers are missing, compilation will fail with "invalid type" errors.

Decompile Scripts

dotnet run --project src/SpookysAutomod.Cli -- papyrus decompile "<pex>" --output "<dir>"

Validate Script Syntax

dotnet run --project src/SpookysAutomod.Cli -- papyrus validate "<psc>"

Generate Script Template

dotnet run --project src/SpookysAutomod.Cli -- papyrus generate --name "<name>" --extends "<type>" --output "<dir>"

Base Types:

• Quest - Quest scripts
• Actor - Actor scripts
• ObjectReference - Object reference scripts
• MagicEffect - Magic effect scripts
• ActiveMagicEffect - Active magic effect scripts
• Alias - Alias scripts
• ReferenceAlias - Reference alias scripts
• LocationAlias - Location alias scripts

Common Workflows

Create and Compile a Quest Script

# 1. Generate script template
dotnet run --project src/SpookysAutomod.Cli -- papyrus generate --name "MyMod_QuestScript" --extends Quest --output "./Scripts/Source"

# 2. Edit the generated script (add your code)

# 3. Validate syntax before compiling
dotnet run --project src/SpookysAutomod.Cli -- papyrus validate "./Scripts/Source/MyMod_QuestScript.psc"

# 4. Compile to PEX
dotnet run --project src/SpookysAutomod.Cli -- papyrus compile "./Scripts/Source" --output "./Scripts" --headers "./skyrim-script-headers"

# 5. Attach to quest in plugin
dotnet run --project src/SpookysAutomod.Cli -- esp attach-script "MyMod.esp" --quest "MyMod_MainQuest" --script "MyMod_QuestScript"

# 6. Auto-fill script properties from PSC filedotnet run --project src/SpookysAutomod.Cli -- esp auto-fill "MyMod.esp" --quest "MyMod_MainQuest" --script "MyMod_QuestScript" --psc-file "./Scripts/Source/MyMod_QuestScript.psc" --data-folder "C:/Skyrim/Data"

Pro Tip: Auto-fill automatically populates vanilla properties (Keywords, Globals, etc.) by parsing your PSC file and searching Skyrim.esm. This saves significant manual work in the Creation Kit.

Decompile and Analyze Existing Scripts

# 1. Decompile a single script
dotnet run --project src/SpookysAutomod.Cli -- papyrus decompile "./Scripts/SomeScript.pex" --output "./Decompiled"

# 2. Decompile all scripts in a directory
dotnet run --project src/SpookysAutomod.Cli -- papyrus decompile "./Scripts" --output "./Decompiled"

# 3. Read the decompiled source to understand behavior

Create Magic Effect Script

# 1. Generate magic effect script template
dotnet run --project src/SpookysAutomod.Cli -- papyrus generate --name "MyMod_FireEffect" --extends ActiveMagicEffect --output "./Scripts/Source" --description "Fire damage over time effect"

# 2. Compile
dotnet run --project src/SpookysAutomod.Cli -- papyrus compile "./Scripts/Source/MyMod_FireEffect.psc" --output "./Scripts" --headers "./skyrim-script-headers"

Complete Workflow: Script with Auto-Filled Properties```bash

1. Create PSC file with vanilla property references

cat > "./Scripts/Source/MyMod_ConfigScript.psc" << 'EOF' ScriptName MyMod_ConfigScript extends Quest

Keyword Property LocTypeInn Auto Keyword Property LocTypeHouse Auto GlobalVariable Property GameDaysPassed Auto Faction Property PlayerFaction Auto

Event OnInit() Debug.Notification("Config initialized") EndEvent EOF

2. Compile script

dotnet run --project src/SpookysAutomod.Cli -- papyrus compile "./Scripts/Source/MyMod_ConfigScript.psc" --output "./Scripts" --headers "./skyrim-script-headers"

3. Attach to quest

dotnet run --project src/SpookysAutomod.Cli -- esp attach-script "MyMod.esp" --quest "MyMod_ConfigQuest" --script "MyMod_ConfigScript"

4. Auto-fill all vanilla properties from PSC

dotnet run --project src/SpookysAutomod.Cli -- esp auto-fill "MyMod.esp" --quest "MyMod_ConfigQuest" --script "MyMod_ConfigScript" --psc-file "./Scripts/Source/MyMod_ConfigScript.psc" --data-folder "C:/Skyrim/Data"

Output:

Filled property 'LocTypeInn' with Skyrim.esm:0x01CB87

Filled property 'LocTypeHouse' with Skyrim.esm:0x01CB88

Filled property 'GameDaysPassed' with Skyrim.esm:0x000038

Filled property 'PlayerFaction' with Skyrim.esm:0x0001DB9A

**Why This Matters:**
- Auto-fill uses **type-aware matching** to prevent wrong property assignments
- For example, it won't confuse `LocTypeInn` (Keyword) with `RiverwoodInn` (Location)
- Saves hours of manual property filling in Creation Kit
- Works with arrays: `Keyword[] Property AllLocTypes Auto`

## Script Template Examples

### Quest Script (OnInit)
```papyrus
ScriptName MyMod_QuestScript extends Quest
{Main quest controller}

;-- Properties --
GlobalVariable Property MyMod_Enabled Auto

;-- Events --
Event OnInit()
    If MyMod_Enabled.GetValue() == 1
        Debug.Notification("My Mod initialized!")
    EndIf
EndEvent

;-- Functions --
Function DoSomething()
    ; Your code here
EndFunction

Actor Script

ScriptName MyMod_ActorScript extends Actor
{Script attached to an actor}

Event OnLoad()
    Debug.Trace("Actor loaded: " + GetDisplayName())
EndEvent

Event OnDeath(Actor akKiller)
    Debug.Notification(GetDisplayName() + " was killed!")
EndEvent

ActiveMagicEffect Script

ScriptName MyMod_EffectScript extends ActiveMagicEffect
{Script for a magic effect}

Event OnEffectStart(Actor akTarget, Actor akCaster)
    Debug.Notification("Effect started on " + akTarget.GetDisplayName())
EndEvent

Event OnEffectFinish(Actor akTarget, Actor akCaster)
    Debug.Notification("Effect ended")
EndEvent

Troubleshooting Script Errors

Common Compilation Errors

"Compilation failed" with no details:

• The toolkit now shows detailed compiler output when compilation fails
• If you see this without details, it's a bug - report it with the command you ran

"Missing header files", "invalid type", or "unknown type":

• Script headers are NOT included with the toolkit (Bethesda copyright)
• You must install them manually - see README "Papyrus Script Headers" section
• Verify headers path points to ./skyrim-script-headers or Creation Kit location
• Headers must contain files like Actor.psc, Game.psc, Quest.psc, etc.
• Without headers, the compiler cannot understand base types and will fail

Compiler not found:

• Run papyrus status to check if compiler is installed
• Run papyrus download to install the compiler if missing

"Script extends unknown type":

• Ensure base type is spelled correctly
• Common types: Quest, Actor, ObjectReference, MagicEffect

"Property not found":

• Properties must be filled in the Creation Kit
• Use GlobalVariable Property MyVar Auto for globals

"Function not found":

• Check function exists in the parent type
• Papyrus is case-insensitive for identifiers

Decompilation Issues

"Failed to decompile":

• Some heavily obfuscated scripts may not decompile
• Try newer Champollion versions

Important Notes

1. Headers MUST be installed - Papyrus compilation will FAIL without script headers. See README for setup.
2. SKSE/SkyUI headers for advanced mods - Place in tools/papyrus-compiler/headers/{skse,skyui}/ for MCM menus and native functions
3. Scripts/Source vs Scripts - Source (.psc) goes in Source folder, compiled (.pex) in Scripts
4. Property auto-fill - Use esp auto-fill to automatically populate vanilla properties from PSC files instead of manual Creation Kit filling
5. Type-aware property matching - Auto-fill prevents wrong type matches (e.g., Location vs Keyword with similar names)
6. Case insensitivity - Papyrus identifiers are case-insensitive
7. Use --json flag for machine-readable output when scripting

JSON Output

All commands support --json for structured output:

dotnet run --project src/SpookysAutomod.Cli -- papyrus status --json