Shard AI Documentation

Hello! This site is dedicated to documenting Shard. See the blog posts for Q&A and how tos, and look at the menu in the sidebar for documentation on how Shard is built, what the different objects do, and how they’re intended to work

Testing Changes Against Multiple Shards ( Native AI )

Sometimes you want to make changes to Shard then compare them against the original. How else will you know if you’ve improved things? What if you want to test the development version of Shards lua against the current release?


Can Shard Use Spring Lua Widgets?

That depends, if Shard is running as a Spring LuaAI, or if it’s running as a native AI using the same interface as AIs such as KAIK, or AAI


Unit Queries

It’s possible to do database style queries of units using query.lua:

require "query.lua"

-- grab all solar collectors within a radius of 1000
position = ...
solar_collector_units = query({
    "unit_type" = "corsolar",
    "within" = {
        "position"= position,
        "radius" = 1000

The implementation is available in beta here

Reclaiming Behaviours

How do I make a unit spend all its time reclaiming things?

From the sounds of it, you should make use of the behaviour system. Units have behaviours attached to them depending on the type of unit. Most construction units only have the taskqueuebehaviour, but here it sounds like you need to implement a reclaimbehaviour.


Counting Units by Type

Some logic might need to know how many of a particular type of unit the AI currently controls. To do this I suggest the following


Random Construction in Task Queues

Some games have multiple tier 1 factories, such as vehicles versus walkers. We might want Shard to randomly choose which type of units to use. This is how to make Shard choose a random unit from a list to build in a task queue:


Wind vs Solar Task Queues

How do we make Shard build wind generators on windy maps, and solars on others?

Here, a function that determines the average wind speed and returns a wind generator if it’s above 10, or a solar if it’s less, is used in the core kbot constructors task list/build list.

How to Count Builders, Friendly & Enemy Units

To determine the overall unit count you can simply count the number of objects returned int he table when calling game:GetFriendlies(), and vice versa for game:GetEnemies()

To count the builders you would either iterate through the returned items and check each if they were a builder, or you can store the value via a module, and increment and decrement on unit created and unit death events. ( latter would be preferable as it’s far less intensive )

Based on a post on the spring forums

Searching For & Reclaiming Map Features

How would i make a builder search for map features and reclaim them?


Shard Attacks

Originally posted on

I was asked a question about Shards attack system on the spring engine lobby server. Having described Shards attack system, I decided to repost the log here for posterity


Having Issues With Construction, and Placement?

Taken from this spring forum post on the C++ API and building construction, it may be useful for those wondering about the build functions

For those with a little lua know how, the taskqueuebehaviour ( in dun dun dun taskqueuebehaviour.lua ) uses shards Build function to build things, but it passes no position parameter, and assumes shard will figure out where to build things on its own.


The difference between Attackers and Builders

Builders are given the taskqueue behaviour, which follows a list of tasks. Tasks are done from first entry to last, in order. If Shard cannot execute a task (eg. no place to build it was found), it will move on to the next task listed.


How Task Queues Work

The Taskqueues are defined in a lua table named ‘taskqueues’ in taskqueues.lua. They take the form of “unittype” = tableOfTasks, where the table of tasks is a lua array of strings, aka unit type names to build, starting in order from the beginning to the end. Such a unit name may be corsolar ( rather than the human readable version Core Solar )


An Introduction to Task Queues

Originally posted on the spring forums

In Shard builders have task lists/build order lists. Shard starts at the beginning of a list, and works its way to the end skipping any it cant do, then repeats. Build orders are lists of unit names


Adding New Behaviors

Originally posted on the spring forums

Behaviours are assigned to units, and implement basic logic. For example, the Taskqueuebehaviour.lua file contains a behaviour that implements taskqueues, and the attackerbehaviour.lua file contains a behaviour called AttackerBehaviour that implements attacking, etc. Everything is named to be as obvious as possible.