Divinity Codex Item Tags

This document summarizes how DivinityProvider resolves DIVINITY_... Codex item tags, which Divinity item modules are supported, and which suffix parameters are actually honored.

Tag format

Preferred format:

DIVINITY_<module-id>:<item-id>[~level:<n>][~material:<item-type>]

Examples:

DIVINITY_custom_items:starter_sword
DIVINITY_item_generator:common~level:5
DIVINITY_item_generator:common~level:5~material:VANILLA_DIAMOND
DIVINITY_gems:ruby~level:3

Suffix parameters

Parameter	Notes
~level:<n>	Only works for modules marked with * in the module table below. If omitted, Divinity uses -1 internally, which means random level within the item's configured min/max. Parsed values are digits only and are clamped to the item's allowed range.
~material:<item-type>	Only works for item_generator. Passed to GeneratorItem.create(level, -1, material). The value must resolve through Codex item lookup, e.g. VANILLA_DIAMOND. If missing, invalid, or not allowed by the generator's material rules, generation falls back to the configured material pool.

Supported modules

* = ~level:<n> is honored for that module.

Module id	Item base type	Supported suffixes	Example
active_items*	UsableItem	~level	DIVINITY_active_items:blink_scroll~level:2
arrows*	LeveledItem	~level	DIVINITY_arrows:fire_arrow~level:4
consumables*	UsableItem	~level	DIVINITY_consumables:health_potion~level:1
custom_items	ModuleItem	none	DIVINITY_custom_items:starter_sword
dismantle*	LimitedItem	~level	DIVINITY_dismantle:basic_hammer~level:3
essences*	SocketItem	~level	DIVINITY_essences:flame_essence~level:2
extractor*	LimitedItem	~level	DIVINITY_extractor:gem_extractor~level:5
fortify*	LimitedItem	~level	DIVINITY_fortify:fortify_stone~level:3
gems*	SocketItem	~level	DIVINITY_gems:ruby~level:3
identify*	LimitedItem	~level	DIVINITY_identify:common~level:10
item_generator*	LimitedItem	~level, ~material	DIVINITY_item_generator:common~level:5~material:VANILLA_DIAMOND
magic_dust*	LimitedItem	~level	DIVINITY_magic_dust:basic_dust~level:4
money	ModuleItem	none	DIVINITY_money:gold_coin
refine*	RatedItem	~level	DIVINITY_refine:refine_stone~level:4
repair*	LimitedItem	~level	DIVINITY_repair:repair_kit~level:2
runes*	SocketItem	~level	DIVINITY_runes:wind_rune~level:6

Important limitations

• custom_items and money are valid provider modules, but ~level does not affect them.
• There is no provider tag syntax for charges/uses.
• There is no provider tag syntax for rated success, socket success, tier, or any other module-specific runtime value.
• ~material: is only consumed by item_generator.

Optional shorthand

Divinity also supports a shorthand form without a module id:

DIVINITY_<item-id>

Example:

DIVINITY_common

Note

Using this method, the provider scans all supported item modules and returns the first matching item id it finds. This is less explicit and can become ambiguous, so module-qualified tags are strongly preferred.