Combatant Scripting

Learn how you can access a combatant’s information via scripting.

Anatomy of a Combatant #

An in-game instance of a combatant is handled by the Combatant class.

It gives you access to all information related to the combatant, e.g. status, abilities, inventory or the combatant’s group.

Settings #

You can access the settings of a combatant’s classes via the Setting attribute.

The CombatantSetting class holds all settings you can define for a combatant in the Makinom editor.

Please note that changing settings in a running game will not be saved with save games (or in the project).

Class Handler #

You can access information about a combatant’s classes via the Class attribute.

The CombatantClass class holds information on the combatant’s current class and classes it already used. E.g. you can access the current class level like this:

int currentClassLevel = combatant.Class.Level;

Status Handler #

You can access information about a combatant’s status via the Status attribute.

The CombatantStatus class holds information on the combatant’s status values, status effects and other status information. E.g. you can access the current value of a status value like this:

int currentClassLevel = combatant.Status[index].GetValue();

index refers to the index of the status value in the Makinom editor.

Or to get a list of all currently applied status effects:

List<StatusEffect> list = combatant.Status.Effects.GetEffects();

Abilities Handler #

You can access information about a combatant’s abilities via the Abilities attribute.

The CombatantAbilities class holds information on the combatant’s abilities. E.g. you can get a list of all currently available abilities like this:

List<AbilityShortcut> list = combatant.Abilities.GetAll();

Please note that this only contains actual abilities – base attacks, counter attacks and class abilities are kept separate from them.

E.g. you can get the current base attack and class ability like this:

AbilityShortcut attackAbility = combatant.abilities.GetCurrentBaseAttack();
AbilityShortcut classAbility = combatant.Abilities.GetClassAbility();

Equipment Handler #

You can access information about a combatant’s abilities via the Equipment attribute.

The CombatantEquipment class holds information on the combatant’s equipment. E.g. you can access the equipment of an equipment slot like this:

EquipShortcut equip = combatant.Equipment[index].Equipment;

index refers to the index of the equipment slot in the Makinom editor.

Battle Handler #

You can access information about a combatant’s battle state via the Battle attribute.

The CombatantBattle class holds information on the combatant’s battle state. E.g. you can access the current turn number like this:

int currentTurn = combatant.Battle.Turn;

Grid Handler #

You can access information about a combatant’s battle state via the Grid attribute.

The CombatantGrid class holds information on the combatant’s grid cell occupation. E.g. you can access the cell the combatant is currently placed on like this:

BattleGridCellComponent cell = combatant.Grid.Cell;

Battle grid components are part of the GamingIsLove.ORKFramework.Components namespace.

Actions Handler #

You can access information about a combatant’s actions via the Actions attribute.

The CombatantActions class holds information on the combatant’s action state and allows starting action selection. E.g. you can start a combatant’s action selection like this:

combatant.Actions.Choose(true, true);

The first bool argument will start a new turn when passing on true, the 2nd bool argument will automatically open the battle menu (for player controlled combatants only) when passing on true (i.e. like the auto show setup for battle systems).

Shortcuts Handler #

You can access information about a combatant’s shortcuts via the Shrotcuts attribute. Learn more about shortcuts and shortcut slots in this documentation.

The CombatantShortcuts class holds information on the combatant’s shortcuts. E.g. you can get the shortcut of the current active shortcut slot list of the combatant like this:

IShortcut shortcut = combatant.Shortcuts.Current[index];

index refers to the index of the shortcut slot.

AI Handler #

You can access information about a combatant’s battle AI via the AI attribute.

The CombatantAI class holds information on the combatant’s battle AI and AI equipment (AI behaviours/rulesets). E.g. you can block a combatant’s battle AI like this:

combatant.AI.Blocked = true;

Animations Handler #

You can access information about a combatant’s animations via the Animations attribute.

The CombatantAnimations class holds information on the combatant’s animations and lets you play animation types. E.g. you can stop all animations of a combatant (defined by it’s animation setup) like this:

combatant.Animations.StopAll();

Object Handler #

