Add Papyrus build and staging

Compile active Papyrus scripts during build and deploy flows, stage compiled `.pex` and source `.psc` files into the mod package, and update setup/dev docs plus changelog for the new workflow.

build-all.bat

@@ -2,6 +2,7 @@
 setlocal EnableExtensions
 
 set "SCRIPT_DIR=%~dp0"
+set "PAPYRUS_RESULT=0"
 
 echo Building Commonwealth Online plugin...
 call "%SCRIPT_DIR%build.bat"
@@ -12,11 +13,24 @@ echo Building PrismaUI_F4...
 call "%SCRIPT_DIR%build-prismaui.bat"
 if errorlevel 1 exit /b 1
 
+echo.
+echo Compiling Papyrus scripts...
+call "%SCRIPT_DIR%compile-papyrus.bat" "%~1"
+if errorlevel 1 set "PAPYRUS_RESULT=1"
+
 echo.
 echo Staging mod package...
 call "%SCRIPT_DIR%stage-mod.bat"
 if errorlevel 1 exit /b 1
 
+if "%PAPYRUS_RESULT%"=="1" (
+    echo.
+    echo Papyrus compilation failed, but the repo build folder was staged for inspection:
+    echo   %SCRIPT_DIR%build\Fallout 4\Data
+    echo Fix the Papyrus compile errors before deploying.
+    exit /b 1
+)
+
 echo.
 echo All builds finished. Mod package is in:
 echo   %SCRIPT_DIR%build\Fallout 4\Data

changelog.md

