📚 Community SDK

This is our effort to bridge the gap between the official Giants Developer Network and the knowledge spread throughout the FS modding community. Sort of an FS modding knowledgebase and FS LUA Reference Library.

Recommended resources:

• ⚙️ Script Library (install | script reference )
• 🧰 FS Build tool (installation instructions)
• 🎁 Bootstrap Mod (download)

Quick links: 🧙 Productivity tips | 🛠️ Configure editor | 👨‍💻 Run code w/o game | 🤖 Automation

📚 LUA Reference Library

• Script Bindings (download)
• Can-I-Use-It? (in-game vs Giants Editor vs Lua stand-alone)
• Community KB (how-to/setup)
  • Global Tables
  • Global Functions
  • Known Classes
• Official GDN
  • FS LUA API Reference
  • Video tutorials
• XML Schemas (how-to/setup)

🧙 Productivity tips & guides

❓ Can-I-Use-It? (in-game vs Giants Editor vs Lua stand-alone)

Did you know that a lot of the in-game Lua code can be tested directly in the Giants editor or even directly via the stand-alone Lua interpreter?

However, there are some limitations. E.g. some features are restricted by Giants due to security considerations, and some game specific core Lua functions are simply not available in the native Lua interpreter.

The Can-I-Use-It? page has a summary of which functions, classes and tables that might be available only in one, two or all three enviroments, sometimes only available with limited functionality.

🛠️ Configure your IDE/text editor

Tips and guides to make you more efficient when working with your mods, especially the XML and Lua parts. Choose the text editor you prefer, ideally one that supports all/most of the options below:

1. Install a Lua extension to provide intellisense and Lua language support
2. Install a Lua server extension to get context aware
3. If your text editor lack advanced support for XML, it is recommended to install an XML extension as well
4. Configure your Lua extension to use Lua 5.1
5. Configure your language server to read source files from a custom folder, and in this folder you add relevant Lua files containing global tables, classes, script bindings etc what will help the language server understand the FS object model, e.g:
   1. ScriptBindings
   2. Global tables
   3. Known classes
   4. Undocumented functions
6. Install a extension to support Markdown
   1. Optionally: Install an extension to support Markdown TODO
7. If everything is setup properly you should now have intellisense suggesting g_currentMission when you type g_cur.

By configuring the editor with the right extensions and settings you set yourself up for maximum productivity where you can focus on the creative process.

Install recommended VS Code extensions

The following example assumes you are using VS Code (which we can truly recommend), however the most popular alternative text editor should have similar capabilties.

Install the following extensions:

1. 'Lua' language server
2. Lua snippets [needs to be verified if still needed]
3. Lua for Visual Studio Code [needs to be verified if still needed]
4. XML
   • Check the XML Schema section for details on how to use this extension optimally
5. [optional] Markdown All In One
6. [optional] Markdown TODO
7. [optional] TODO Highlight
8. [optional] Python
9. [optional] FS22 Snippets by FSG Modding
   • This extension might be redundant if the XML extension and proper XML Schemas is used
   • Possible (untested) alternative by Razor Modding Team
10. [optional] Code Runner
    • Enables execution of selected code directly from VS Code text editor, perfect to test run small snippets

Setup the Lua language server extension

The following assumes you completed the previous step of setting up VS Code with the Lua language server.

1. Go to Extensions
2. Find Lua (language server from step 1 in the setup extensions guide)
3. Klick on the gear icon ⚙️
4. Choose Extensions Settings
5. Search for Runtime Version and select 5.1
6. Search for Workspace Library and add at least one folder where you will store your custom Lua API reference files. Recommended Lua files to add:
   • scriptBinding.lua
   • gameSource (extract the contents of gameSource.zip in the sdk\debugger\ subfolder of your FS installation)
   • All files from the Community KB
7. [optional] Search for Max Preload and choose a higher number (5000 seems to work ok without requiring too much memory)
8. [optional] Search for Show Params and enable it
9. [optional] Search for Hint
   • Hint: Enable Enable
   • Hint: Param type Enable
   • Hint: Set type Enable
10. [optional] Review other extension settings based on your personal preferences
11. Done

Note: if you put all the different files from step 6 above in different subfolders, you can also open this folder as separate project in VS Code which makes it easy to search for functions, tables or files from your "SDK library", e.g:

👨‍💻 Run Lua code without starting the game

Did you know that you can test run your code without starting/reloading the game?

1. Run code in Giants Editor (GE)

If you open Giants Editor (you don't need to load any i3d file), you can execute directly from the console.

This is a convinient way of executing Lua code in an enviroment that is similar to the actual game, without the loading time of realoding the game each time you change your script. Just be aware that some functions from the game is not available in GE (at least without additional script), see Can-I-Use-It? for more details.

💡 You can also execute script files with the source() command, and even better, you can also bind keyboard shortcuts to a script in GE if your are using Giants Editor - Hotkeys and Macros

💡 Did you know that you can also import base game scripts as long as you know the path, e.g source("dataS/scripts/shared/string.lua") (note: "data$" is substituted with "dataS"). The path can be found in error messages and in certain resources online.

❗ Since source() caches the imported file, you either need to restart GE or change the file name if you make changes to the same file.

2. Run code directly in the VS Code text editor

If you have the VS Code plugin Code Runner enabled, you can easily execute the selected code directly from the text editor. This is a quick way to test small snippets of code.

Just bare in mind that the execution is not aware of the context in the file outside the selected text block. I.e. this code would fail if you select and run line 2:

local a = "Hello"
print(a .. "There") -- The only line selected

It would be the same as running:

--local a = "Hello"
print(a .. "There") -- The only line selected

3. Run code from the terminal

In a terminal, run the command lua, this will start the Lua interpreter from which you can run commands directly, e.g.:

> print("Hello") 
Hello
> 

❗ You might have a different Lua version installed than the game uses (5.1), i.e. some commands might behave a bit different.

💡 You can open a terminal directly in VS Code (menu View > Terminal or keyboard shortcut)

🤖 Automation

A great productivity tip is to use automation to streamline tedious tasks, this is a few examples:

1. Automate the process of creating your zip archive using a single command in the terminal
2. Automate the TestRunner tool automatically when building your zip archive
3. Auto-start FS from your code eidtor with a pre-defined savegame that contains your dev/test setup
4. Use a mod to enable you to restart current savegame directly from the game, either via the UI or the developer console
   • PowerTools provides both UI and console option, PowerTools Developer has the console option and EasyDevControls also provide the console option.
5. In VS Code you can allocate keyboard shortcuts to custom commands, e.g. to create your zip or start FS with a specific savegame
6. Use a AI tool such as Codeium or Copilot to assist you with Lua patterns and examples
   • Note: be aware that FS has a custom (locked-down) Lua implementation which means AI often struggle with more complex questions

🧰 FS Build Tool

We have created a tool to make the build process easier and less time consuming. In short, it can take care of the automation steps 1-3 in the list above and even be triggered via keyboard shortcuts (see #5).

Installation instructions for FS Build