Modding - Abilities

## Abilities

Abilities are special actions that the player can activate either by using a consumable item, or a reusable ability that is unlocked through infrastructure upgrades, research, etc. Abilities are defined in the `Abilities.json` file.

## Base Types

There are three main types that abilities inherit from: default, misc-item and item-ability. The default base class is used for reusable abilities such as those earned through infrastructure upgrades, and the item-ability for consumables that are used through the quick-bar, like repair kits. The misc-item base type is used for special consumables that are used by right clicking, such as blueprints that grant free expansions or free constructions, those that grant free skill points, or those that lower the global infestation level.

## Format

Abilities are defined using the standard Entity Format.

## Ability Parameters

Abilities have several parameters that affect how they behave, the most important one being the "action" which determines what the ability does.

### Cooldown

```
cooldown: {
	type: "repair"
	time: 15
}

```

Cooldown is an object parameter that has two children - "time" and "type". The time parameter defines how long after using the ability before it can be used again. The "type" is an optional parameter that can be used to group several abilities together in terms of cooldown - so that if one of the abilities in the set are in cooldown, the others will not be available other. By default the "type" equals the ability's ID, so it only affects itself unless another ability receives the same type.

In the example above we set the cooldown for "repair" type items to 15, so using any repair kit will make all repair kits unavailable for 15 seconds.

### Charging

```
charging: {
	time: 0.33
	effect-prefab: "EffectOverloadChargePrefab"
	charging-sound: "ability-charge-overload"
	slow: true
}

```

Some abilities take a few seconds to charge before they are activated, such as the teleport to city ability. The charging is an optional parameter that has several child values:

"time" - how long for the ability to charge

"slow" - whether or not Tiny is slowed down while the ability is charging. Default false.

"lock" - when set to true, Tiny will be unable to move or act while the ability is charging. Default false.

"charging-sound" - sound effect to use while charging.

"effect-prefab" - visual effect to use on Tiny while charging.

"target-effect-prefab" - visual effect to use on the ability's target area while charging.

Sounds and prefabs cannot be added through modding at the moment, so you must reference existing ones. These are all optional, and if not defined there will be no sound / no visual effect.

### Action

The action defines what happens when the ability is used. All abilities must have a "class" parameter that determines which action will be used, and then additional parameters depending on that class. See below for a list of supported actions and usage examples.

In addition to action-specific parameters, all actions can have the following parameters:

"target" - defines how the ability is targeted. The "target" parameter has two child parameters - "type" and "range". Type can be either "Self" or "Position". When the type is Self, it will target Tiny regardless of where the mouse cursor is. When the target is "Position", it will target the position of the mouse cursor, unless it is out of range, then it will target the closest point to the target position within range. The "range" parameter determines the ability's maximum range from tiny. Default range is 99, and default type is Self.

"activate-sound" - sound effect to play when the ability is activated (when the charging is complete, if the ability has charging time)

"effect-prefab" - visual effect to show when the ability is activated.

"static-effect" - set to true if you want the visual effect to remain where the ability was used. Otherwise it will follow its target around (if the ability's target is a unit). Default is false.

### Requires Unlock

```
requires-unlock: true

```

Whether or not you need to unlock this ability before you can use it (through Infrastructure Upgrades for example) before you can use it. For abilities that are used through items, this should always be true and will never be unlocked (you don't need to unlock the ability before you can use a consumable that activates it).

To unlock a construction blueprint, use an unlock Modifier with the "ActiveAbilityType" entry.

## Action Classes

These are the different classes of actions that are currently supported. Each has its own parameters.

### PlayerActionAddStatusEffect

```
overclock: {
	parents: [ "abilities.base.default" ]
	action: {
		class: "PlayerActionAddStatusEffect"
		statuseffect: "overclock"
		duration: 15
		activate-sound: "ability-overclock"
	}
	cooldown: {
		time: 90
	}
}

```

Adds a new status effect to tiny. "statuseffect" defines which status effect to apply (from StatusEffects.json), and "duration" determines how long this effect will last before expriting. See Modding - Status Effects for more information on defining status effects.

This action always applies to Tiny, so the target parameter has no effect.

## PlayerActionAoeDamage

```
overload: {
	parents: [ "abilities.base.default" ]
	action: {
		class: "PlayerActionAoeDamage"
		range: 3
		damage: 60
		effect-prefab: "EffectOveloadPrefab"
		static-effect: true
		activate-sound: "ability-overload"
	}
	charging: {
		time: 0.33
		effect-prefab: "EffectOverloadChargePrefab"
		charging-sound: "ability-charge-overload"
		slow: true
	}
	cooldown: {
		time: 10
	}
}

```

This ability action deals damage to all enemies around the target.

It has a "damage" parameter that determines how much damage will be dealt to each unit, and a "range" parameter that determines the area of effect radius.

## PlayerActionCreateUnit

```
decoy: {
	parents: [ "abilities.base.default", "abilities.base.item-ability" ]
	action: {
		class: "PlayerActionCreateUnit"
		unit: "unit-decoy"
		activate-sound: "ability-decoy"
		target: {
			type: "Position"
		}
	}
	cooldown: {
		time: 90
	}
}

```

This ability action creates a player unit - such as the decoy or placeable turret. It has a "unit" parameter that defines the unit will be spawned. See Modding - Units for more information on defining units.

## PlayerActionHeal

```
repair: {
	parents: [ "abilities.base.default", "abilities.base.item-ability" ]
	cooldown: {
		type: "repair"
		time: 15
	}
	action: {
		class: "PlayerActionHeal"
		activate-sound: "ability-repair"
		effect-prefab: "EffectHealbeamPrefab"
		heal: 50
	}
}

```

The heal ability restores Tiny's health. The "heal" parameter determines how many hit points will be restored when activating this ability (absolute value, it does not scale with Tiny's maximum health).

This action always applies to Tiny, so the target parameter has no effect.

## PlayerActionRepairRadius

```
building-repair: {
	parents: [ "abilities.base.default", "abilities.base.item-ability" ]
	action: {
		class: "PlayerActionRepairRadius"
		range: 8
		activate-sound: "ability-repair"
		effect-prefab: "EffectHealbeamPrefab"
	}
	cooldown: {
		time: 100
	}
}

```

This action fully repairs all buildings in a radius around Tiny. The "range" parameter determines the distance from tiny within which the buildings will be repaired.

This action always applies to Tiny, so the target parameter has no effect.

## PlayerActionTeleportToCity

This action will teleport tiny back to the city center.

## PlayerActionFreeBuilding

```
free-expansion: {
	parents: [ "abilities.base.misc-item" ]
	action: {
		class: "PlayerActionFreeBuilding"
		construction: "citytile"
		activate-sound: "warning-upgrade"
	}
}

```

This action grants the player a free building. "construction" determines which building will be built (see Modding - Construction Blueprints) and the optional "amount" parameter determines how many free constructions will be added (default 1).

## PlayerActionReflection

This action is a collection of several smaller actions. It has a "method" parameter that determines which one of the smaller actions will happen. Possible "methods" are "AddSkillPoints", "ChangeThreatTime", and "ReduceGlobalDifficulty" - all of which receive an "amount" parameter.

**AddSkillPoints** - adds free infrastructure upgrades.

**ChangeThreatTime** - Increases or decreases the threat level an "amount" worth of cycles. When the value is negative, the threat does not decrease, but instead it will stop advanced for the given duration.

**ReduceGlobalDifficulty** - Reduces global infestation by the given amount of skulls.

See Abilities.json for sample uses of this action.