skyrim-esp

name

skyrim-esp

description

Create and modify Skyrim plugin files (.esp/.esl). Use when the user wants to create a mod, add weapons, armor, spells, perks, books, quests, NPCs, NPC AI packages (36 types for complete behavior control), factions, globals, leveled lists, encounter zones, locations, outfits, or form lists to a plugin. Includes quest aliases, script property management, type inspection, and detailed analysis. Also use when the user wants to view existing records, create override patches, search for records across plugins, manage perk conditions, compare record versions, or detect load order conflicts. Eliminates need for xEdit and Creation Kit for NPC behavior setup.

Skyrim ESP Module

Create, inspect, and modify Skyrim plugin files using the ESP module of Spooky's AutoMod Toolkit.

Prerequisites

Run all commands from the toolkit directory:

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

Command Reference

Create a Plugin

dotnet run --project src/SpookysAutomod.Cli -- esp create "<name>.esp" [options]

Option	Description
--light	Create as ESL-flagged light plugin
--author "Name"	Set author in header
--output "./path"	Output directory

Inspect a Plugin

dotnet run --project src/SpookysAutomod.Cli -- esp info "<plugin>"
dotnet run --project src/SpookysAutomod.Cli -- esp list-masters "<plugin>"

Add Records

Books (work immediately, no model needed):

dotnet run --project src/SpookysAutomod.Cli -- esp add-book "<plugin>" "<editorId>" --name "Name" --text "Content..." --value 50

Weapons (require --model to be visible):

dotnet run --project src/SpookysAutomod.Cli -- esp add-weapon "<plugin>" "<editorId>" --name "Name" --type sword --damage 25 --model iron-sword

Model presets: iron-sword, steel-sword, iron-dagger, hunting-bow

Armor (require --model to be visible):

dotnet run --project src/SpookysAutomod.Cli -- esp add-armor "<plugin>" "<editorId>" --name "Name" --type heavy --slot body --rating 40 --model iron-cuirass

Model presets: iron-cuirass, iron-helmet, iron-gauntlets, iron-boots, iron-shield

Spells (require --effect to function):

dotnet run --project src/SpookysAutomod.Cli -- esp add-spell "<plugin>" "<editorId>" --name "Name" --effect damage-health --magnitude 50 --cost 45

Effect presets: damage-health, restore-health, damage-magicka, restore-magicka, damage-stamina, restore-stamina, fortify-health, fortify-magicka, fortify-stamina, fortify-armor, fortify-attack

Perks (require --effect to function):

dotnet run --project src/SpookysAutomod.Cli -- esp add-perk "<plugin>" "<editorId>" --name "Name" --description "Effect" --effect weapon-damage --bonus 25 --playable

Effect presets: weapon-damage, damage-reduction, armor, spell-cost, spell-power, spell-duration, sneak-attack, pickpocket, prices

Quests:

dotnet run --project src/SpookysAutomod.Cli -- esp add-quest "<plugin>" "<editorId>" --name "Name" --start-enabled

Globals (configuration variables):

dotnet run --project src/SpookysAutomod.Cli -- esp add-global "<plugin>" "<editorId>" --type float --value 1.5

NPCs (record only - need race/face data for visibility):

dotnet run --project src/SpookysAutomod.Cli -- esp add-npc "<plugin>" "<editorId>" --name "Name" --level 20 --essential

NPC AI Packages (complete behavior system - 36 types supported):

# Basic behaviors
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type sandbox --radius 500
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type travel --marker "DestRef"
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type sleep --bed "BedRef" --start-hour 22 --duration 8
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type eat --furniture "ChairRef" --start-hour 12 --duration 2
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type follow --target "PlayerRef"
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type guard --marker "GuardRef"
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type patrol --marker "PatrolRef"

# Activities & actions
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type useitemat --item-ref "ForgeRef"  # Crafting
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type sit --furniture "ChairRef"
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type useidlemarker --marker "IdleRef"  # Sweeping, hammering
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type wander --marker "CenterRef" --radius 1000
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type wait --marker "WaitRef"

# Combat & magic
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type flee --distance 1500
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type useweapon --weapon-ref "WeaponRef" --target "TargetRef"
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type usemagic --spell-ref "SpellRef" --target "TargetRef"
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type shout --shout-ref "ShoutRef"

