MODDING

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 canonical 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+click on most of the text in-game to jump directly to the line in 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 Code is much more convenient than working with any other editor.

Setting up Visual Studio Code

Install Visual Studio Code, then install the Stars in Shadow Dev extension.

After installing the extension, open your Stars in Shadow\ folder (in Steam or GOG, you can do this by clicking on "Browse files" in the game's properties). Then open the Lua state\ folder in Visual Studio Code. Now you have an IDE! But you'll need to jump through a few more hoops to make all the developer features work.

Enable Developer Options (jump-to-source + live reload)

To reveal the in-game Developer Options pane, create an empty file in the root Stars in Shadow folder called show_hidden_options.bool, then launch the game and open Options. Click the Options title to switch into Developer Options.

Enable "visual studio dev hooks" inside "Options". Then close the game.

Back inside Visual Studio Code, make sure you have the Lua state\ folder open, then hit F5. If the game starts up, congratulations! You are now running in dev mode. Do a few tests to make sure it works! The main features you should have are:

Sharing your Mods

For a detailed walkthrough of how the modding features work in SiS, you should read Modding\README.md. However, the main reason to package your changes as a formal "mod" is if you want to share it with other players. If you're only interested in changing a few game balance numbers for your own amusement, just clicking around with the dev tools and editing files in-place may be all you'll ever need!

You may, however, find it useful to take a look through the Modding Forum which is full of helpful people who may be interested in answering questions on how to do certain things, and is also a great place to post your mods.