Modding: Items

This article is updated for Update 15.

Items are defined in the items file Items.txt. To learn more about defining crafting recipes, see Modding: Crafting Recipes.

Items may have many different values, according to the type of item.

**Note**: Every item must have a matching display name in the Texts.txt file using the following format:

```
items.wool.name=Wool
items.wool.description=Resource used in\ncrafting recipes.

```

Description is optional, but newlines must be inserted manually into the description using "\n".

## Item Icon

You may define the name of the icon to use to display for each item. This value is optional, and defaults to "item\_wood" where wood is the item's ID.

Format:

```
items.entity.wood.sprite=item_wood

```

The example above is redundant, because "item\_wood" is the default image for an item with ID "wood" as above. This is useful if you want to use an image of another item instead of supplying a new image.

Item icons are typically 64x64 pixels.

See Modding: Adding Images to Mods for more information on how to add new images.

## Scavenging Values

Each item may appear in relevant scavenge locations if the difficulty tier of the scavenge location equals to or is one tier above the item.

How many of the item are available in the mission depends on the mission difficulty and the item value. The amount of items per stack is determined by the total loot value (defined in Difficulty.txt and depends on the scavenge mission difficulty) divided by the item's value.

```
items.base.level1.value=20
items.base.level1.level=1

items.base.uncommon.valuemul.rarity=2

```

In this example, all items that inherit from "items.base.level1" will only appear in relevant locations in which the mission difficulty is tier 1 or 2. The amount of this item will be determined by the total loot value of the location, divided by the item value which is 20.

The level property also affects when traders offer this item. Make sure all items have a correct level and rarity. The only exception is scraps, which are currency and don't have a level or rarity.

If an item also inherits from "items.base.uncommon", then the item's value will be multiplied by "valuemul" which is 2 for "rarity". So an item that is both "level1" and "uncommon", will have a value of 40. An item may have more than one value multiplier as long as they have different IDs ("rarity" in the example above). If they are the same ID, then only the last one applies.

All the default items have both a level and a rarity, for convenience, but if you wish you may directly define the scavenge values of the item instead of inheriting from a level and a rarity.

You can find all the default levels and rarity nodes in the original configuration files.

See Modding: Map Locations for more information on defining which items are available for scavenge in each map location.

## Item Effects

Items may have effects on different survivors that equip it, using the following format:

```
items.entity.luckycharm.effect.accuracy=0.1
items.entity.luckycharm.effect.evade=0.1

```

In this example, a survivor that equips the item will have 10% bonus to accuracy and 10% bonus to evasion

See Modding: Effect Values for a list of different stats that can be used here.

## Combat Abilities

Items may provide combat abilities when equipped by a survivor, using the following format:

```
items.entity.sandalwood.abilities.healsandalwood=1

```

In this example, equipping the "sandalwood" item in combat gives the survivor the 1 use of "healsandalwood" combat ability. The key holds the ability ID (healsandalwood in this case), and the value is the maximum number of times the ability can be used per combat instance.

See Modding: Combat Abilities for more information on defining what the abilities do.

## Equipable Items

Items may be equipped in weapon, armor or equipment slot using the following format:

```
items.entity.transmutationgun.parents=items.base.weapon

```

In this example, the "transmutationgun" item inherits from "items.base.weapon" that defines all the characteristic of an item that can be equipped in the weapons slot.
The following options exist for equipable items:

* "items.base.weapon" for Weapons
* "items.base.armor" for Armor
* "items.base.usable" for Equipment

## Skill Requirements

You may define a skill requirement to equip an item. Only survivors with a matching skill will be allowed to equip these items.

```
items.entity.sacredsword.skillreq.occultweapon=true

```

In the example above, only survivors that have a skill that unlocks "occultweapon" are able to equip the Sacred Sword.

See Modding: Skills for more information on defining skills that allow equipping these weapons.

## Auras

Equippable items may provide their owner with auras that apply status effects on units around them.

```
items.entity.featherofmaat.parents=items.base.usable,items.base.level2,items.base.rare
items.entity.featherofmaat.auras.lightweight.range=3
items.entity.featherofmaat.auras.lightweight.effect.lightweight=true
items.entity.featherofmaat.auras.lightweight.targetmode=Ally
items.entity.featherofmaat.auras.lightweight.prefab=PositiveAuraPrefab

```

