Ground of Aces Scripting

The game uses Python for scripting. The current supported version of Python is 3.4.

Scripts location

The script are located in the game folder, under the directory GroundOfAces_Data/StreamingAssets/Scripts. They are grouped into directories that can be loaded individually.

Loading scripts

By default, only the scripts located inside the Default directory are loaded on game startup.

In order to load scripts from other directory, use the command load_scripts <name> in the cheats console.

Writing scripts

Inside of the directory, scripts are contained inside .py files, where each one can contain one or more event handlers.

Mission scripts

Mission scripts are a specific type of scripts that are used to define all inner workings of missions, for more info about mission scripts head over to the mission scripting section of the documentation

Global variables

Each script has access to some predefined global variables that provide functionality to interact which the game. They are:

• event_log - create event log entries
• localization - add or modify localization terms
• morale - modify characters morale
• resources - spawn or destroy resources
• characters - retrieve characters information

Events

The list of default events and their arguments can be found here.

Event handler functions

Event handler functions are normal Python functions, decorated with the event_handler decorator. The name of the function can be any valid Python function name, and will be used together with the containing module name to identify the function internally when calculating how many times a function was called (in order to implement max occurrences limit). The function arguments depend on the particular event (see here).

The handler function can optionally return False - this will cause the execution not to be counted towards the max_occurrences limit. This is useful if particular handler should be invoked limited number of times, but only under certain conditions. Not returning anything (or explicitly returning True) causes the execution to be counted normally.

event_handler(event_name, chance=1.0, max_occurrences=-1)
def handler_function(arg1, arg2):

• event_name - Name of the event to handle. This can be any string that corresponds to an existing event, but for built-in events the easier way is to from Blindflug.MinorEvents import MinorEvent and the use the constants defined there.
• chance - A chance of the event handler being called when the event happens, from 0.0 to 1.0. E.g. setting chance to 0.5 would give the handler 50% chance to be called when the event happens. This default to 1.0 (always call the handler on event).
• max_occurrences - Maximum number of times the handler can be called during a single playthrough. Negative value means "no limit". The default in -1.

Example

This code would be located in a file under the scripts directory, e.g. GroundOfAces_Data/StreamingAssets/Scripts/Default/example.py.

# Import MinorEvent to have access to built-in event names
from Blindflug.MinorEvents import MinorEvent
# Import MoraleCategory to have access to morale type constants
from Blindflug.Game.Characters.Morale import MoraleCategory
# Import DayPhase to have access to day phase constants
from Blindflug.DayPhases import DayPhase
 
# Define a localization term that can be displayed in the game.
# This term contains a single placeholder value named "MOOD".
# Since this is located outside the function, it will be called when the script is loaded.
localization.SetTerm("en", "morale_up", "New day phase, mood improves by {[MOOD]}!")
 
# Use a decorator to mark the function as an event handler.
# This will give the function 10% chance to be called when the game day phase changes,
# up to 4 times during a single game.
@event_handler(MinorEvent.DAY_PHASE_CHANGE, chance=0.1, max_occurrences=4)
# Define a function to be called when the event happens.
# The arguments are specific to the day phase change event,
# and contain the previous and the current phase.
def on_day_phase(previous_phase, current_phase):
    # Adjust mood change amount depending on the new day phase
    mood_boost = 10 if current_phase == DayPhase.Leisure else 5 if current_phase == DayPhase.Sleep else 0
 
    # If there is nothing to do, return `False` and don't count this execution towards
    # the max occurrences limit
    if mood_boost == 0:
        return False
 
    # Modify the mood of all characters
    morale.ModifyMorale(MoraleCategory.Mood, mood_boost)
 
    # Create an event log entry, using the localization term defined previously
    # The "MOOD" placeholder will be replaces with the value of `str(mood_boost)`
    event_log.Create("morale_up", {'MOOD': str(mood_boost)})