0 of 0
About this mod
Quick workflow wrapper files to decompile the Starfield base game Papyrus scripts with CHAMPOLLION and compile your own scripts with CAPRICA.
- Permissions and credits
- Changelogs
Quick workflow wrapper files to decompile the Starfield base game Papyrus scripts with CHAMPOLLION and compile your own scripts with CAPRICA.
Note: if you are using Starfield Creation kit refer to [ Papyrus decompile and compile command files with CreationKit ] which will be published when CreationKit releases.
DECOMPILE
The Papyrus script compiler needs to import the decompiled base game scripts, and you will probably need to look at them to see how new functions are used in context. So do this first:
(1) Extract ChampollionDecompile.cmd from the download archive into your SOURCE working folder. It is best to NOT put the loose base game source PEX files in your Starfield folders for performance and compatibility.
(2) Edit ChampollionDecompile.cmd SOURCE to your working folder.
(3) Use Hexabit B.A.E. to extract PEX scripts from [ Starfield - Misc.ba2 ] to SOURCE.
(4) Put Champollion.exe >= 1.3.0 in the same folder as ChampollionDecompile.cmd
(5) Edit ChampollionDecompile.cmd DESTINATION path. It can be anywhere but unless you totally know what you are doing, best start relative to your starfield.exe folder ...\Data\Scripts\Source\Base which is the standard Fallout4 Creation Kit style path. Example:
(6) Run ChampollionDecompile.cmd to decompile the whole PEX SOURCE tree to PSC DESTINATION. As path recursion can be inconsistent the folder structure is hard coded in the .cmd file.
COMPILE
(1) Extract CapricaCompile.cmd from the download archive to your scripts working folder SCRIPTPATH. It can be anywhere but unless you totally know what you are doing, best start relative to your starfield.exe folder ...\Data\Scripts\Source\User which is the standard Fallout4 Creation Kit style path. Example:
(2) Edit CapricaCompile.cmd path settings to match your environment. Paths should start with your starfield.exe folder path and maintain the Fallout4 Creation Kit style relative path structure, example:
(2a) If you are compiling script fragments such as Perks or Quests you will need to manually switch specific paths in and out for each of them. Or keep them in multiple CapricaCompilePerk.cmd CapricaCompileQuest.cmd type files:
(2b) Or just compile all files in your recursive scriptpath at once:
(3) Put Caprica.exe master build >= 6378296518 v0.3.0 in SCRIPTPATH folder (login to Github to see/download build artifacts).
(4) Starfield_Papyrus_Flags.flg file, variable and command line removed in v003 as they are now included in the exe.
(5) Create your new PSC scripts in SCRIPTPATH folder (best not mess with name spaces at this stage).
(6) To compile with CapricaCompile.cmd either:
(a) set the value of SCRIPTNAME in CapricaCompile.cmd (with .psc file extension), or
(b) pass the SCRIPTNAME on the command line (with .psc file extension) to override the hardcoded value, or
(c) fill in the prompt when CapricaCompile.cmd is run with no SCRIPTNAME set.
NOTEPAD++ INTEGRATION
To compile direct from Notepad++ [ Run ] menu, use version 002 or later of the these CMD files and enter [ Program to Run ] "YourSCRIPTPATH\CapricaCompile.cmd" $(FILE_NAME)
Example:
Then [ Save ] a name.
COMPILING TEST AND DEBUG CODE
If you have ever, ahem, published scripts with a crap-tonne of test harness and debug code still active, this workflow may help to pop any offending text in notepad as a compile time reminder.
Append ;debugdebug to any non production code blocks or lines (Bool bDebug = true ;debugdebug is my usual) and include this block in CapricaCompile.cmd just before caprica.exe:
SCRIPTSEARCH (v004)
Most learning comes from looking at base game scripts to see how functions are used. To help with that try StarfieldScriptSearch.cmd in the download archive. Put anywhere, edit the paths to match your configuration:
SOURCEBASE is the CapricaCompile IMPORT path
SOURCEUSER is the CapricaCompile SCRIPTPATH
And then keyword search on some yummy new functions: OnCombatListAdded, GetCurrentPlanet, PlaceDuplicateActorAtMe, RequestSaveByName & etc
The search string does not use wildcards or regex and can not have spaces, just plain 'ol ASCII chars.
OTHER OBSERVATIONS
You will of course need to enable loose files to see your new compiled PEX scripts in game.
You will undoubtably be wanting to enable the Papyrus Debug.Trace log.
If you dont know/use the console command [ ReloadScript scriptname ] to hot-reload recompiled scripts during test/remediation give yourself a slap for the many hours of unnecessary game exit & reloads.
If you find this useful, payback by never distributing hacked base game scripts without clearly informing users you are distributing hacked base game scripts. There really is no need (unless you are the Unofficial Community Patch) as they can ALWAYS* be non-invasively wrapped with sufficient consideration.
KNOWN ISSUES & FAQ
(1) If you are not a Papyrus script developer this is not for you.
(2) If you dont know what your "starfield.exe folder path" is or means this is not for you.
(3) Nothing works because you know better and ignored the it just works advice: "best start relative to your starfield.exe folder [ example ] which is the standard Fallout4 Creation Kit style path."
(4) Why do you not use Caprica.exe with the --recurse option ? Several reasons:
(a) when the wrapper files were first created the recurse function was not reliable.
(b) the recurse function does not work passing filenames direct from notpad++ macros.
(c) the recurse function does not work passing a wildcard file series [ FOR %%f in (...) do ... %%~nf.psc ].
(d) If you have say 100+ starfield scripts (actual number) why recompile them every run ?
(e) this is an education article for those who are not already expert. Fully qualifying all commands and script paths helps the process of understanding and learning, rather than I'm so clever short form notation ... MOV AX, [BX+1] ?
==============
Appreciation for the dedication and amazing software engineering talents of Orvid and Nikitalita in producing the CHAMPOLLION and CAPRICA tools that enable the joy of Papyrus scripting in Starfield within 4 weeks of the product launch.
(*) 5 modifed lines in 300,000 published is 0.002% qualifies as "always" on this page.
Note: if you are using Starfield Creation kit refer to [ Papyrus decompile and compile command files with CreationKit ] which will be published when CreationKit releases.
DECOMPILE
The Papyrus script compiler needs to import the decompiled base game scripts, and you will probably need to look at them to see how new functions are used in context. So do this first:
(1) Extract ChampollionDecompile.cmd from the download archive into your SOURCE working folder. It is best to NOT put the loose base game source PEX files in your Starfield folders for performance and compatibility.
(2) Edit ChampollionDecompile.cmd SOURCE to your working folder.
(3) Use Hexabit B.A.E. to extract PEX scripts from [ Starfield - Misc.ba2 ] to SOURCE.
(4) Put Champollion.exe >= 1.3.0 in the same folder as ChampollionDecompile.cmd
(5) Edit ChampollionDecompile.cmd DESTINATION path. It can be anywhere but unless you totally know what you are doing, best start relative to your starfield.exe folder ...\Data\Scripts\Source\Base which is the standard Fallout4 Creation Kit style path. Example:
C:\Program Files (x86)\Steam\steamapps\common\Starfield\Data\Scripts\Source\Base
(6) Run ChampollionDecompile.cmd to decompile the whole PEX SOURCE tree to PSC DESTINATION. As path recursion can be inconsistent the folder structure is hard coded in the .cmd file.
COMPILE
(1) Extract CapricaCompile.cmd from the download archive to your scripts working folder SCRIPTPATH. It can be anywhere but unless you totally know what you are doing, best start relative to your starfield.exe folder ...\Data\Scripts\Source\User which is the standard Fallout4 Creation Kit style path. Example:
C:\Program Files (x86)\Steam\steamapps\common\Starfield\Data\Scripts\Source\User
(2) Edit CapricaCompile.cmd path settings to match your environment. Paths should start with your starfield.exe folder path and maintain the Fallout4 Creation Kit style relative path structure, example:
set IMPORT=C:\Program Files (x86)\Steam\steamapps\common\Starfield\Data\Scripts\Source\Base
set OUTPUT=C:\Program Files (x86)\Steam\steamapps\common\Starfield\Data\Scripts
set SCRIPTPATH=C:\Program Files (x86)\Steam\steamapps\common\Starfield\Data\Scripts\Source\User
(2a) If you are compiling script fragments such as Perks or Quests you will need to manually switch specific paths in and out for each of them. Or keep them in multiple CapricaCompilePerk.cmd CapricaCompileQuest.cmd type files:
set SCRIPTPATH=C:\Program Files (x86)\Steam\steamapps\common\Starfield\Data\Scripts\Source\User\Fragments\Perks
or
set SCRIPTPATH=C:\Program Files (x86)\Steam\steamapps\common\Starfield\Data\Scripts\Source\User\Fragments\Quests
(2b) Or just compile all files in your recursive scriptpath at once:
caprica.exe --game starfield --import "%IMPORT%" --output "%OUTPUT%" --recurse "%SCRIPTPATH%\"
(3) Put Caprica.exe master build >= 6378296518 v0.3.0 in SCRIPTPATH folder (login to Github to see/download build artifacts).
(5) Create your new PSC scripts in SCRIPTPATH folder (best not mess with name spaces at this stage).
(6) To compile with CapricaCompile.cmd either:
(a) set the value of SCRIPTNAME in CapricaCompile.cmd (with .psc file extension), or
(b) pass the SCRIPTNAME on the command line (with .psc file extension) to override the hardcoded value, or
(c) fill in the prompt when CapricaCompile.cmd is run with no SCRIPTNAME set.
NOTEPAD++ INTEGRATION
To compile direct from Notepad++ [ Run ] menu, use version 002 or later of the these CMD files and enter [ Program to Run ] "YourSCRIPTPATH\CapricaCompile.cmd" $(FILE_NAME)
Example:
"C:\Program Files (x86)\Steam\steamapps\common\Starfield\Data\Scripts\Source\User\CapricaCompile.cmd" $(FILE_NAME)
Then [ Save ] a name.
COMPILING TEST AND DEBUG CODE
If you have ever, ahem, published scripts with a crap-tonne of test harness and debug code still active, this workflow may help to pop any offending text in notepad as a compile time reminder.
Append ;debugdebug to any non production code blocks or lines (Bool bDebug = true ;debugdebug is my usual) and include this block in CapricaCompile.cmd just before caprica.exe:
Spoiler:
Show
:DEBUGDEBUG
if exist debugdebugoutput.txt del /q debugdebugoutput.txt
findstr /i /c:"debugdebug" "%SCRIPTFILE%" >> debugdebugoutput.txt
if not exist debugdebugoutput.txt goto CAPRICA
for /f %%i in ("debugdebugoutput.txt") do set size=%%~zi
echo debugdebugoutput.txt size:%size%
if "%size%"=="0" GOTO CAPRICA
start notepad.exe debugdebugoutput.txt
pause
echo.
echo ******************************
echo.
:CAPRICASCRIPTSEARCH (v004)
Most learning comes from looking at base game scripts to see how functions are used. To help with that try StarfieldScriptSearch.cmd in the download archive. Put anywhere, edit the paths to match your configuration:
SOURCEBASE is the CapricaCompile IMPORT path
SOURCEUSER is the CapricaCompile SCRIPTPATH
And then keyword search on some yummy new functions: OnCombatListAdded, GetCurrentPlanet, PlaceDuplicateActorAtMe, RequestSaveByName & etc
The search string does not use wildcards or regex and can not have spaces, just plain 'ol ASCII chars.
OTHER OBSERVATIONS
You will of course need to enable loose files to see your new compiled PEX scripts in game.
You will undoubtably be wanting to enable the Papyrus Debug.Trace log.
If you dont know/use the console command [ ReloadScript scriptname ] to hot-reload recompiled scripts during test/remediation give yourself a slap for the many hours of unnecessary game exit & reloads.
If you find this useful, payback by never distributing hacked base game scripts without clearly informing users you are distributing hacked base game scripts. There really is no need (unless you are the Unofficial Community Patch) as they can ALWAYS* be non-invasively wrapped with sufficient consideration.
KNOWN ISSUES & FAQ
(1) If you are not a Papyrus script developer this is not for you.
(2) If you dont know what your "starfield.exe folder path" is or means this is not for you.
(3) Nothing works because you know better and ignored the it just works advice: "best start relative to your starfield.exe folder [ example ] which is the standard Fallout4 Creation Kit style path."
(4) Why do you not use Caprica.exe with the --recurse option ? Several reasons:
(a) when the wrapper files were first created the recurse function was not reliable.
(b) the recurse function does not work passing filenames direct from notpad++ macros.
(c) the recurse function does not work passing a wildcard file series [ FOR %%f in (...) do ... %%~nf.psc ].
(d) If you have say 100+ starfield scripts (actual number) why recompile them every run ?
(e) this is an education article for those who are not already expert. Fully qualifying all commands and script paths helps the process of understanding and learning, rather than I'm so clever short form notation ... MOV AX, [BX+1] ?
==============
Appreciation for the dedication and amazing software engineering talents of Orvid and Nikitalita in producing the CHAMPOLLION and CAPRICA tools that enable the joy of Papyrus scripting in Starfield within 4 weeks of the product launch.
(*) 5 modifed lines in 300,000 published is 0.002% qualifies as "always" on this page.