In the example above the "featherofmaat" has a "lightweight" aura that affects allies of 3 tiles, with the "lightweight" status effect.

See Modding: Auras for more information.

## Tagging Items

You may define item categories using tags. These are displayed in the item description, and may be used in other configuration files. For example, some stat bonuses are only applied when an item with a specific tag is equipped (See Modding: Effect Values).

```
items.entity.crossbow.tags.bow=true

```

In this example, the crossbow is tagged as "bow". An item may have more than one tag.

Each tag must have a display name defined in the Texts.txt file using the following format:

```
tags.toolweapon.name=Tools

```

Items tagged with "toolweapon" will appear as "Tools" in the game.

## Weapons

There are a few weapon-specific properties that must be defined in order for an item to be a valid weapon:

```
items.entity.bow.properties.damage=10
items.entity.bow.properties.attackspeed=3
items.entity.bow.properties.range=5
items.entity.bow.properties.accuracy=50
items.entity.bow.properties.attacksound=bow_attack
items.entity.bow.properties.prefab=bow
items.entity.bow.properties.survivorattackanimation=SurvivorBow
items.entity.bow.properties.attackanimation=ArrowPrefab
items.entity.bow.properties.hand=left

```

Each weapon must have damage, attack speed, range, accuracy, prefab and animation values.

Damage, attack speed, range and accuracy of the equipped weapon are used as the base value for all combat calculations. All multiplier bonuses are applied on these base values.

"attacksound" is the sound heard when the weapon fires, and is optional.

"attackmisssound" is the sound heard when the weapon misses, and is optional.

"survivorattackanimation" is the animation that the survivor will use when attacking. This usually depends on the weapon prefab.

"attackanimation" is the name of the projectile/attack effect that spawns when the survivor attack animation sequence completes. This is optional (melee weapons don't have them)

See the original configuration files for available prefab, animation, and sound values.

See Modding: Adding Audio to Mods for more information on adding custom weapon sounds.

## Weapon Hit Effects

Weapons may also have on-hit effects. These status effects will be applied in combat whenever the weapon hits a target.

```
items.entity.demonitebow.hiteffect.demonitecurse=3

```

In the example above, a target hit by the Demonite Bow will suffer from the "demonitecurse" status effect for 3 time units.

See Modding: Status Effects for configuring the effects themselves.

## Weapon Splash Damage

Weapons may deal splash damage to other units around their target:

```
items.entity.shotgun.splash.range=1
items.entity.shotgun.splash.damage=0.5

```

In the above example the shotgun deals 50% of it's damage to units within 1 tile of the target.

See Modding: Splash Damage for more information.

## Armor

Armors must define health, armor and evade values.

```
items.entity.scraparmor.armormodel=armor2
items.entity.scraparmor.armortexture=scraparmor_color
items.entity.scraparmor.properties.health=100
items.entity.scraparmor.properties.evade=25
items.entity.scraparmor.properties.defense=1

```

These values are used as base values for all combat calculations. Survivors with no armor equipped have 75 health, 0 armor and 20 evade.

The "armormodel" and "armortexture" properties determine what the armor will appear like when worn by a survivor. There are 3 armor models: "armor1", "armor2" and "armor3" that determine the shape of the armor. The texture determines the coloring of the model. Textures must match their model, you can't have a sleeveless texture applied to a full body armor.

## Food

For an item to be eddible, it must be defined as a food item:

```
items.entity.salad.food=true

```

You should also tag food items appropriately so that they are counted in the "Gather food items" campaign misison:

```
items.entity.salad.tags.food=true

```

See Modding: Food for more information on defining bonuses from eating several food types.

## Base Use Items

Base use items are items that you can use in the base (outside of combat) for temporary or permanent bonuses. Base use items should inherit the "items.base.baseuse" base class.

```
items.entity.songofglory.parents=items.base.baseuse,items.base.level2,items.base.rare
items.entity.songofglory.baseaction.use.class=BaseActionAddSkill
items.entity.songofglory.baseaction.use.skill=songofglory

```

In the example above, the "songofglory" item may be consumed to give a survivor the "songofglory" skill.

See the original Items.txt for possible classes of base use items.

## Gather Limits

If you wish to allow the player to set gather limits for this item, use the following format:

```
items.entity.water.gatherlimits=true

```

You can then define a matching action in Objects.txt that will use this item's gathering limit values to automatically disable the task when the limits have been reached.