WarpShell V2 Alpha

WarpShell is a visual workflow recorder for Skyrim Papyrus modding.

It records command runs as timeline ticks, lets you replay saved output, branch from earlier points, overwrite future ticks when you choose to, and save repeatable compiler workflows as profiles.

This is an alpha preview. It is useful for testing the workflow and building Papyrus command pipelines, but it is not a full terminal emulator yet.

Quick Start

1. Install Python 3.11 or newer.
2. Double-click Launch WarpShell V2 Alpha.bat.
3. Select sample-papyrus-project in Branch History.
4. Click ticks in the timeline to inspect saved output.
5. Click Replay Logs to watch saved output without running anything.
6. Double-click profile 01_fake_compile_clean to run a safe fake compile.

The included profiles use the included fake compiler and fake mod. They do not touch Skyrim.

What Is Included

• WarpShell Workbench GUI.
• Live Shell input for real command execution.
• Tick timeline with rewind, replay, branch, rerun, overwrite, and delete workflows.
• Branch History tree with nested branches.
• Code / Recipe Editor for command batches and text files.
• Profiles for saved command recipes.
• Output panel with red/green activity indicator.
• Fake Papyrus compiler for safe testing.
• Fake Skyrim mod sample project.
• Seed sample sessions, branches, and profiles.
• Reset script for restoring the sample workspace.
• Optional legacy command-line scripts.

Live Vs Replay

WarpShell has two different modes:

• Live execution runs commands on your machine and records results as ticks. The activity dot is red.
• Replay Logs shows saved stdout/stderr from existing ticks only. It does not run commands or write new ticks. The activity dot is green.
• Idle mode shows no activity dot.

Use Replay Logs when you only want to inspect history. Use the Live Shell, profile Run, Run Tick, Run To Tick, or Run Recipe when you want real execution.

Main GUI Controls

Top toolbar:

• Refresh: reload saved sessions and profiles from disk.
• New Session: create a blank timeline.
• Stop: stop an active live run or replay.
• Halt on error: when enabled, command batches stop on the first non-zero exit code.

Branch History:

• Select a session or branch to load its timeline.
• Nested rows show branches created from earlier ticks.
• Delete moves the selected session JSON into sample_warp_home/deleted.
• Branch History does not execute commands by itself.

Tick Timeline:

• Rewind: show saved output up to the selected tick.
• Replay Logs: play saved output without executing commands.
• Back / Forward: move the selected tick.
• Branch From Tick: create a child branch from the selected tick.
• Run Tick: rerun the selected command and replace that tick's saved result.
• Run To Tick: rerun from the first tick through the selected tick and replace those saved results.
• Delete Tick: remove a tick and renumber later ticks.

Code / Recipe Editor:

• Open File: open a script or command text file.
• Save File: save editor contents.
• Load Branch: load the current timeline commands into the editor.
• Run Recipe: run the editor commands as a fresh recipe session starting at tick 1.
• Save Profile: save editor commands as a named profile.
• Save Branch Profile: save the loaded branch commands as a profile.

Profiles:

• Single-click a profile to load its commands into the editor.
• Double-click a profile or click Run to run it as a fresh profile session.
• Delete removes the selected profile.

Output / Live Shell:

• Clear: clear the output pane.
• Replay: replay saved logs for the selected timeline.
• Type a command and press Enter to run it live.
• Up and Down move through command history.
• clear and cls clear the output pane.

Timeline Fork Prompt

If you select an earlier tick while later ticks already exist, then run a new Live Shell command, WarpShell asks what to do:

• Branch: create a child branch from the selected tick and run the new command there.
• Overwrite: delete the future ticks from the current timeline and run the new command as the next tick.
• Cancel: leave the timeline unchanged and keep the command in the input box.

This prevents accidental tick 7 / tick 8 style appends when you meant to work from tick 4.

Included Sample Sessions

sample-papyrus-project

Base workflow with four ticks:

1. Change into the fake mod folder.
2. List source files.
3. Run a clean fake compile for two scripts.
4. List fake build outputs.