# Dialogue & social
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type forcegreet --target "PlayerRef"  # Quest interactions
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type greet --target "ActorRef"
dotnet run --project src/SpookysAutomod.Cli -- esp add-package "<plugin>" "<editorId>" --type say --topic-ref "TopicRef"

# Attach packages to NPCs (evaluated in order)
dotnet run --project src/SpookysAutomod.Cli -- esp attach-package "<plugin>" --npc "NpcEditorId" --package "PackageEditorId"

All 36 Types: sandbox, travel, sleep, eat, follow, guard, patrol, useitemat, activate, sit, useidlemarker, wander, wait, relax, flee, ambush, useweapon, usemagic, castmagic, shout, dialogue, forcegreet, greet, say, accompany, escortto, followto, acquire, find, holdposition, keepaneyeon, lockdoors, unlockdoors, dismount, hover, orbit

FormKey Format: Must be "FORMID:MODNAME" with exactly 6 hex digits (e.g., "000007:Skyrim.esm")

Factions (for tracking and organization):

dotnet run --project src/SpookysAutomod.Cli -- esp add-faction "<plugin>" "<editorId>" --name "Name" --flags "HiddenFromPC,TrackCrime"

LeveledItems (for random loot distribution):

# With preset
dotnet run --project src/SpookysAutomod.Cli -- esp add-leveled-item "<plugin>" "<editorId>" --preset low-treasure

# Custom with entries (format: item,level,count)
dotnet run --project src/SpookysAutomod.Cli -- esp add-leveled-item "<plugin>" "<editorId>" --chance-none 15 --add-entry "GoldBase,1,100" --add-entry "LockPick,5,3"

# Guaranteed multi-item drop
dotnet run --project src/SpookysAutomod.Cli -- esp add-leveled-item "<plugin>" "<editorId>" --use-all --add-entry "Sword,10,1" --add-entry "Shield,10,1"

Presets: low-treasure (25% none), medium-treasure (15% none), high-treasure (5% none), guaranteed-loot (0% none)

FormLists (for script property collections):

# Add vanilla forms by FormKey
dotnet run --project src/SpookysAutomod.Cli -- esp add-form-list "<plugin>" "<editorId>" --add-form "Skyrim.esm:0x000896"

# Add mod forms by EditorID
dotnet run --project src/SpookysAutomod.Cli -- esp add-form-list "<plugin>" "<editorId>" --add-form "MyWeapon01" --add-form "MyWeapon02"

# Use in scripts: FormList Property MyList Auto
# Set property: --property MyList --value "ModName.esp|0x800"

EncounterZones (for level scaling control):

# With preset
dotnet run --project src/SpookysAutomod.Cli -- esp add-encounter-zone "<plugin>" "<editorId>" --preset mid-level

# Custom with flags
dotnet run --project src/SpookysAutomod.Cli -- esp add-encounter-zone "<plugin>" "<editorId>" --min-level 30 --max-level 50 --never-resets

# Fully scaling (1-unlimited)
dotnet run --project src/SpookysAutomod.Cli -- esp add-encounter-zone "<plugin>" "<editorId>" --preset scaling

Presets: low-level (1-10), mid-level (10-30), high-level (30-50), scaling (1-unlimited) Flags: --never-resets (enemies stay dead), --disable-combat-boundary (NPCs pursue anywhere)

Locations (for quest markers and fast travel):

# With preset
dotnet run --project src/SpookysAutomod.Cli -- esp add-location "<plugin>" "<editorId>" --name "The Rusty Tankard" --preset inn

# With parent location
dotnet run --project src/SpookysAutomod.Cli -- esp add-location "<plugin>" "<editorId>" --name "My Shop" --preset dwelling --parent-location "WhiterunHoldLocation"

# Custom keywords
dotnet run --project src/SpookysAutomod.Cli -- esp add-location "<plugin>" "<editorId>" --name "Special Place" --add-keyword "LocTypeCity"

Presets: inn (LocTypeInn), city (LocTypeCity), dungeon (LocTypeDungeon), dwelling (LocTypeDwelling)

