This article is updated for Update 15.
Modding Items[]
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.