Weapons

Root folder: ../datafiles/mods/mod-name/items/weapons/

Every weapon is defined in its own .json file. The filename must match the weapon’s item_key.
During game initialization, these files are read and loaded into memory.

Parameter	Description	Example
item_key	The unique identifier of the item.	sword_immersive_equipment_arcane_short_sword
item_level	The item level affects whether the item can be dropped based on the enemy’s level or player’s level.	10
genus	The item’s genus used for certain German translations. Values: „m„, „f„, „n„	m
value	The item’s price.	100
loot_chance	The chance for the item to drop as random loot. Range: 0 – 1 0: does not drop as random loot 1: maximum chance to be dropped as random loot	1
lang_name	The item’s name.	sword_arcane_short_sword_name
lang_desc	The item’s description.	sword_arcane_short_sword_desc
weapon_type	The item’s subtype. Values: „sword„, „rapier„, „greatsword„, „staff„, „spear„, „bow„, „rune„, „shield„, „fist„, „throwable„	sword
requirements	Defines the stat requirements the player need to equip the item.	{ „VIT“: 0, „END“: 0, „MAG“: 0, „STR“: 3, „DEX“: 0, „INT“: 5, „LCK“: 0 }
damage_scaling	The scaling of the weapon based on the player’s stats.	{ „STR“: 0.05, „DEX“: 0, „INT“: 0.1, „LCK“: 0 }
is_unique	Whether the item’s rarity is unique. Values: true, false	false
prefix_chance	The chance to roll a random Prefix within the item’s level range. Range: 0 – 1 0: no Prefix possible 1: maximum chance to roll a Prefix	0.3
suffix_chance	The chance to roll a random Suffix within the item’s level range. Range: 0 – 1 0: no Suffix possible 1: maximum chance to roll a Suffix	0.3
asset_icon	The icon shown in the inventory. References a Sprite.	spr_immersive_equipment_weapon_attack_short_sword_icon
animations	The item’s animation when equipped by the player. The „following „animations“ object contains the following animations „idle“, „move“, „attack“, each referencing a Sprite.	{ „idle“: „spr_immersive_equipment_weapon_attack_short_sword_idle“, „move“: „spr_immersive_equipment_weapon_attack_short_sword_move“, „attack“: „spr_immersive_equipment_weapon_attack_short_sword_attack“ }
animations_special	(optional) Special animations needed for certain skills. Primarily needed for block animation of the „sword“ weapon type.	{ „block_shield“: „spr_immersive_equipment_weapon_attack_short_sword_block“ }
attack	The primary attack of the weapon. References a Skill.	{ „skill_key“: „skill_melee_sword“, „skill_override“: { „skill_properties_damage“: { „damage_physical“: 10, „damage_fire“: 1, „damage_ice“: 1, „damage_holy“: 1, „damage_dark“: 1 } } }
skills	(optional) Additional skills the item always has assigned. Contains a list of referenced Skills.	[ { „skill_key“: „skill_dodge“ } ]
skills_random	(optional) Additional skills the item randomly has assigned. Contains a list of referenced Skills. Requires skills_random_data to be defined.	[ { „skill_key“: „skill_missile_flame_ring_2“ }, { „skill_key“: „skill_missile_ice_triad_2“ }, { „skill_key“: „skill_timed_effect_word_of_healing“ } ]
skills_random_data	(only required if skills_random is set) Defines the minimum and maximum amount of skills to be rolled from the skills_random list.	{ „min“: 1, „max“: 2 }
mods	(optional) Additional item modifications (Affixes) the item always has assigned. Contains a list of Affixes.	{ „name“: „add_status_bonus_regeneration_mana“, „values“: { „from“: 0.25, „to“: 0.50 } } ]
mods_random	(optional) Additional item modifications (Affixes) the item randomly has assigned. Contains a list of Affixes. Requires mods_random_data to be defined.	[ { „name“: „add_damage“, „values“: { „damage_fire_percent“: { „from“: 0.05, „to“: 0.15 } } }, { „name“: „add_damage“, „values“: { „damage_ice_percent“: { „from“: 0.05, „to“: 0.15 } } } ]
mods_random_data	(only required if mods_random is set) Defines the minimum and maximum amount of item modifications (Affixes) to be rolled from the mods_random list. Optionally, a pre-defined random_item_mods_source_key can be provided as a source for the random Affixes.	{ „random_item_mods_source_key“: „weapon_mods_epic_1“, „min“: 2, „max“: 4 }
sockets	(optional) The amount of sockets the item can roll.	{ „min“: 1, „max“: 3 }
rarity_variations	(optional) tbd

