helix / ItemValue

Class: ItemValue

Defined in: core/values/item.ts:141

An item - id plus an optional, structured definition of its data (name, model data, enchantments, lore, raw components). The single source of truth for an item across the pack: pass the same object to give to grant it, or to Predicate.matchTool(...) / Selector.holding(...) to check for it. It lowers itself per target version (data components on 1.20.5+, NBT before) and per context (item-stack string vs item_predicate JSON) - you never re-encode it.

const excalibur = Item("diamond_sword") .named("Excalibur").enchant("sharpness", 5).modelData(1234);

ctx.playerGive(Selector.nearest(), excalibur); // give …[components] 1 ctx.if(predicateCheck(dp.predicate("excalibur", // if predicate … run … Predicate.matchTool(excalibur))), …);

Bare ids and #tags still work (Item("diamond"), Item("#planks")), and .data(raw) is a verbatim escape hatch for hand-written component/NBT strings.

Implements

• CommandValue

Constructors

Constructor

new ItemValue(id): ItemValue

Defined in: core/values/item.ts:151

Parameters

id

string

Returns

ItemValue

Methods

baseId()

baseId(): string

Defined in: core/values/item.ts:220

The normalized item id with no data/components (minecraft:diamond, #minecraft:planks).

Returns

string

---

component()

component(name, stackValue, predicate?): this

Defined in: core/values/item.ts:210

A raw data component for things the typed builders don't model yet, e.g. .component("unbreakable", "{}"). key/json are optional predicate counterparts so it can still participate in match_tool matching.

Parameters

name

string

stackValue

string

predicate?

json

unknown

key

string

Returns

this

---

componentsJson()

componentsJson(version): Record<string, unknown>

Defined in: core/values/item.ts:367

The item's data components as a { "minecraft:custom_name": ... } map, for a loot/recipe set_components function or any data-file that carries components inline. Built from the same definitions as render/toPredicate, so a loot-granted item matches its give'd / predicate forms. Empty on versions before components, or for an item defined only via raw .data(...) (which can't be parsed back into structured components).

Parameters

version

VersionProfile

Returns

Record<string, unknown>

---

count()

count(n): this

Defined in: core/values/item.ts:160

Stack size carried with the item (used by give; a count range for predicates).

Parameters

n

number

Returns

this

---

data()

data(data): this

Defined in: core/values/item.ts:154

Verbatim data escape hatch ([components] on 1.20.5+, {nbt} before).

Parameters

data

string

Returns

this

---

enchant()

enchant(enchantment, level): this

Defined in: core/values/item.ts:194

Add an enchantment + level (repeatable).

Parameters

enchantment

string | CommandValue

level

number

Returns

this

---

getCount()

getCount(): number | undefined

Defined in: core/values/item.ts:227

The count set via count, if any.

Returns

number | undefined

---

lore()

lore(...lines): this

Defined in: core/values/item.ts:200

Append lore lines (lore / display.Lore). Each line is a string or styled TextComponent.

Parameters

lines

...TextComponent[]

Returns

this

---

model()

model(handle): this

Defined in: core/values/item.ts:188

Point this item at a resource-pack model via its ModelRef (from dp.model(...)) or a bare <ns>:name. Lowers to the item_model component on 1.21.4+; on older versions it needs the ref's legacy custom_model_data number (see ModelRef), else rendering throws.

Parameters

handle

string | ModelRef

Returns

this

---

modelData()

modelData(n): this

Defined in: core/values/item.ts:177

Raw custom_model_data / CustomModelData integer - the escape hatch for a model you manage in an external resource pack. Prefer model with a ModelRef from dp.model(...), which generates the model + emits the typed item_model component instead of a magic number.

Parameters

n

number

Returns

this

---

named()

named(name): this

Defined in: core/values/item.ts:166

custom_name / display.Name. Accepts a plain string or a styled TextComponent.

Parameters

name

TextComponent

Returns

this

---

render()

render(version): string

Defined in: core/values/item.ts:330

The full item-stack string (id + data), version-aware.

Parameters

version

VersionProfile

Returns

string

Implementation of

CommandValue.render

---

renderData()

renderData(version): string

Defined in: core/values/item.ts:317

Just the data fragment appended to the id in stack form ([...]/{...}/"").

Parameters

version

VersionProfile

Returns

string

---

toPredicate()

toPredicate(version): Record<string, unknown>

Defined in: core/values/item.ts:341

This item as an item_predicate JSON object (the body of a match_tool condition, or a recipe/equipment item check). Built from the same component definitions as render, so a give'd item matches its own predicate. Raw .data(...) strings can't be parsed back, so an item defined only that way matches by id alone.

Parameters

version

VersionProfile

Returns

Record<string, unknown>