Modding - Items

## Items

Items are anything that can be produced, carfted, scavenged, etc. This includes resources of all kinds, equipment, consumables, and even some special items such as Research Points and Fuel. Items are defined in the `Items.json` file.

## Base Types

There are a few pre-defined base types for items that the actual item entities inherit from. These base types are used to define common attributes that apply to several production recipes, such as whether they can fly or not, if they are global, and if they can be transported via rails. You can find the base types in the `Items.json` file that is supplied with the Reference Configuration Files.

## Format

Production recipes are defined using the standard Entity Format.

## Item Parameters

This is a list of the different parameters that can be applied to items. Item parameters are almost always optional, a simple resource item can include just its ID and all the rest uses default values.

### Sprite

The sprite parameter is optional. By default, it will search for a sprite called "`item_[item entity ID]`", but you can define a different one using the following format:

```
sprite: "my_item"

```

See Adding Sprites for more information on adding your own image files.

### Is Global

The "is-global" parameter determines whether the item is a global resource, like power, flux, workers and fuel. Global items do not need to be transported, they never exist in the player's or a building's inventory, they only exist in the global inventory. Global items that are produced, crafter or picked up, will automatically be added to the global inventory, and removed from there when consumed.

Global items can also have a limit to the amount you can own. See Type Components below for more information on setting this up.

### Flying, Carting and Tracking

```
can-track: true
cant-fly: true
cancart: false
cartprefab: "cartstarwoodboard1"

```

These parameters affect whether the item is lost when the city flies (raw materials), whether it can be tracked in the top-left HUD section (resources can be tracked, but equipment can't), and whether or not it can be transported through carts (resources that are used or created in production recipes). Note that the "cant-fly" parameter is a negative (when set to true, the item **can't** fly), and all the others are positive.

"cant-fly" and "can-track" are false by default, while "cancart" is true by default (there's no good reason for this, it's just how it was developed).

"cartprefab" defines the model of the item that will e used within the cart when transporting the item. If you leave this out, the cart will appear empty. These prefabs can not be added through modding at the moment, so you will have to use one of the existing ones when adding your own items. See the original config file references to find the model names for the built in items.

### Equipment slots

Items that are equipped, such as weapons, armors and modules - need to have an equipment slot defined. See Type Components below for more information on how to define the equipped item's effects and behavior.

```
equipslot: "mech-upgrade"

```

Available equip slots are "mech-upgrade", "city-upgrade", "armor", "wpn-melee" and "wpn-ranged", however, you can add your own custom slots (similar to the mech/city modules) in the `Config.json` file under "mech".

## Type Components

Type components are used to define special behavior to items, such as weapons, armor, consumables, and items that modify player stats. For more information on how components work, see Modding - Instance and Type Components.

These are the type components available for Item entities:

### ItemComponentGlobalLimit

Add this component to global items so that their storage capacity will be limited. When over capacity, new items will not be produced, and exceeding amounts will be removed according to the "perishtime" setting.

##### Parameters:

"baselimit" - Starting capacity for this item. Additional capacity can be gained through modifiers for buildings, infrastructure upgrades, etc.

"perishtime" - Time in seconds that it takes to lose a single unit, when over capacity. When no perish time is defined, or if the value is 0 or lower, all excess are lost immediately. This can be a problem when a storage building loses power, or is temporarily disabled - all excess will be lost immediately. It is better to set low numbers such as 1, that way it will take a few seconds before the player will loose their excess resources.

```
typecomponents: {
	limit: {
		class: "ItemComponentGlobalLimit"
		perishtime: 1
	}
}

```

### ItemComponentConsumable

Add this component to items that you want the player to be able to use. There are two types of consumables - those that you use through the quickbar (usually fit for combat or movement related consumables), and those that you use by right clicking the item in the inventory window.

##### Parameters:

"quick-bar" - Set to true if you want the player to be able to use this item through the quickbar. Default is true.

"right-click" - Set to true if you want the player to be able to use this item by right clicking it. Default is true.

"ability" - Define the ability to activate when using this item. See Modding - Abilities for more information on defining abilities.

```
typecomponents: {
	consumable: {
		ability: "grenade"
		right-click: false
		quick-bar: true
	}
}

```

### ItemComponentEquipEffect

Add this component to items that the player can equip, if you want to create a positive or negative permanent effect while the item is equipped. Effects can include stat bonuses/penalties, increased global storage capacity, and even unlock abilities, buildings, crafting recipes, etc.

Remember to make sure that you set the "equipslot" parameter so that the player can actually equip these items.

##### Parameters:

"modifiers" - A set of modifiers that are applied when the item is equipped. See Modding - Modifiers for more information on the different options.

"status-effects" - A set of status effects that will be applied on the player unit when this item is equipped. In most cases using modifiers is enough, but status effects have some extra options (like AOE damage) that modifiers do not, and when using a status effect you can have a status effect icon above the health bar, if desired.

```
typecomponents: {
	effects: {
		class: "ItemComponentEquipEffect"
		modifiers: {
			stats: {
				prod-speed: -0.5
				prod-inputamount: -0.25
				~spec: "prodgroup-refine"
				~global: true
			}
		}
	}
}

```

```
typecomponents: {
	aoe: {
		class: "ItemComponentEquipEffect"
		status-effects: {
			ranged-aoe: true
		}
	}
}

```

### ItemComponentArmor

Add this component to items that act as armor. Armor items differ from other equippable items in that they determine Tiny's ***base*** health value (the value on top of which all other modifiers are applied).

Remember to make sure that you set the "equipslot" parameter to "armor" so that the player can equip these items as armor.

##### Parameters:

"health" - The base amount of hit points Tiny will have when this armor is equipped. This value is a Smart Value, not a regular number.

### ItemComponentWeapon

Add this component to items that act as weapons, either melee or ranged. Weapons differ from other equippable items in that they determine how Tiny's attacks behave when they are equipped.

Remember to make sure that you set the "equipslot" parameter to one of the weapon slots, so that the player can equip these items as weapons.

##### Parameters:

"damage" - The base damage for this weapon. This value is a Smart Value, not a regular number.

"dmg-variation" - The variation of the damage, as a fraction. A value of 0.1, for example, that the actual damage is between -10% and +10% of the damage above. Default is 0.2

"range" - The maximum range of projectile weapons. The projectile will disappear after traveling this much.

"behaviour" - The way the weapon behaves. At the moment there are two behaviors, melee and ranged. See existing examples for usage and syntax.

"cooldown" - Time in seconds between attacks. Make sure this is not lower than the time it takes to animate the attack.

"animtime" - How long the player is slowed down after attacking.

"shoot-sound" - Sound effect used when the attack is triggered.

"heat" - Heat generated by the attack. When heat reaches 100, the player will be unable to attack for a fraction of the second. This is used to determine how many attacks in a combo. For example, melee attacks have a heat of 26, so after 4 attacks the combo will end, and will have to wait half a second before the player can attack again.

"auto" - When true, the player can hold the button to continuously attack instead of clicking again and again. At the moment all built-in weapons are automatic.

"projectile-prefab" - The model that is used when the attack is triggered. Despite the name, this applies for melee attacks as well. These are not just visual, they also include that collider that determines the attack hitbox, so don't leave it empty. Prefabs can not be created through modding, so copy it from one of the examples that behaves the way your weapon should.

"burst-count" and "burst-angle" - For shotgun-style weapons, when burst-count is above 1, multiple projectiles will be created within the "burst-angle" instead of a single projectile.

"weapon-prefab" - The model of the weapon itself. New models can't be added through modding so use one of the existing ones.

See the original Weapons.json in the Reference Configuration Files for usage examples.