Outfits (for NPC equipment sets):

# With preset
dotnet run --project src/SpookysAutomod.Cli -- esp add-outfit "<plugin>" "<editorId>" --preset guard

# Custom items
dotnet run --project src/SpookysAutomod.Cli -- esp add-outfit "<plugin>" "<editorId>" --add-item "ArmorIronCuirass" --add-item "WeaponIronSword"

Presets: guard (iron armor + sword + shield), farmer (clothes), mage (robes + hood), thief (leather armor)

Record Management

List Records:

dotnet run --project src/SpookysAutomod.Cli -- esp list-records "<plugin>" --type <type> --limit 50

Supported types: weapon, armor, spell, perk, quest, npc, faction, book, global, leveleditem, formlist, outfit, location, encounterzone

Remove Record:

dotnet run --project src/SpookysAutomod.Cli -- esp remove-record "<plugin>" "<editorId>" --dry-run

Clone Record:

dotnet run --project src/SpookysAutomod.Cli -- esp clone-record "<plugin>" "<sourceEditorId>" "<newEditorId>" --dry-run

Quest Aliases

Quest aliases enable dynamic tracking of NPCs, objects, or locations. Essential for follower frameworks.

Add Alias with Script:

dotnet run --project src/SpookysAutomod.Cli -- esp add-alias "<plugin>" --quest "<questId>" --name "<aliasName>" --script "<scriptName>" --flags "Optional,AllowReuseInQuest"

Attach Script to Existing Alias:

dotnet run --project src/SpookysAutomod.Cli -- esp attach-alias-script "<plugin>" --quest "<questId>" --alias "<aliasName>" --script "<scriptName>"

Common flags: Optional, AllowReuseInQuest, AllowReserved, Essential, Protected

Script Management

Attach Script to Quest:

dotnet run --project src/SpookysAutomod.Cli -- esp attach-script "<plugin>" --quest "<questId>" --script "<scriptName>"

Set Script Property Manually:

dotnet run --project src/SpookysAutomod.Cli -- esp set-property "<plugin>" --quest "<questId>" --script "<scriptName>" --property "<propName>" --value "<formId>" --type object

Auto-Fill Properties (RECOMMENDED):

# Single script - parses PSC file and fills vanilla properties
dotnet run --project src/SpookysAutomod.Cli -- esp auto-fill "<plugin>" --quest "<questId>" --script "<scriptName>" --psc-file "<path>" --data-folder "<skyrim-data-path>"

# Bulk auto-fill ALL scripts (5x faster for multiple scripts)
dotnet run --project src/SpookysAutomod.Cli -- esp auto-fill-all "<plugin>" --script-dir "<source-dir>" --data-folder "<skyrim-data-path>"

What Auto-Fill Does:

• Parses PSC files to extract property names and types
• Searches Skyrim.esm with type-aware filtering
• Automatically fills matching vanilla properties
• Prevents wrong matches (e.g., Location vs Keyword with similar names)
• Supports array properties (creates ScriptObjectListProperty)

Analysis & Inspection

Basic Info:

dotnet run --project src/SpookysAutomod.Cli -- esp info "<plugin>"
dotnet run --project src/SpookysAutomod.Cli -- esp list-masters "<plugin>"

Type Inspection (Debug Mutagen Types):

dotnet run --project src/SpookysAutomod.Cli -- esp debug-types "<pattern>" --json

Examples: QuestAlias, Quest*, --all

Dry-Run Mode

Preview changes without saving:

dotnet run --project src/SpookysAutomod.Cli -- esp add-weapon "<plugin>" "<id>" --name "Test" --damage 30 --model iron-sword --dry-run --json

Available on all add-* commands.

SEQ File Generation

Required for start-enabled quests:

dotnet run --project src/SpookysAutomod.Cli -- esp generate-seq "<plugin>" --output "./SEQ"

Merge Plugins

dotnet run --project src/SpookysAutomod.Cli -- esp merge "<source>.esp" "<target>.esp" --output "Merged.esp"

Record Viewing and Override System

View, analyze, and create override patches for existing records without xEdit.

View Record Details