You can access information about a combatant’s game objects via the Object attribute.

The CombatantObject class holds information on the combatant’s game objects, e.g. the spawned prefab, the battle spot or the combatant’s radius. E.g. you can get the radius like this (when using a Radius component to define it on the spawned prefab):

float radius = combatant.Object.Radius;

You can also access the combatant’s game object directly from the combatant instance via the GameObject attribute.

Additionally, you can assign a new game object to the combatant, replacing the previously spawned prefab.

UI Handler #

You can access information about a combatant’s UI via the UI attribute.

The CombatantUI class holds information on the combatant’s UI, e.g. combatant object HUDs or HUD color. E.g. you can set the UI color of the combatant (e.g. used for tinting the combatant’s HUDs) like this:

combatant.UI.SetColor(Color.white);

Research Handler #

You can access information about a combatant’s research trees via the Research attribute.

The ResearchHandler class holds information on the combatant’s current research and learned research trees. E.g. you can the number of active research items like this:

int count = combatant.Research.InResearch;

Console Handler #

You can access a combatant’s own console via the Console attribute.

The ConsoleHandler class holds information on the combatant’s console lines and lets you add new lines or clear the console. E.g. you can remove all console likes like this:

combatant.Console.Clear();

Inventory Handler #

You can access a combatant’s inventory via the Inventory attribute.

The Inventory class gives access to the inventory of the combatant (or the combatant’s group when using group inventories). E.g. you can get the allowed quantity of an item likes like this:

int count = combatant.Inventory.GetAllowedCount(item);

item refers to an instance of an IShortcut implementation you want to check for. E.g. an ItemShortcut instance is an in-game representation of an item or an EquipShortcut instance for an equipment.

Currencies, items, equipment and other inventory content are managed by individual sub-inventory handlers that can be accessed via the inventory, e.g. combatant.Inventory.Items for items.

Selected Targets Handler #

You can access a combatant’s individual targets via the SelectedTargets attribute. Learn more about individual targets in this documentation.

The SelectedTargets class gives access to the individual targets of the combatant. E.g. you can set a selected target for an individual target index like this:

combatant.SelectedTargets[index] = target;

