I intend to post a number of topics here regarding modding. I'll edit them as I go with updates to the various file formats, and in response to questions. We can always move them to their own forum should it get noisy in here!

Here’s all the information you need to start creating your own planning AI improvements, completely changing the AI's behaviour.

How it works

The whole system works using A* pathfinding techniques to start with a set of goals the character wants to fulfill, and working backwards to a point that's already true for the character. For a longer overview and example see this blog post.

Therefore, to control the AI you don't tell it what to do in a traditional scripting manner. Rather, you teach it how to satisfy certain goals. The game will always attempt to satisfy the goals given in data/needs.csv (currently: SOCIETY, REST, IMPROVEMENT and MONEY), plus a couple of other goals: SAFETY, WORK (used to ensure there are always people manning desks for the player to interact with) and any mission goals. It adds them as goals to the planner with a traversal cost of between 0 and 10000, where 0 is an urgent need and 10000 is a very low priority.

The system then attempts to apply the planning rules to figure out how to get to a state that already exists for the character. These rules are detailed in data/planner.csv.


The planner csv file format details the rules for the planner. Note that the header field is ignored. It's divided into the following fields:
  • goal: The goal that this rule fulfils. The planner will always check the game state to see whether a goal is true before seeing how to fulfil that goal. For example, the IN_ENTERABLE goal will be true if the character is in the 'enterable' (or location) that's in context at that time.
  • action (optional): The AI action that is completed to achieve this goal. These are a fixed list: the game will crash if you attempt to list one that doesn't exist. Once reaching a game state that already exists, the planner works backwards to create a chain of these actions, giving the plan for the AI to complete. eg: MOVE_TO moves the character to the location that's in context.
  • requirement: the required goal that must be true before the character can perform this action.
  • collect and filter: these specify the context ids for the new goals added to the list based on this requirement. The collect field specifies a list of things in the game, eg: goods, people, ships in range, enterables, etc. The filter field specifies how this list should be filtered down. If several values are returned, several sub-goals are added to the list with the same goal, one for each new id, with the context set to that id. When these fields are blank, the planner uses the context for the current goal.
  • cost: The cost of the action for the planner, which gives the order in which the rules will be traversed (lowest cost first). This can also be specified as :a:b which will range the cost between a and b depending on the value of one of our character's attribute. See the exist planner.csv file for examples.

I hope that's enough to be going on with: I'm aware this is incomplete, but hopefully it will be enough of a start. Do ask clarification questions in this post and I'll update the main text.

Chris Parsons
Quote 0 0