ScriptMerge
is a command line tool for merging in-game scripts from multiple source code files.
It can also minify the script for release, so it can fit under the 100k characters limit.
Please consider supporting my work on Patreon or one time via PayPal.
- Install .NET Framework 4.8.1 (if you don't have it)
- Create .Net Framework 4.8.1 Class Library project
- Configure the project for C# 6.0 syntax
- Reference these NuGet packages from the project:
SpaceEngineers.ScriptingReferences
System.Collections.Immutable
- Use the
Script/Skeleton.cs
file from this repository as a starting point for your script code - See the
TODO
comments in the skeleton for more - See the Hints below
Build and use IngameScriptMergeTool
to merge your script source into a single file:
IngameScriptMergeTool --help
Description:
Command line tool to merge a Space Engineers script from multiple source code files.
Usage:
IngameScriptMergeTool [options]
Options:
-s, --solution <solution> Path to the solution file, it must include all projects your script depends on [default: *.sln]
-n, --namespace <namespace> Comma separated list of namespaces containing the code to be merged into the script [default: Script]
-d, --deploy <deploy> Deploy the script into SE's IngameScripts folder with this name (prints to stdout if not given)
-m, --minify Minify the source code by removing all comments and most unnecessary whitespace [default: False]
-u, --unicode Shorten all names to single Unicode letters, exclusion: //! KeepThisName [default: False]
-a, --aggressive Aggressively compress code (reduces repeated string literals) (requires --unicode) [default: False]
-r, --release Enables release mode, it removes #ifdef DEBUG ... #endif blocks [default: False]
--version Show version information
-?, -h, --help Show help and usage information
- Print debug merge:
IngameScriptMergeTool
- Print release merge:
IngameScriptMergeTool -maur
- Deploy debug merge:
IngameScriptMergeTool -d "Name Of My Script"
- Deploy release merge:
IngameScriptMergeTool -maur -d "Name Of My Script"
The deployment target is SE's script folder: %AppData%\SpaceEngineers\IngameScript\local\Name Of My Script
- For debugging 3D math use the (DevTool) Programmable Block DebugAPI mod and its PB API
- Add your unit tests (if any) into a separate namespace (for example
Tests
) - Make sure to wrap all debug code into
#if DEBUG
directives - Subdirectories are allowed, use
/
as a delimiter, or example:My Subdir/Name Of My Script
- Specific names (everywhere):
//! KeepThisName, KeepThatName
- On the line of declaration:
const string DontRenameThis = "x"; //!
- Enum values, sometimes they are shown to the player:
KeepThisEnumValue, //!
Adding //!!
anywhere in a namespace declaration will move that namespace block to the
top of the merged script and exludes it from variable renaming and minification.
This is useful to add documentation and configuration supposed to be editable by the player.
namespace Script {
//!!
/* Example script */
static class Config {
// This is a configuration variable
public static ConfigVar = 1;
}
}
- Enable the ScriptDev plugin in Plugin Loader, Apply, restart SE.
- Append the script's name in square brackets to your PB's name:
Programmable Block [Name Of My Script]
- The plugin will update the code in your PB whenever the
Script.cs
file changes.
You can wrap debug and release code into directives as you would in regular C# code:
#if DEBUG
Echo("DEBUG");
#endif
#if !DEBUG
Echo("RELEASE");
#endif
The directives themselves are removed, only their body are preserved during merging.
You can develop multiple scripts in the same solution. You can also split your code into any number of projects. All what matters while merging the script is the namespaces the tool takes the code from.
Put your shared code into a separate namespace, then use the --namespaces
(-n
) option to select the namespaces
to build your script from.
For example to develop two scripts in the same solution you could use these namespaces:
- SharedCode
- FirstScript
- SecondScript
Then invoke the merge tool with these parameters to deploy them separately:
-n SharedCode,FirstScript -d "First Script"
-n SharedCode,SecondScript -d "Second Script"
This is a simpler tool than MDK and does not depend on Visual Studio. However, it does not verify the script against the PB API whitelist, currently. It could be implemented based on the same whitelist file of MDK, should enough script developers request it. The type information is already available, since it is required for proper minification.
- SE Mods Discord FAQ, Troubleshooting, Support, Bug Reports, Discussion
- Plugin Loader Discord Everything about plugins