@@ -10,6 +10,10 @@ For testing notes, milestone summaries, known issues, and next steps, see [`docs
 ## [Unreleased]
 
 ### Added
+- `compile-papyrus.bat` to compile active Papyrus sources from `creation-kit\scripts\source` into `creation-kit\scripts\compiled` using the Fallout 4 Creation Kit Papyrus compiler, resolving the Fallout 4 install with the same path workflow as `deploy-all.bat`, using saved `.fallout4-path` values without re-prompting during builds, and skipping reference-only `CoSync*.psc` files.
+- `build-all.bat` now compiles Papyrus scripts before staging the mod package, and still stages the repo build folder for inspection when Papyrus compilation fails.
+- `deploy-all.bat` now resolves the Fallout 4 path, compiles Papyrus scripts, stages the repo build folder, and then deploys from `build\Fallout 4\Data` into the Fallout 4 `Data` folder.
+- `stage-mod.bat` now stages active Papyrus scripts recursively: compiled `creation-kit\scripts\compiled\*.pex` into `Data\Scripts` and raw `creation-kit\scripts\source\*.psc` into `Data\Scripts\Source\User`, while skipping reference-only `CoSync*` files.
 - Server-authoritative weather and time control via `serverWorldState` packets from the dev server GUI.
 - **Weather / Time** tab in `server/dev_server_app.py` with preset buttons for `fw` weather form IDs and `set gamehour to HHmm` time values.
 - `server/world_state_presets.py` with shared weather and time preset definitions.
@@ -18,6 +22,7 @@ For testing notes, milestone summaries, known issues, and next steps, see [`docs
 - `timeSync` tracking in `server/fake_client.py` host world-state snapshot output.
 
 ### Fixed
+- Fixed Papyrus staging path construction so `.pex` and `.psc` files are copied into `build\Fallout 4\Data\Scripts` and `build\Fallout 4\Data\Scripts\Source\User`.
 - If a server profile exists but its associated save was deleted, joining from the main menu now falls back to first-time character creation and re-binds the profile to the newly created save instead of hard-failing.
 - Pending first-time profile binding now completes as soon as a save exists even if character-creation phase flags are still active, preventing repeated `coc` first-time launches on reconnect.
 - Session launch now resolves equivalent server endpoints (for example `localhost`, `127.0.0.1`, and legacy host-case variants) to an existing server profile before deciding first-time join flow, preventing unintended new-character creation when reconnecting.

compile-papyrus.bat

@@ -0,0 +1,87 @@
+@echo off
+REM compile-papyrus.bat [Fallout 4 install path]
+REM Compiles creation-kit/scripts/source/*.psc into creation-kit/scripts/compiled/*.pex.
+setlocal EnableExtensions EnableDelayedExpansion
+
+set "SCRIPT_DIR=%~dp0"
+set "SCRIPTS_SOURCE_DIR=%SCRIPT_DIR%creation-kit\scripts\source"
+set "SCRIPTS_COMPILED_DIR=%SCRIPT_DIR%creation-kit\scripts\compiled"
+set "CONFIG=%SCRIPT_DIR%.fallout4-path"
+set "RESOLVE_INPUT=%~1"
+if not defined RESOLVE_INPUT if defined FALLOUT4_PATH set "RESOLVE_INPUT=%FALLOUT4_PATH%"
+if not defined RESOLVE_INPUT if exist "%CONFIG%" set /p "RESOLVE_INPUT=" < "%CONFIG%"
+
+call "%SCRIPT_DIR%resolve-fallout4-path.bat" "%RESOLVE_INPUT%"
+if errorlevel 1 exit /b 1
+
+set "PAPYRUS_COMPILER=%PAPYRUS_COMPILER_EXE%"
+if not defined PAPYRUS_COMPILER set "PAPYRUS_COMPILER=%F4_DIR%\Papyrus Compiler\PapyrusCompiler.exe"
+
+set "PAPYRUS_FLAGS=%DATA_DIR%\Scripts\Source\Base\Institute_Papyrus_Flags.flg"
+set "PAPYRUS_IMPORTS=%SCRIPTS_SOURCE_DIR%;%DATA_DIR%\Scripts\Source\User;%DATA_DIR%\Scripts\Source;%DATA_DIR%\Scripts\Source\Base"
+
+if not exist "%PAPYRUS_COMPILER%" (
+    echo Papyrus compiler not found:
+    echo   %PAPYRUS_COMPILER%
+    echo Install the Creation Kit or set PAPYRUS_COMPILER_EXE.
+    exit /b 1
+)
+
+if not exist "%PAPYRUS_FLAGS%" (
+    echo Papyrus flags file not found:
+    echo   %PAPYRUS_FLAGS%
+    exit /b 1
+)
+
+if not exist "%SCRIPTS_SOURCE_DIR%" (
+    echo Papyrus source folder not found:
+    echo   %SCRIPTS_SOURCE_DIR%
+    exit /b 1
+)
+
+if not exist "%SCRIPTS_COMPILED_DIR%" mkdir "%SCRIPTS_COMPILED_DIR%"
+
+for %%F in ("%SCRIPTS_COMPILED_DIR%\CoSync*.pex") do (
+    if exist "%%~fF" del /q "%%~fF"
+)
+
+echo Compiling Papyrus scripts...
+echo   Source: %SCRIPTS_SOURCE_DIR%
+echo   Output: %SCRIPTS_COMPILED_DIR%
+echo   Compiler: %PAPYRUS_COMPILER%
+echo.
+
+set "SCRIPT_COUNT=0"
+
+for /r "%SCRIPTS_SOURCE_DIR%" %%F in (*.psc) do (
+    set "BASE_NAME=%%~nF"
+    if /i "!BASE_NAME:~0,6!"=="CoSync" (
+        echo   Skipping reference source: %%~nxF
+    ) else (
+        set "REL=%%~fF"
+        set "REL=!REL:%SCRIPTS_SOURCE_DIR%\=!"
+        set "SCRIPT_NAME=!REL:~0,-4!"
+        set "SCRIPT_NAME=!SCRIPT_NAME:\=:!"
+        set "SCRIPT_OUTPUT=!SCRIPT_NAME::=\!"
+        set "EXPECTED_PEX=%SCRIPTS_COMPILED_DIR%\!SCRIPT_OUTPUT!.pex"
+        set /a SCRIPT_COUNT+=1
+
+        echo   !SCRIPT_NAME!
+        if exist "!EXPECTED_PEX!" del /q "!EXPECTED_PEX!"
+        "%PAPYRUS_COMPILER%" "!SCRIPT_NAME!" -f="%PAPYRUS_FLAGS%" -i="%PAPYRUS_IMPORTS%" -o="%SCRIPTS_COMPILED_DIR%"
+        if not exist "!EXPECTED_PEX!" (
+            echo Papyrus compilation failed for !SCRIPT_NAME!.
+            exit /b 1
+        )
+    )
+)
+
+if "%SCRIPT_COUNT%"=="0" (
+    echo No active Papyrus sources found.
+) else (
+    echo.
+    echo Papyrus compilation complete. Scripts compiled: %SCRIPT_COUNT%
+)
+
+endlocal
+exit /b 0

deploy-all.bat

@@ -3,10 +3,17 @@ setlocal EnableExtensions
 
 set "SCRIPT_DIR=%~dp0"
 
-call "%SCRIPT_DIR%stage-mod.bat"
+call "%SCRIPT_DIR%resolve-fallout4-path.bat" "%~1"
 if errorlevel 1 exit /b 1
 
-call "%SCRIPT_DIR%resolve-fallout4-path.bat" "%~1"
+echo.
+echo Compiling Papyrus scripts...
+call "%SCRIPT_DIR%compile-papyrus.bat" "%F4_DIR%"
+if errorlevel 1 exit /b 1
+
+echo.
+echo Staging mod package...
+call "%SCRIPT_DIR%stage-mod.bat"
 if errorlevel 1 exit /b 1
 
 set "STAGED_DATA=%SCRIPT_DIR%build\Fallout 4\Data"
@@ -38,6 +45,8 @@ echo   %DATA_DIR%\*.esp
 echo   %DATA_DIR%\Materials\
 echo   %DATA_DIR%\Meshes\
 echo   %DATA_DIR%\Textures\
+echo   %DATA_DIR%\Scripts\*.pex
+echo   %DATA_DIR%\Scripts\Source\User\*.psc
 
 endlocal
 exit /b 0

docs/dev-log.md

@@ -9,6 +9,47 @@ failed experiments, successful tests, and next steps.
 
 ---
 
+## 2026-06-28 - Papyrus Build Integration
+
+### Summary
+Added Papyrus compilation to the full build flow so active source scripts in `creation-kit/scripts/source` are compiled before the mod package is staged.
+
+### Files Changed
+- `compile-papyrus.bat`
+- `build-all.bat`
+- `deploy-all.bat`
+- `stage-mod.bat`
+- `docs/setup.md`
+- `changelog.md`
+- `docs/dev-log.md`
+
+### Details
+- Added `compile-papyrus.bat`, which resolves Fallout 4 through `resolve-fallout4-path.bat` so build-time Papyrus compilation uses the same explicit path, `FALLOUT4_PATH`, saved `.fallout4-path`, common-path scan, prompt, and save behavior as deploy. Saved `.fallout4-path` values are passed directly to the resolver during builds so `build-all.bat` does not pause for repeat confirmation.
+- The compile step calls `PapyrusCompiler.exe` directly instead of `ScriptCompile.bat` because the helper batch uses stale hardcoded `C:\Projects\Fallout4\...` paths.
+- `build-all.bat` now compiles active Papyrus scripts before `stage-mod.bat` copies `.pex` files into `build/Fallout 4/Data/Scripts`, and still stages the repo build folder for inspection if Papyrus compilation fails.
+- `deploy-all.bat` now resolves the Fallout 4 install path first, compiles Papyrus scripts, stages into the repo build folder, and then copies from `build/Fallout 4/Data` into the game `Data` folder.
+- `stage-mod.bat` now preserves relative script paths when staging `.pex` files to `Data/Scripts` and `.psc` files to `Data/Scripts/Source/User`.
+- Reference-only `CoSync*.psc` and stale `CoSync*.pex` files are skipped so the old exploration pathway is not included in builds or deploys.
+
+### Testing
+- Ran `compile-papyrus.bat "d:\SteamLibrary\steamapps\common\Fallout 4"`.
+- Confirmed `CO_Vault109StartQuestScript` compiled successfully.
+- Confirmed `CoSync`, `CoSyncPlayer`, and `CoSyncQuest` are skipped as reference-only sources.
+- Confirmed `test.psc` is not skipped by name and is treated as an active test script.
+- Full `build-all.bat` and `deploy-all.bat` were not run in this session.
+- Verified the build-only staging path by running `stage-mod.bat` after a known `test.psc` compile failure.
+- Confirmed `build/Fallout 4/Data/Scripts/CO_Vault109StartQuestScript.pex`, `build/Fallout 4/Data/Scripts/Source/User/CO_Vault109StartQuestScript.psc`, and `build/Fallout 4/Data/Scripts/Source/User/test.psc` exist.
+- Confirmed `test.psc` was not copied into the real Fallout 4 install during build-only staging.
+
+### Known Issues
+- Invalid active `.psc` scripts fail the build, including test scripts whose filename does not match their `Scriptname`.
+
+### Next Steps
+- Run `build-all.bat` and confirm the staged package contains `Data/Scripts/*.pex` and `Data/Scripts/Source/User/*.psc`.
+- Run `deploy-all.bat` and verify the files land in the Fallout 4 install.
+
+---
+
 ## 2026-06-26 - First-Time Join Starts in `COVault109`
 
 ### Summary

docs/setup.md

@@ -4,7 +4,7 @@
 
 - Fallout 4 on PC
 - Fallout 4 Script Extender, F4SE
-- Fallout 4 Creation Kit
+- Fallout 4 Creation Kit, including the Papyrus compiler
 - Visual Studio 2022 or newer
 - Git
 - CMake or another build system required by the selected plugin template
@@ -68,7 +68,13 @@ From the repository root:
 build-all.bat
 ```
 
-This builds the plugin, PrismaUI_F4, and stages a complete mod package into `build/Fallout 4/Data` at the repo root. The layout mirrors the real game path under your Fallout 4 install.
+This builds the plugin, PrismaUI_F4, compiles active Papyrus sources from `creation-kit/scripts/source` into `creation-kit/scripts/compiled`, and stages a complete mod package into `build/Fallout 4/Data` at the repo root. The build step does not copy files into the real Fallout 4 install. Reference-only `CoSync*.psc` files are skipped. If a Papyrus script fails to compile, `build-all.bat` still stages the repo build folder for inspection, then exits with an error so the failed script is not missed.
+
+`build-all.bat` uses the same Fallout 4 path resolver as `deploy-all.bat`: it accepts an explicit path, checks `FALLOUT4_PATH`, uses the saved `.fallout4-path`, checks common Steam install paths, and prompts/saves the path when needed. You can also pass the game path explicitly:
+
+```bat
+build-all.bat "D:\SteamLibrary\steamapps\common\Fallout 4"
+```
 
 ```text
 build/
@@ -83,6 +89,11 @@ build/
       ├─ Materials/       (from creation-kit/assets)
       ├─ Meshes/          (from creation-kit/assets)
       ├─ Textures/        (from creation-kit/assets)
+      ├─ Scripts/
+      │  ├─ *.pex         (compiled from creation-kit/scripts/source)
+      │  └─ Source/
+      │     └─ User/
+      │        └─ *.psc   (from creation-kit/scripts/source)
       └─ PrismaUI_F4/
          ├─ libs/          (Ultralight runtime DLLs)
          ├─ resources/     (Ultralight assets)
@@ -103,13 +114,14 @@ deploy-all.bat
 deploy-all.bat "D:\SteamLibrary\steamapps\common\Fallout 4"
 ```
 
-`deploy-all.bat` re-stages `build/Fallout 4/Data` then copies it into the game's `Data` folder. On first use it prompts for the install path and saves it in `.fallout4-path` (gitignored).
+`deploy-all.bat` resolves the Fallout 4 install path, compiles Papyrus scripts, re-stages `build/Fallout 4/Data`, then copies that staged repo build into the game's `Data` folder. On first use it prompts for the install path and saves it in `.fallout4-path` (gitignored).
 
 Individual steps:
 
 ```bat
 build.bat              REM CommonwealthOnline.dll only
 build-prismaui.bat     REM PrismaUI_F4.dll only
+compile-papyrus.bat    REM Papyrus .psc to .pex only
 stage-mod.bat          REM assemble build/ from existing DLL outputs
 deploy-ui.bat          REM HTML views only (requires PrismaUI_F4 installed separately)
 ```

stage-mod.bat

@@ -2,7 +2,7 @@
 REM stage-mod.bat
 REM Assembles the full mod into build/Fallout 4/Data at the repo root.
 REM Merge build/Fallout 4 into your game install, or copy build/Fallout 4/Data into Data.
-setlocal EnableExtensions
+setlocal EnableExtensions EnableDelayedExpansion
 
 set "SCRIPT_DIR=%~dp0"
 set "BUILD_DIR=%SCRIPT_DIR%build"
@@ -10,6 +10,8 @@ set "DATA_DIR=%BUILD_DIR%\Fallout 4\Data"
 set "FRAMEWORK_DIR=%SCRIPT_DIR%ThirdParty\framework-F4-Conversion"
 set "ASSETS_DIR=%SCRIPT_DIR%creation-kit\assets"
 set "ESP_DIR=%SCRIPT_DIR%creation-kit\esp"
+set "SCRIPTS_COMPILED_DIR=%SCRIPT_DIR%creation-kit\scripts\compiled"
+set "SCRIPTS_SOURCE_DIR=%SCRIPT_DIR%creation-kit\scripts\source"
 set "PRISMA_DLL="
 set "CO_DLL=%SCRIPT_DIR%plugin\build\windows\x64\release\CommonwealthOnline.dll"
 set "UL_SDK=%ULTRALIGHT_SDK_PATH%"
@@ -98,6 +100,8 @@ call :StageAssetFolder Materials
 call :StageAssetFolder Meshes
 call :StageAssetFolder Textures
 
+call :StagePapyrusScripts
+
 echo.
 echo Mod staged successfully.
 echo Merge into your Fallout 4 install:
@@ -120,3 +124,34 @@ if not defined SOURCE exit /b 0
 echo   %FOLDER%\
 xcopy /Y /E /I /Q "%SOURCE%\*" "%DATA_DIR%\%FOLDER%\" >nul
 exit /b 0
+
+:StagePapyrusScripts
+REM Compiled .pex scripts go to Data\Scripts; raw .psc sources go to Data\Scripts\Source\User.
+call :StagePapyrusFolder "%SCRIPTS_COMPILED_DIR%" "%DATA_DIR%\Scripts" "*.pex" "Scripts"
+call :StagePapyrusFolder "%SCRIPTS_SOURCE_DIR%" "%DATA_DIR%\Scripts\Source\User" "*.psc" "Scripts\Source\User"
+exit /b 0
+
+:StagePapyrusFolder
+set "PAPYRUS_SOURCE=%~1"
+set "PAPYRUS_DEST=%~2"
+set "PAPYRUS_PATTERN=%~3"
+set "PAPYRUS_LABEL=%~4"
+
+if not exist "%PAPYRUS_SOURCE%" exit /b 0
+
+for /r "%PAPYRUS_SOURCE%" %%F in (%PAPYRUS_PATTERN%) do (
+    set "BASE_NAME=%%~nF"
+    if /i "!BASE_NAME:~0,6!"=="CoSync" (
+        echo   Skipping reference script: %%~nxF
+    ) else (
+        set "REL=%%~fF"
+        set "REL=!REL:%PAPYRUS_SOURCE%\=!"
+        set "DEST_FILE=%PAPYRUS_DEST%\!REL!"
+        for %%D in ("!DEST_FILE!") do set "DEST_DIR=%%~dpD"
+
+        if not exist "!DEST_DIR!" mkdir "!DEST_DIR!"
+        echo   %PAPYRUS_LABEL%\!REL!
+        copy /Y "%%~fF" "!DEST_FILE!" >nul
+    )
+)
+exit /b 0