using-bgs-papyrus

Using bgs-papyrus

bgs-papyrus is the agent-native CLI for Papyrus compile and decompile work. It detects official Creation Kit compilers, compiles .psc to .pex, decompiles .pex to .psc through Champollion, and returns JSON envelopes for agent workflows.

Use this skill for:

• compiling Papyrus source to bytecode for Skyrim LE, Skyrim SE/AE, Fallout 4, or Starfield;
• decompiling Papyrus bytecode to source for inspection or patching;
• detecting whether the official Creation Kit compiler and Champollion are available;
• handling Starfield Guard syntax produced by Champollion.

Do not use this skill for plugin record edits, load-order edits, or BA2/BSA packing. Route those through the xEdit, load-order, or archive skills.

Prerequisites — detect first

Always query the live CLI before choosing a backend or game path:

bgs-papyrus capabilities --json
bgs-papyrus detect-toolchain --json --game starfield

The official Creation Kit must be installed by the user from Steam. Bethesda's PapyrusCompiler.exe is not bundled with this plugin and must not be copied into the repo or plugin tree. bgs-papyrus detects and drives the installed compiler.

Champollion is used for decompile. bgs-papyrus detects Champollion; it does not download it automatically. Install Champollion.exe at:

~/.bgs-modding-superpowers/tools/champollion/Champollion.exe

or the user can set BGS_PAPYRUS_CHAMPOLLION to an existing executable.

One PowerShell install shape for Champollion v1.3.2 from Orvid/Champollion releases:

$root = "$HOME\.bgs-modding-superpowers\tools\champollion"; New-Item -ItemType Directory -Force -Path $root | Out-Null; $zip = Join-Path $root "Champollion.v1.3.2.zip"; Invoke-WebRequest "https://github.com/Orvid/Champollion/releases/download/v1.3.2/Champollion.v1.3.2.zip" -OutFile $zip; Expand-Archive -Force $zip $root

Human manuals:

• English: tools/bgs-papyrus/USER-GUIDE.en.md
• Chinese: tools/bgs-papyrus/USER-GUIDE.zh-cn.md

Hard rules

• Never write compiled .pex output into the game's Data folder or any Stock-Game tree.
• Game-ready compiled output belongs in an MO2 mod overlay: <MO2_Root>/mods/<mod-name>/Scripts/.
• Use --json for agent workflows and branch on the envelope, not human text.
• Detect the toolchain before compile/decompile. Do not guess that a compiler path exists.
• Starfield compile should use the official CK compiler for Guard syntax. Caprica and russo are non-Guard fallbacks.

Commands

Check bgs-papyrus --help and <subcommand> --help for the current option surface. The examples below are templates.

capabilities

Discover supported games, subcommands, backends, flags files, and Starfield syntax behavior.

bgs-papyrus capabilities --json

detect-toolchain [--game G]

Find installed official CK compilers and the Champollion decompiler.

bgs-papyrus detect-toolchain --json --game fallout4
bgs-papyrus detect-toolchain --json

Supported game arguments are skyrimle, skyrimse, fallout4, and starfield. Fallout 3, Fallout: New Vegas, and Oblivion do not use Papyrus and are out of scope.

compile <src> --game G

Compile one .psc file, or use --all for a directory.

bgs-papyrus compile "D:\work\Scripts\Source\MyQuestScript.psc" --json --game starfield --out "D:\work\compiled" --import "D:\work\Scripts\Source"

Useful options:

• --out <dir>: output directory.
• --import <dir>: source import directory; repeat for multiple roots.
• --backend ck|caprica|russo|auto: compiler backend.
• --flags <file>: explicit flags file.
• --optimize, --release, --final, --all: compile options.

For final game use, copy the resulting .pex into an MO2 overlay:

<MO2_Root>/mods/<mod-name>/Scripts/

Never write the result to <game>/Data/Scripts/ directly.

decompile <src> --game G

Decompile one .pex file, or use --recursive for a directory.

bgs-papyrus decompile "D:\mods\Example\Scripts\MyQuestScript.pex" --json --game starfield --out "D:\work\decompiled"

Useful options:

• --out <dir>: output directory.
• --recursive: decompile a directory tree.
• --threaded: use Champollion threaded mode where supported.
• --sf-syntax-fix / --no-sf-syntax-fix: enable or disable Starfield syntax post-processing.

Starfield specifics

The official Starfield CK compiler handles Guard syntax natively. Champollion v1.3.2 guesses some Guard syntax in a form that the CK does not accept, so bgs-papyrus applies a validated Starfield syntax post-process during decompile:

Guard ... EndGuard       -> LockGuard ... EndLockGuard
TryGuard ... EndGuard    -> TryLockGuard ... EndTryLockGuard

This Guard rewrite was checked by recompiling the decompiled output through the real Starfield CK compiler.

Known limitation: Champollion v1.3.2 has unrelated decompile bugs, such as remote-event casts, that can stop complex vanilla scripts from recompiling cleanly. Treat decompiled output as a strong starting point and manually fix compiler-rejected constructs. The Guard post-processor is validated; this limitation is upstream Champollion.

Safe workflow pattern

1. Run bgs-papyrus capabilities --json.
2. Run bgs-papyrus detect-toolchain --json --game <game>.
3. Compile or decompile with --json.
4. For compile output, stage final .pex files only under <MO2_Root>/mods/<mod-name>/Scripts/.
5. For decompile output intended for reuse, recompile it through the official CK compiler before claiming it is publishable.