MODDING

At some point in the not-too-distant future, this may evolve into a wiki or something similar. But, until then, here's the basic orientation you need to start causing trouble in your SiS scripts folder.

SiS is written in Lua 5.2... ish.

The script files used by SiS are written in a variant of Lua 5.2 Specifically, they use a version of the language that has a number of parser hacks, these allow common shorthands (like '+=') and less common shorthands (like '?.') along with some straight up unique shorthands (like '!.'). If you don't know Lua, the cannonical reference guide is the Third Edition of Programming in Lua (PiL). However, the assorted shorthands and other parser quirks used in SiS are currently only documented on my personal page on the Lua user's wiki.

SiS is designed for live-coding

Stars in Shadow supports a “developer mode”, which allows the game to request that any running copy of Visual Studio open up a particular file, and then jump to a particular line of code. When “developer mode” is on, you can ctrl-left click on most of the text in the game to jump directly to the line of the lua scripts where said text is defined. The live-editing features then often (but not always) cause edits made to those text blocks to immediately show up in the game.

Similarly -- when an error message pops up in game, clicking on one of the lines shown in the stack trace should take you to the offending lua script.

This means that even if all you’re going to do is edit the game script files, working with Visual Studio is much more convenient than working with any other editor. Of course, MSVS is a bit of a monster to download and setup.

Setting up Visual Studio

Both the engine and the scripts in SiS are developed using Visual Studio 2013. Visual Studio 2013 is free for small independent developers and hobbyists -- and if you're a modder, you're in that category :) Visual Studio is also fairly extensible -- and there are a couple SiS-specific extensions that you'll either need, or benifit from, when hacking around in the source.

• OpenHint: This is the most critical addon -- it allows communication between visual studio and any running copy of SiS. Unzip it, then follow the instructions in README.txt.
• BabeLua: This is a moderatly hacked version of the BabeLua source -- it provides fairly nice Lua syntax highlighting -- and it can handle most (but not quite all) of the quirks of my modified Lua parser properly.
• Word Wrapping: Gets you my crude implementation of word-wrapping inside Lua comments and multi-line string definitions. It’s a bit buggy, but, usable, and it can help keep text definitions inside scripts readable.
• SvenBar: A quick and dirty navigation bar for SiS Lua files. It's occasionally useful.
• DPack: A huge multiuse extension that has one feature I can’t live without -- a file browser that lets you quickly navigate to any source file by entering in a partial file name. Once DPack is installed, you can access the DPack file browser under TOOLS -> DPACK -> File Browser -> All Files. You can (and should) hotkey this file option by creating a new entry in TOOLS -> Options -> Environment -> Keyboard that maps the shortcut of your choice to Tools.DPack.FileBrowser.AllFiles. (I use Ctrl+O).

Setting up SiS

Inside your root Stars in Shadow directory (the same one that contains sis.exe) create a files called 'show_hidden_options.bool' (the contents don't matter). Then launch sis.exe. Open up the options pane, and click on the title text that says "Options". The pane should switch modes, and display "Developer Options". The most important of these is "visual studio dev hooks". Turn that on -- then exit the game.

To use SiS and Visual Studio together, you'll need a Visual Studio project that contains all the SiS script files. Creating such a project is a bit awkward. You can try using this project created by me (on 09/21/2016). But to get a fresh copy, the fastest method I know of is to:

1. Create a new solution, containing an empty C++ project.
2. In explorer, navigate to the Stars in Shadow Lua State directory. In the search bar, type *.lua. You should get a list of 500+ files. Highlight them all, then drag and drop into your empty c++ project. You should now have a project file containing 500+ unorganized lua files.
3. Save the project, then launch sis.exe. Start a new game, and in the race selection screen, ctrl-click on one of the race's background text. If RACES.lua opens in visual studio, congrats, the setup appears to be successful!
4. Test live coding -- change the description of the race you're editing to something funnier. If everything is working, your new text will appear in game immediately after you save the file.

Extra Hotkeys and Hidden Features

In your game's root directory, open README.txt. It contains documentation on some of the hidden options (like "ai dev"). It also includes a little info on hotkeys like F1 (open debug log) which will be important parts of your modding experience. When the live-coding features reload an edited lua file, the file "chunk" executes immediately -- and any 'print' or 'console' commands that are executed will emit debugging information to the debug log.

Versioning

sis.exe recognizes a couple different command-line options. For the purposes of modding, the most important of these is '-noupdate', which will stop the updater from running automatically any time a new build is posted. If you're actively editing scripts, you won't want the updater to overwrite what you've done, so creating a custom shortcut that launches sis.exe using the -noupdate option is certainly a good idea. If you start working on any non-trivial mods, you'll also almost certainly want to setup a versioning control system to keep the changes posts by the updater separate from any change-sets of your own. SiS has no version control helpers at this time -- though if there's demand for it, I might be able to hack together some helpers for git users.

21 September, 2016 13:00