# View by EditorID (requires --type)
dotnet run --project src/SpookysAutomod.Cli -- esp view-record "<plugin>" --editor-id "<id>" --type <type>

# View by FormID (type inferred)
dotnet run --project src/SpookysAutomod.Cli -- esp view-record "<plugin>" --form-id "<formid>"

Supported Types: spell, weapon, armor, quest, npc, perk, faction, book, miscitem, global, leveleditem, formlist, outfit, location, encounterzone

Create Override Patches

# Create override patch (copies record to new plugin)
dotnet run --project src/SpookysAutomod.Cli -- esp create-override "<source>.esp" -o "<patch>.esp" --editor-id "<id>" --type <type>

The patch automatically:

• Adds source as master reference
• Preserves FormKey from original
• Loads after source in load order (wins conflicts)

Search for Records

# Search by pattern
dotnet run --project src/SpookysAutomod.Cli -- esp find-record --search "<pattern>" --type <type> --plugin "<plugin>"

# Search across all plugins in Data folder
dotnet run --project src/SpookysAutomod.Cli -- esp find-record --search "<pattern>" --type <type> --data-folder "C:/Skyrim/Data" --all-plugins

Batch Override Multiple Records

# Create overrides for all matching records
dotnet run --project src/SpookysAutomod.Cli -- esp batch-override "<source>.esp" -o "<patch>.esp" --search "<pattern>*" --type <type>

# Override specific records by EditorID list
dotnet run --project src/SpookysAutomod.Cli -- esp batch-override "<source>.esp" -o "<patch>.esp" --type <type> --editor-ids "ID1,ID2,ID3"

Compare Records

# Compare same record in two plugins
dotnet run --project src/SpookysAutomod.Cli -- esp compare-record "<plugin1>.esp" "<plugin2>.esp" --editor-id "<id>" --type <type>

Detect Conflicts

# Find which plugins modify a specific record
dotnet run --project src/SpookysAutomod.Cli -- esp conflicts "<data-folder>" --editor-id "<id>" --type <type>

# Check all conflicts for a plugin
dotnet run --project src/SpookysAutomod.Cli -- esp conflicts "<data-folder>" --plugin "<plugin>.esp"

Condition Management (Perks Only)

Note: Conditions only work on Perk, Package, IdleAnimation, and MagicEffect records.

List Conditions:

dotnet run --project src/SpookysAutomod.Cli -- esp list-conditions "<plugin>" --editor-id "<perkId>" --type perk

Add Condition:

# Add level requirement
dotnet run --project src/SpookysAutomod.Cli -- esp add-condition "<source>.esp" -o "<patch>.esp" --editor-id "<perkId>" --type perk --function GetLevel

# Common functions: GetLevel, IsSneaking, IsRunning, IsSwimming, IsInCombat

Remove Conditions:

# Remove conditions by index (get indices from list-conditions)
dotnet run --project src/SpookysAutomod.Cli -- esp remove-condition "<source>.esp" -o "<patch>.esp" --editor-id "<perkId>" --type perk --indices "0,2"

Common Workflows

Create a Complete Weapon Mod

# 1. Create plugin
dotnet run --project src/SpookysAutomod.Cli -- esp create "MyWeaponMod.esp" --light --author "YourName"

# 2. Add weapon with model
dotnet run --project src/SpookysAutomod.Cli -- esp add-weapon "MyWeaponMod.esp" "MyWeapon_Sword" --name "Blade of Power" --type sword --damage 35 --value 500 --model iron-sword

# 3. Verify
dotnet run --project src/SpookysAutomod.Cli -- esp info "MyWeaponMod.esp"

Create a Spell Pack

# Create plugin
dotnet run --project src/SpookysAutomod.Cli -- esp create "SpellPack.esp" --light

# Add damage spell
dotnet run --project src/SpookysAutomod.Cli -- esp add-spell "SpellPack.esp" "SP_Fireball" --name "Greater Fireball" --effect damage-health --magnitude 75 --cost 60

# Add healing spell
dotnet run --project src/SpookysAutomod.Cli -- esp add-spell "SpellPack.esp" "SP_Heal" --name "Major Healing" --effect restore-health --magnitude 100 --cost 50

