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 currently being developed using Visual Studio 2017 (an older version of the modding page with links for the Visual Studio 2013 version of the toolset can be found here). Visual Studio 2017 (Community)is free for small independent developers and hobbyists -- and if you're a modder, you're in that category :) If your only interest is SiS modding, I'd recommend installing just the base C++ developer features. (You won't actually be doing any C++ dev work, but the template project file I link below is technically a C++ project.)

Visual Studio is fairly extensible -- and there are a couple SiS-specific extensions that you'll either need, or benifit from, when hacking around in the source.

Setting up SiS

Inside your root Stars in Shadow directory (the same one that contains sis.exe) create a file 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. (Alternatively, if you're using the Steam or GoG.com distribution of Stars in Shadow, you should disable automatic updates using the assosiated Steam/Galaxy game properties settings.) 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 each official update 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.

Distributing Your Mod

At present, SiS includes only very basic tools for mod distribution. Essentially, any modified Lua files can be unzipped and placed in a subdirectory of Stars in Shadow/Mods, which will cause them to override the standard version of those files. Please read the documentation in your copy of Stars in Shadow/Mods/MakingMods.txt for more info.