C++ Documentation

This will explain how the projects native component is setup, how to build it, how SWIG is used, and some design decisions

Shards native AI, is a Spring AI built on the OO C++ API. It acts as a wrapper around this API, providing a simpler API that is bound to a Lua VM. This Lua environment is not the same as the Lua environment that powers spring games, and has different APIs. Data can be sent between the two across a dedicated API.

The binding that exposes the engine to the Lua VM is built using the SWIG tool. Modifications to the generated file should be avoided as they’ll be overwritten by the tool when next ran.

The native AI also contains some minor helper functions, such as exposing the closestbuildsite helper function, with some additional tweaks to make it more robust.

Directory Structure


This folder contains the lua AI, and is copied as is into the target AI folder by the spring engines make files. This is also where you will find the AIInfo.lua etc


This folder contains some core files that underpin the structure of the API, namely the definition of an AI module, and the tables that wrap around whatever engine is being used at the time. `api.lua` will load files from a subfolder depending on the environment it finds itself in.

When using the AI in a new environment, be sure to pass units through `shardify_unit` before passing units to the main Shard AI object acquired via `ai.lua` so that Shard can use the functions it expects.


This contains the dependent libraries specific to the AI. Currently only the lua 5 VM is present. The Spring Engine API and headers are included with the game engine itself. Some of these headers and APIs are automatically generated by AWK scripts when the engine is built.


This folder contains the stub AI itself, the C++ component that interfaces with the engine and provides the lua environment Shards AI logic runs in. cpptestai is the main object that handles the engines events and translates them, wrapping unit objects etc. CTestAI is the object that calls the lua environment etc. If you’re building a pure C++ AI, you may want to replace this class with your own and remove or repurpose the lua code.


A Visual Studio 2010 project. It may work but it’s recommended you use the Spring Engine build system