warning_review @ tick 2

A branch from the base session at tick 2. It compiles WSA_Utility.psc, which contains an intentional warning marker.

broken_script_test @ tick 3

A nested branch from warning_review at tick 3. It compiles WSA_BrokenExample.psc, which contains an intentional error marker so you can test failure handling.

Included Sample Profiles

01_fake_compile_clean

Runs the fake compiler against two sample scripts. One script emits a warning, but the build succeeds.

02_fake_compile_with_error

Runs the fake compiler against the intentionally broken script. This is useful for testing halt-on-error behavior.

03_clean_then_compile_all

Deletes fake build output, then compiles every .psc under the sample source folder.

04_show_fake_build_outputs

Lists the generated fake .pex files.

Fake Compiler

The fake compiler is here:

tools/fake_papyrus_compiler.py

Example:

python "%WARPSHELL_PACKAGE%tools\fake_papyrus_compiler.py" scripts\Source --recursive -i scripts\Source -o build\Scripts --strict

It scans .psc files and:

• prints warnings for lines containing ; WARN:
• fails for lines containing ; ERROR:
• writes fake .pex text files into the output folder

Useful options:

• --recursive: compile .psc files in subfolders.
• --clean: delete the output folder before compiling.
• --strict: print stricter demo output.
• --fail-on-warning: treat warnings as failures.

Folder Layout

Warpshell V2 alpha/
  Launch WarpShell V2 Alpha.bat
  Reset Sample Data.bat
  README.md
  INSTRUCTION_MANUAL.md
  VERSION.txt
  LICENSE.txt
  warpshell/
    warp_gui.py
    warpshell.py
    replay.py
    session_store.py
  tools/
    fake_papyrus_compiler.py
  examples/
    FakeSkyrimMod/
  sample_warp_home_seed/
    profiles.json
    sessions/
    deleted/

Data Location

The launcher sets:

WARPSHELL_HOME=sample_warp_home
WARPSHELL_PACKAGE=this package folder

On first launch, the launcher recreates sample_warp_home from sample_warp_home_seed if the live sample workspace is missing.

That means the shipped build uses package-local sample data by default without needing a prebuilt live workspace in the zip.

If you run warpshell/warp_gui.py directly without the launcher, WarpShell stores data in:

%USERPROFILE%\.warp

For Nexus users, using the launcher is recommended.

Reset Samples

If the sample data gets messy, run:

Reset Sample Data.bat

This restores sample_warp_home from sample_warp_home_seed.

If sample_warp_home does not exist yet, the launcher creates it automatically from the seed folder before opening the GUI.

Optional Command-Line Scripts

The GUI is the intended V2 Alpha experience, but the package still includes the older Python scripts:

• warpshell.py: typed command recorder.
• replay.py list: list saved sessions.
• replay.py replay <session>: show saved logs.
• replay.py replay <session> --execute: re-execute saved commands live.
• replay.py rewind <session> <tick>: inspect or branch from an earlier tick.

Most users should start with Launch WarpShell V2 Alpha.bat.

Alpha Limitations

• WarpShell is not a full terminal emulator.
• Some deeply interactive console programs may behave differently than they do in native CMD or PowerShell.
• cd persists inside WarpShell, but arbitrary shell state changes may not.
• Profiles are plain command lists, not a full build-system language.
• There is no built-in Papyrus compiler path discovery yet.
• There is no packaged .exe yet.
• The fake compiler is only for testing the UI and workflow.

Suggested Nexus Description

WarpShell V2 Alpha is a visual Papyrus workflow recorder for Skyrim mod authors. It records command timelines, replays saved compiler output, branches from earlier ticks, saves build profiles, and includes a fake Papyrus project so users can test the workflow before wiring it into a real mod setup.

Support Notes

When reporting issues, include:

• Windows version
• Python version
• what button or command was used
• the selected session or branch name
• the session file from sample_warp_home/sessions
• any output shown in the Live Shell panel