Custom item system [MAY 17 2026]

About

The custom item descriptor (ITEMS.ITM) is a plain text file with INI format structure, which can be opened by any text editor and edited directly. It allows to create a whole new item or replace existing and fine tune it. This manual intends to help create your own items or modify already existing. It contains detailed description of each parameter and in the File example chapter you will find a file that is ready for use.

Changelog

1. MAY 17 2026

   • New action parameter "CheckRange" has been added.
   • New action parameter "ClipToAmount" has been added.
   • New topic "Extra action parameters" has been added.
   • New item example "Life Essence" has been added.

2. FEB 02 2025

   • Fixed incorrect max amount limit comparison for ammo with "ExtLimits" item flag enabled.
   • Added all game items file example.
   • New action "TeamScore" has been added.
   • New action "Frag" has been added.

How to start

Basically, all you need to do is to create a text file in your current mod directory and rename it to "ITEMS.ITM".

Notes

1. To insert custom item sprites in maps is recommended to use XMAPEDIT. Latest version already have a special button called "User items" that available in the "Game Objects" menu via [ALT+S] in 3D or [SHIFT+S] in 2D edit modes.
2. If you playing Blood in multiplayer, all players must have identical ITEMS.ITM file to avoid desync. If some of players sees "OUT OF SYNC" message once picked up an item, it usually means that something wrong with that file.

Output

The parser doesn't show any modal error messages, however it outputs messages in the console, which is available via pressing the "~" (tilde) key. Start any map or load a save, open the console and look for recent messages that prefixed with "ITEM SETUP" characters to get detailed information. Alternatively, you can open a log file to read such messages.

Global file syntax rules

[General]
Version = 1

Other rules

1. No quotes anywhere.
2. Max characters per line limited by 256.
3. Lines that starts from ";" or "#" characters are comments and ignored by parser.
4. All numeric values must be present in decimal format.
5. There is no floating point values supported.
6. Any letter case is fine.

Supported value types

Before making first descriptor, you must learn the value types the file is working with. Always make sure you write it properly.

Basic value types and keywords

Appearance

Represents associative array with dynamic length. Contains a specific key/value pairs. Allows to override default appearance of objects such as sprites. Write order doesn't matter.

Syntax example:

(Tile=10, Shade=-32, Sound = 777)	// set appearance

Sections and parameters

All sections, except [General] that described in Global file syntax rules topic treated as a start of actual item definition and in-game name. Names must be unique, however, sometimes you may want to have different types with same item name. If that is case, please add "_" character which serving as separator and enter some text just after it.

Example:

[Spray Can] // displaying item name is "Spray Can"
Type = (Weapon, 48) // type 48
.....

[Spray Can_AMMO] // displaying item name remains "Spray Can"
Type = (Ammo, 60) // type 60
.....

Each section may contain several parameters that describes item behavior. Most of them are optional, however they designed to make item to do something useful apart from being just picked up.

Basic parameters

Caption = My item

Appearance = (Tile = 15, Size = 40, Sound=776)

Flags = (NoEffect, NoMessage)

Message = Got fire armor  // shows "Got fire armor"

Message = You got %s item // shows "You got %NAME% item"

GameMode = (S, T, B)

RespawnTime = 3

DropLiveTime = 10

Action parameters or "Actions"

Actions are most interesting part which makes item useful. They allows to change player health or armor, give or remove weapons, set screen effects and much more. Each item supports up to 256 actions that can be combined (for example add 100 health and 50 armor) and/or duplicated. Item can be picked up when at least one action successful, when all actions that marked as required successful, or it have no actions at all. In case when item have any required actions, they must be successful for all other actions to be completed.

Each action key name consist of 2 parts: prefix that defines it's operation and name that defines action type. The value of key represents associative array with dynamic length containing a specific key/value pairs which can be written in random order. Most of them are pretty same for each action.

Operations

Action types

Health Action

Allows to change player's health amount. Cannot be reduced when player is immortal.

Amount = 10

MinAmount = 1

game: auto

extended: 999

MaxAmount = 50

Examples:

SetHealth = (Amount=90,  MinAmount=50, MaxAmount=100)

// set health to 90 units when >= 5 AND <= 100

SubHealth = (Amount=5,  MinAmount=50)

// substract 5 units when > 50

AddHealth = (Amount=10, MaxAmount=100)

// add 10 units when < 100

Armor Action

Allows to change player's armor amount.

Amount = 10

MinAmount = 1

game: auto

extended: 250

MaxAmount = 50

Slot = 1 // body armor

Compatible = False

Examples:

SetArmor = (Amount=100,  MinAmount=50, MaxAmount=200, Slot=3)

// set spirit armor to 100 units when >= 5 AND <= 200

SubArmor = (Amount=5,  MinAmount=50, Slot=1)

// substract 5 units from body armor when > 50

AddArmor = (Amount=10, MaxAmount=100, Slot=2)

// add 10 units to fire armor when < 100

Ammo Action

Allows to change player's weapon ammo amount. Cannot be reduced if have infinite ammo.

Amount = 35