index refers to the index of the individual targets settings (e.g. the first added setting in Battles > Target Selection > Individual Target Settings.

target refers to an instance of the Combatant class that will be used (or use null to remove the target of that index).

Variable Handler #

You can access a combatant’s object variables via the Variables attribute.

The VariableHandler class gives access to the variables of the combatant. E.g. you can set a variable like this:

combatant.Variables.Set(key, value);

key refers to a string value representing the variable key.

value refers to the value that will be used – it needs to be a bool, int, float, string or Vector3 value.

Selected Data Handler #

You can access a combatant’s selected data via the SelectedData attribute.

The SelectedDataHandler class gives access to the selected data of the combatant. E.g. you can set a selected data like this:

combatant.SelectedData.Change(key, data, ListChangeType.Set);

key refers to a string value representing the selected data key.

data is the data you want to store and can be anything, e.g. an instance of a combatant, a variable handler, a component or an item (ItemShortcut instance, etc.).

Getting a Combatant Instance #

You can get existing combatant instances and create new ones from scratch.

Don’t forget that you’ll need to use the ORK Framework namespace GamingIsLove.ORKFramework.

using GamingIsLove.ORKFramework;

A Game Object’s Combatant #

A combatant is assigned to a game object via the CombatantComponent component – which also shows the combatant’s status and state information in the inspector.

Getting the combatant of a game object can be done in a single line of code:

Combatant combatant = ORKComponentHelper.GetCombatant(gameObject);

gameObject refers to the GameObject you want to get the combatant from.

If the game object isn’t part of a combatant, this’ll return null.

Creating a Combatant Instance #

Creating a new combatant instance via scripting involves multiple steps:

  • creating a Group for the combatant to join (or using an already existing group)
  • creating the Combatant instance
  • initializing the combatant
  • (optionally) spawning the combatant

Creating a group #

The Group class holds all combatants that are part of a group (e.g. the player group), the group’s inventory (when using group inventory), manages who is part of the battle group and which faction the group belongs to.

You can create a new group with the following code:

Group group = new Group(faction);
  • faction (FactionSetting)
    The FactionSetting of the used faction.

You can get the FactionSetting for a faction like this:

FactionSetting faction = ORK.Factions.Get(index);

index refers to the index of the faction in the Makinom editor. You can also get the faction via it’s GUID (string value).

Combined, you can create a group for a faction like this:

Group group = new Group(ORK.Factions.Get(index));

Creating a combatant #

The Combatant class holds everything related to a combatant – status, equipment, etc.

You can create a new combatant with the following code:

Combatant combatant = ORK.Combatants.Create(index, group, showNotification, showConsole)
  • index (int)
    The ID/index of the combatant.
  • group (Group)
    The group the combatant will join.
  • showNotification (bool)
    true if notifications should be shown, otherwise false.
  • showConsole (bool)
    true if console lines should be added, otherwise false.

Initializing the combatant #

The combatant created earlier has only basic initializations done – we still need to set up the level, class level and class the combatant should have, which will initialize the status, equipment and other things of the combatant. You can either use the default start settings of the combatant’s settings, or define the values you want.

Initializing a combatant with the default start settings:

combatant.Init();

Initializing a combatant with defind level, class level and class:

combatant.Init(level, int classLevel, startClass, loadGame, learnAbilities, useStartInventory, useStartEquipment, useInitSchematic, useStatusEffects);
  • level (int)
    The level the combatant will have.
    Has to be at least 1.
  • classLevel (int)
    The class level the combatant will have.
    Has to be at least 1.
  • startClass (Class)
    The ID/index of the class the combatant will have.
  • loadGame (bool)
    true if this is a creation from loading save game data, otherwise false.
    You usually want to pass on false here.
  • learnAbilities (bool)
    true if the combatant should learn the set up abilities, otherwise false.
  • useStartInventory (bool)
    true if the combatant should use the set up start inventory, otherwise false.
  • useStartEquipment (bool)
    true if the combatant should use the set up start equipment, otherwise false.
  • useInitEvent (bool)
    true if the combatant should use the set up init game event, otherwise false.
  • useStatusEffects (bool)
    true if the combatant should check the auto status effects upon creation, otherwise false.

You can get the Class for the combatant similar to getting the faction:

Class startClass = ORK.Classes.Get(index);

index refers to the index of the class in the Makinom editor. You can also get the class via it’s GUID (string value).

Spawning a combatant #

If you want to spawn your newly created combatant, you can use the following code (routing the call through the access handler):

combatant.Object.SpawnAccess(position, setRotation, rotation, setScale, scale);
  • position (Vector3)
    The position the combatant will spawn at.
  • setRotation (bool)
    If you want to set the rotation when spawning or not.
  • rotation (Vector3)
    The rotation of the Y-axis when spawning (only used when setRotation is true).
  • setScale (bool)
    If you want to set the scale when spawning or not.
  • scale (Vector3)
    The scale that will be used when spawning (only used when setScale is true).

One Line Creation using Access Handler #

Here’s a complete example for creating a combatant instance (excluding spawning it) and routing the call through the access handler:

Combatant combatant = ORK.Access.Combatant.CreateInstance(
    ORK.Combatants.Get(combatantIndex), new Group(ORK.Factions.Get(factionIndex)), showNotification, showConsole,
    level, classLevel, ORK.Classes.Get(classIndex), loadGame,
    learnAbilities, useStartInventory, useStartEquipment,
    useInitSchematic, useStatusEffects);

The CreateInstance function of the access handler combines creating a combatant instance and initializing it.

It uses the combined arguments from the creation and initialization calls above.

Combatant Handler #

The CombatantHandler class has access to all spawned combatants in your scene. You can access it via ORK.Game.Combatants.

E.g. you can get a list of all combatants like this:

List<Combatant> list = ORK.Game.Combatants.GetAll();

The combatant handler offers many different functions to get a list of combatants based on different checks, e.g. being ally or enemy of a given user combatant, distance to user combatant, etc.