SuperAPI AI Directory

skyrim-papyrus-modding

Coding & development

View repository

Updated 10-30 16:18

About this skill

Papyrus modding

Required inputs

  • Exact Skyrim runtime and compiler.
  • Source script, import roots, flags file, and output directory.
  • Owning quest, alias, magic effect, or form.
  • Required script-extender libraries and versions.
  • Save-upgrade expectations.

Architecture rules

  • Choose the smallest lifecycle owner that matches the behavior.
  • Prefer events and registered callbacks over polling loops.
  • Unregister listeners and timers when the object stops owning them.
  • Avoid expensive work in frequently firing events.
  • Treat properties and VMAD attachment as part of the plugin contract.
  • Use Game.GetFormFromFile or a verified soft-dependency pattern when a dependency is optional.
  • Preserve property names and persisted state across updates unless a migration is provided.
  • Use MCM Helper as the default for new configuration menus when the installed stack supports it; verify its exact schema from installed examples. Maintain SKI_ConfigBase as a legacy fallback and do not auto-migrate an existing menu without a save/configuration migration plan.
  • Ship a debug switch from the first build (an MCM toggle or GlobalVariable, off by default). When it is on, write through one helper to Debug.OpenUserLog("<ModName>") / Debug.TraceUser("<ModName>", msg): the mod version on init and update, resolved settings, state changes and every failed lookup or soft dependency. Tell the user the file is Documents\My Games\Skyrim Special Edition\Logs\Script\User\<ModName>.0.log and needs [Papyrus] bEnableLogging=1 (plus bEnableTrace=1 for Debug.Trace).

Workflow

  1. Map the script lifecycle and all external calls.
  2. Inspect the exact declaration scripts for every dependency.
  3. Implement source changes in the versioned workspace.
  4. Compile with explicit import order. Use scripts/compile_papyrus.ps1 or the project's equivalent.
  5. Treat a successful compile as necessary but not sufficient.
  6. Check VMAD attachment, properties, event registration, save upgrade, and runtime logs.
  7. Package matching PSC and PEX policy intentionally. Do not ship stale PEX files.

Adult projects

Preserve explicit technical strings, events, and intended adult-only behavior. Do not sanitize the implementation. Exclude child races, child actors, age-ambiguous characters, and real-person sexual content from adult systems.

Evidence standard

Use this hierarchy for version-sensitive facts:

  1. The active project's ENVIRONMENT.md, TASK.md, installed framework version, and build files.
  2. Official upstream documentation or source for that exact version.
  3. Known-good files from the user's installed mod library, read-only.
  4. Direct inspection of the relevant ESM, ESP, DLL, script, log, or archive.

Do not substitute memory, an old example, or a plausible token. Record the evidence path or URL in VALIDATION.md.

Runtime storage references

  • references/papyrusutil.md
  • references/jcontainers.md
  • references/runtime-data-storage-selection.md