MinAmount = 0

game: auto

extended: 999

MaxAmount = 50

Slot = 2 // flare pistol

Examples:

AddAmmo = (Amount=10, MaxAmount=100, Slot=3)

// add 10 ammo for sawed-off when < 100

SubAmmo = (Amount=5,  MinAmount=50, Slot=9)

// substract 5 ammo from life leech when > 50

SetAmmo = (Amount=20,  MinAmount=0, MaxAmount=100, Slot=2)

// set ammo for flare pistol to 20 when >= 0 AND <= 100

Weapon Action

Allows to give or remove player's weapons. Keep in mind that even if you give a weapon, but it has no ammo - player won't be able to select it. You have to create another action that will add some ammo for it! In multiplayer modes with permanent weapons option enabled item cannot be picked up if player already have weapon, despite item may contain another actions.

Amount = 1

Slot = 2 // napalm launcher

Examples:

AddWeapon = (Amount=1, Slot=3)

// give sawed-off

SubWeapon = (Amount=1, Slot=9)

// take away life leech

SetWeapon = (Amount=0, Slot=2)

// take away flare pistol

PowerTime Action

Allows to change various powerups time. The powerup will toggle it's state automatically according current time amount.

Amount = 35

MinAmount = 0

game: auto

extended: 999

MaxAmount = 50

Slot = 25 // reflective shots

Compatible = False

Examples:

AddPowerTime = (Amount=10, MaxAmount=35, Slot=15)

// add 10 seconds for ivulnerability when < 35

SubPowerTime = (Amount=5,  MinAmount=50, Slot=15)

// substract 5 seconds from ivulnerability when > 50

SetPowerTime = (Amount=20,  MinAmount=0, MaxAmount=100, Slot=15)

// set ivulnerability timer to 20 seconds when >= 0 AND <= 100

Inventory Action

Allows to change player's inventory item amount.

Amount = 100

MinAmount = 0

game: auto

extended: 999

MaxAmount = 50

Slot = 1 // doctor's bag

Examples:

AddInventory = (Amount=10, MaxAmount=100, Slot=1)

// add 10% for doctor's bag when < 100

SubInventory = (Amount=20,  MinAmount=50, Slot=1)

// substract 20% from doctor's bag when > 50

SetPowerTime = (Amount=80, Slot=1)

// set doctor's bag amount to 80%

Key Action

Allows to give or erase keys of player. Keep in mind that Key 7 never shows in player HUD.

Amount = 1

Slot = 2 // eye key

Examples:

AddKey = (Amount=1, Slot=1)

// give skull key

SubKey = (Amount=1, Slot=2)

// erase eye key

SetKey = (Amount=1, Slot=2)

// give eye key

ScreenEffect Action

Allows to set various player screen effects such as pain, delirium, pickup etc. The effects you define with this action replaces default pickup effect. When there is other actions of different type, the effects will play only if at least one of them is completed.

Amount = 35

MinAmount = -128

MaxAmount = 3600

Slot = 1 // pickup effect

Examples:

AddScreenEffect = (Amount=10, MaxAmount=35, Slot=6)

// add 10 units for earthquake effect when < 35

SubScreenEffect = (Amount=5,  MinAmount=50, Slot=1)

// substract 5 units from pickup effect when > 50

SetScreenEffect = (Amount=100, Slot=2)

// set pain effect to 100

AirTime Action

Allows to change player's underwater timer. The greater value, the longer time player can be underwater. Note that using it for items that is not underwater normally makes no sense.

Amount = 10

MinAmount = 5

MaxAmount = 100

Examples:

AddAirTime = (Amount=3)

// add 3 seconds for underwater timer

SubAirTime = (Amount=5)

// substract 5 seconds from underwater timer

SetAirTime = (Amount=120)

// set underwater timer to 120 seconds

IgnoreDamage Action

Allows to change player's permanent damage type vulnerability.

Amount = 1

Slot = 2 // bullet damage

Examples:

AddIgnoreDamage = (Amount=1, Slot=1)

// make player ignore falling damage

SubIgnoreDamage = (Amount=1, Slot=1)

// make player receive falling damage

TeamScore Action

For "Teams" multiplayer mode only. Allows to change player's team score.

Amount = 10

MinAmount = 0

MaxAmount = 100

Examples:

AddTeamScore = (Amount=15)

// add 15 scores to the player's team

SubTeamScore = (Amount=15)

// substract 15 scores from the player's team

Frag Action

Allows to change player's frag amount. Doesn't work in "Cooperative" multiplayer mode.

Amount = 10

MinAmount = 0

MaxAmount = 100

Examples:

AddFrag = (Amount=5)

// add 5 frags to the player

SubFrag = (Amount=15)

// substract 5 frags from the player

Extra global action parameters

CheckRange = Yes

ClipToAmount = No

Required = Yes

File example

Below is a brief example with few new items. You may also download a larger example file which replicates all the original game items.

Slots lists

Armor slots

Powerup slots

These are most interesting:

Inventory slots

Weapon slots

Key item slots

Effect slots

Damage type slots