Best practices

The easiest way to set up new items is to copy an existing item definition, ideally of the same weapon_type, and change the necessary information.

Each item must be assigned a unique key.  To prevent conflicts with other mods or base assets, it is recommended to use a composite naming scheme that includes the mod identifier (e.g. „immersive_equipment“) and the item’s descriptive name (e.g. „arcane_short_sword“). A consistent prefix per weapon type can further help distinguish weapons (e.g. „sword_“, „rapier_“, „staff_“, …).

The lang_name must not necessarily reference to a key of the Language.csv. This is only required to support multiple languages. If lang_desc is not found in the Language.csv, it is not shown.

To test weapons, the in-game Debug Commands can be used to spawn items.

Example Definitions

Arcane Short Sword

{
	"item_key": "sword_immersive_equipment_arcane_short_sword",
	"item_level": "8",
	"genus": "n",
	"value": "160",
	"loot_chance": "0.4",
	"lang_name": "sword_arcane_short_sword_name",
	"lang_desc": "sword_arcane_short_sword_desc",
	"weapon_type": "sword",
	"requirements": {
		"VIT": 0,
		"END": 0,
		"MAG": 0,
		"STR": 3,
		"DEX": 0,
		"INT": 5,
		"LCK": 0
	},
	"damage_scaling": {
		"STR": 0.05,
		"DEX": 0,
		"INT": 0.1,
		"LCK": 0
	},
	"is_unique": false,
	"prefix_chance": "0.1",
	"suffix_chance": "0.1",
	"asset_icon": "spr_immersive_equipment_weapon_attack_short_sword_icon",
	"animations": {
		"idle": "spr_immersive_equipment_weapon_attack_short_sword_idle",
		"move": "spr_immersive_equipment_weapon_attack_short_sword_move",
		"attack": "spr_immersive_equipment_weapon_attack_short_sword_attack"
	},
	"animations_special": {
		"block_shield": "spr_immersive_equipment_weapon_attack_short_sword_block"
	},
	"attack": {
		"skill_key": "skill_melee_sword",
		"skill_override": {
			"skill_properties_damage": {
				"damage_physical": 10,
				"damage_fire": 1,
				"damage_ice": 1,
				"damage_holy": 1,
				"damage_dark": 1
			}
		}
	},
	"skills": [],
	"mods": [{
			"name": "passive.parry"
		}
	],
	"sockets": {
		"min": 0,
		"max": 2,
	}
}

Dagger + Epic Variation (from the base game)

{
	"item_key": "rapier_dagger",
	"item_level": "1",
	"genus": "m",
	"value": "10",
	"loot_chance": "1",
	"lang_name": "rapier_dagger_name",
	"lang_desc": "rapier_dagger_desc",
	"weapon_type": "rapier",
	"requirements": {
		"VIT": 0,
		"END": 0,
		"MAG": 0,
		"STR": 0,
		"DEX": 0,
		"INT": 0,
		"LCK": 0
	},
	"damage_scaling": {
		"STR": 0,
		"DEX": 0.1,
		"INT": 0,
		"LCK": 0
	},
	"poise_ratio": 0,
	"prefix_chance": "0",
	"suffix_chance": "0",
	"asset_icon": "spr_weapon_rapier_dagger_icon",
	"animations": {
		"idle": "spr_weapon_rapier_dagger_idle",
		"move": "spr_weapon_rapier_dagger_move",
		"attack": "spr_weapon_rapier_dagger_attack"
	},
	"attack": {
		"skill_key": "skill_melee_rapier",
		"skill_override": {
			"skill_properties_damage": {
				"damage_physical": 1
			}
		}
	},
	"skills": [{
			"skill_key": "skill_dodge"
		}
	],
	"rarity_variations": [
		{
			"rarity": "epic",
			"item_key": "rapier_dagger::epic",
			"item_level": "16",
			"value": "400",
			"loot_chance": ".10",
			"requirements": {
				"VIT": 0,
				"END": 0,
				"MAG": 0,
				"STR": 0,
				"DEX": 28,
				"INT": 0,
				"LCK": 0
			},
			"damage_scaling": {
				"STR": 0,
				"DEX": 0.40,
				"INT": 0,
				"LCK": 0
			},
			"attack": {
				"skill_key": "skill_melee_rapier",
				"skill_override": {
					"skill_properties_damage": {
						"damage_physical": 23
					}
				}
			},
			"sockets": {
				"min": 3,
				"max": 3,
			},
			"mods_random_data": {
				"random_item_mods_source_key": "weapon_mods_epic_1",
				"min": 2,
				"max": 4
			}
		}
	]
}