---
title: Combatant Scripting
description: "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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatant.html) class. It gives you access to all information related to the combatant, e.g. status,…"
url: "https://orkframework.com/guide/ork3/ork3-documentation/scripting/combatant-scripting/"
updated: "2026-07-08"
category: ORK 3 Documentation / Scripting
tags:
  - Scripting
---

# 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatant.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatant_setting.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_class.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_status.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_abilities.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_equipment.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_battle.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_grid.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_actions.html) 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](https://orkframework.com/guide/documentation/features/shortcut-slots/).

The [CombatantShortcuts](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_shortcuts.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_a_i.html) class holds information on the combatant's battle AI and AI equipment ([AI behaviours/rulesets](https://orkframework.com/guide/documentation/inventory/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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_animations.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_object.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatants_1_1_combatant_u_i.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_research_handler.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_console_handler.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_inventory.html) 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](https://orkframework.com/guide/documentation/battles/target-selection/).

The [SelectedTargets](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_selected_targets.html) 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](https://makinom.com/api/class_gaming_is_love_1_1_makinom_1_1_variable_handler.html) 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](https://makinom.com/api/class_gaming_is_love_1_1_makinom_1_1_selected_data_handler.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_group.html) 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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatant.html) 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](https://orkframework.com/guide/documentation/scripting/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](https://orkframework.com/guide/documentation/scripting/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](https://orkframework.com/api/class_gaming_is_love_1_1_o_r_k_framework_1_1_combatant_handler.html) 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.
