AI scripting interface: under the hood

Welcome to part 4 of our series about the AI scripting interface, that lets you program your own Powargrid AI in Lua!

• Part 1: introduction
• Part 2: debugging tools
  
• Part 3: interacting with the game
• Part 4: under the hood

This time, I'd like to talk about some of the implementation details of our AI scripting framework. If you just want to write your own AI, you don't need to know about any of this! Still, I'm sure some folks will find it interesting :)

MoonSharp

Our game is made in Unity, which gave us several options to embed a scripting language. We went with MoonSharp, for a few reasons:

• it's entirely written in C# and designed to be used with Unity, which means it's a matter of dropping a single, cross platform DLL into your project and you're ready to go
• you can have multiple interpreters in a program, so each user AI gets its own environment
• it comes with a built-in debugger
  
• it has a solid security model to sandbox script code

Sandboxing

Playing against someone else's AI means running their code on your computer. We have to ensure that it's safe to do so: we don't want an AI to give someone else access to your computer, to delete your files, or in fact even look at them. That's why the AI scripts run in a secure environment, called a sandbox.

The sandbox strictly limits the files an AI script can access: you can use the "require" function to load additional modules, but you can only load Lua files, and only from two places: the AI's own directory, and the Shared directory that contains utility modules you may want to share between different AIs, like our ailib module.

We also limit the built-in Lua modules you can use. For example, you can have math, string and table, but not os, the interface to the operating system.

Threading and command queue

We had several requirements for the AI framework:

• API calls should be blocking: if you say "build me a power line", that power line should be built when the function returns. This makes for a much nicer interface than, for example, something based on callbacks.
• an AI script must not be allowed to freeze the game while running, even if it goes into an infinite loop.
  
• AI scripts must not be allowed to interfere with each other.
  

To make that happen, each AI script gets its own Lua interpreter and runs in a separate thread.

Multithreading is hard, especially when you're trying to share data between threads - so we don't, or at least, we share the absolute minimum.

When it's the AI's turn, the framework takes a snapshot of the current game state: how much power does each player have, what buildings are on the board, how many charges does each weapon have, etc.

If the AI calls a function that just returns information about the game state, this is answered based on the snapshot. Since Powargrid is a turn based game, nothing can change until the current player makes a move.

When an AI calls a function to change the game — for example, placing a building — the AI thread enqueues this command and on the next frame, the AI framework, running on the main thread, picks up the command, tries to execute the action, puts the result (whether it was built or not) on the response queue, and takes a new snapshot. The AI thread that was blocking on the response queue picks up the response and returns that to the Lua script as the result of the "build" command, and the AI can continue.

That's it, in a nutshell! Again, don't worry about any of this when writing your AI. Just take a look at the API docs and the example AI, and start hacking!