# Add buff spell
dotnet run --project src/SpookysAutomod.Cli -- esp add-spell "SpellPack.esp" "SP_Fortify" --name "Warrior's Blessing" --effect fortify-health --magnitude 50 --duration 120 --cost 80

Create a Perk Overhaul

# Create plugin
dotnet run --project src/SpookysAutomod.Cli -- esp create "PerkMod.esp" --light

# Combat perks
dotnet run --project src/SpookysAutomod.Cli -- esp add-perk "PerkMod.esp" "PM_WeaponMaster" --name "Weapon Master" --description "+20% weapon damage" --effect weapon-damage --bonus 20 --playable

# Magic perks
dotnet run --project src/SpookysAutomod.Cli -- esp add-perk "PerkMod.esp" "PM_Efficiency" --name "Magical Efficiency" --description "Spells cost 25% less" --effect spell-cost --bonus 25 --playable

# Stealth perks
dotnet run --project src/SpookysAutomod.Cli -- esp add-perk "PerkMod.esp" "PM_Assassin" --name "Assassin's Strike" --description "3x sneak attack damage" --effect sneak-attack --bonus 200 --playable

Add Content to Existing Mod

# Check what's in the mod
dotnet run --project src/SpookysAutomod.Cli -- esp info "ExistingMod.esp"

# Add new content
dotnet run --project src/SpookysAutomod.Cli -- esp add-weapon "ExistingMod.esp" "NewWeapon" --name "Added Sword" --damage 30 --model steel-sword

# Verify addition
dotnet run --project src/SpookysAutomod.Cli -- esp info "ExistingMod.esp"

Create a Dungeon with Level Scaling

# Create plugin
dotnet run --project src/SpookysAutomod.Cli -- esp create "DungeonMod.esp" --light

# Create location
dotnet run --project src/SpookysAutomod.Cli -- esp add-location "DungeonMod.esp" "DM_Crypt" --name "Forgotten Crypt" --preset dungeon

# Create encounter zone
dotnet run --project src/SpookysAutomod.Cli -- esp add-encounter-zone "DungeonMod.esp" "DM_CryptZone" --preset mid-level --never-resets

# Create boss loot
dotnet run --project src/SpookysAutomod.Cli -- esp add-leveled-item "DungeonMod.esp" "DM_BossChest" --preset high-treasure

# Verify
dotnet run --project src/SpookysAutomod.Cli -- esp info "DungeonMod.esp"

Create NPCs with Custom Outfits

# Create plugin
dotnet run --project src/SpookysAutomod.Cli -- esp create "NPCMod.esp" --light

# Create custom outfit
dotnet run --project src/SpookysAutomod.Cli -- esp add-outfit "NPCMod.esp" "NM_GuardOutfit" --preset guard

# Create faction
dotnet run --project src/SpookysAutomod.Cli -- esp add-faction "NPCMod.esp" "NM_TownGuards" --name "Town Guards"

# Create NPC (outfit assigned in Creation Kit)
dotnet run --project src/SpookysAutomod.Cli -- esp add-npc "NPCMod.esp" "NM_GuardCaptain" --name "Captain Smith" --level 20 --essential

Create Form List for Script Property

# Create plugin
dotnet run --project src/SpookysAutomod.Cli -- esp create "ScriptHelpers.esp" --light

# Create form list with weapons
dotnet run --project src/SpookysAutomod.Cli -- esp add-form-list "ScriptHelpers.esp" "SH_AllWeapons" --add-form "MyWeapon01" --add-form "MyWeapon02"

# In your script, declare: FormList Property AllWeapons Auto
# Then auto-fill or manually set: --property AllWeapons --value "ScriptHelpers.esp|0x800"

Important Notes

1. Always use --model for weapons and armor - without it they'll be invisible
2. Always use --effect for spells and perks - without it they won't function
3. EditorIDs must be unique - use a prefix like MyMod_ to avoid conflicts
4. Light plugins (.esl) have a 2048 record limit but don't use a load order slot
5. Start-enabled quests require SEQ files - generate with generate-seq command
6. Use --json flag for machine-readable output when scripting

JSON Output

All commands support --json for structured output:

dotnet run --project src/SpookysAutomod.Cli -- esp info "MyMod.esp" --json