Appearance
twine / ItemBuilder
Class: ItemBuilder
Defined in: item.ts:27
Fluent builder for a custom item that does things. Wrap the same Item you'd give (the single source of truth for its data) and attach opt-in behaviours; toModule(name) turns it into a drop-in ConfiguredModule you list in a parent module's imports. Only attached behaviours emit anything.
const wand = defineItem(Item.STICK.named("Frost Wand").modelData(7)) .give() .onAttack((ctx) => ctx.effect().give(Selector.self(), "slowness", 5)) .onHeldTick((ctx) => ctx.particle(...));
@Module({ name: "courtyard", imports: [wand.toModule("frost_wand")] })
Constructors
Constructor
new ItemBuilder(
item):ItemBuilder
Defined in: item.ts:35
Parameters
item
ItemValue
Returns
ItemBuilder
Methods
give()
give():
this
Defined in: item.ts:50
Emit a /function <ns>:zzz/item/<slug>/give that grants the fully-built item to @s.
Returns
this
holderSelector()
holderSelector(
dp):Selector
Defined in: item.ts:99
The held-detection selector: an @a matching whoever is holding this item, via its (once-)registered holding predicate. For consumers that drive their own tick loop instead of onHeldTick - refine it (.volume(...)) and detect holders the same way the item is defined/given. Needs the Datapack to register the predicate.
Parameters
dp
Datapack
Returns
Selector
matchExact()
matchExact():
this
Defined in: item.ts:44
Detect this item by its full identity (components/NBT), not just its base id. By default held-detection keys on the base id alone (cheap, and shared with any other definition of the same base item); call this when two items share a base id but must be told apart - e.g. a custom-modelled lantern vs a plain one. See HoldingOptions.exact.
Returns
this
onAttack()
onAttack(
body):this
Defined in: item.ts:62
Run body (as the attacker) when the player damages an entity while holding the item.
Parameters
body
Returns
this
onHeldTick()
onHeldTick(
body):this
Defined in: item.ts:56
Run body every tick, as (and at) each player holding the item.
Parameters
body
Returns
this
onRightClick()
onRightClick(
body):this
Defined in: item.ts:87
Run body (as and at the holder) on right-click, detected via the used:<item> statistic - the reliable carrot-/warped-fungus-on-a-stick technique that works for items onUse can't see. Costs one tick command + a scoreboard objective; gated by this item's holding predicate so only this custom item triggers. Use matchExact when several custom items share the same base id.
Parameters
body
Returns
this
onUse()
onUse(
body):this
Defined in: item.ts:74
Run body (as the user) when the player uses the item, via a minecraft:using_item advancement. Fires for items the game treats as "in use" on right-click (food, bow, shield, spyglass, …); for items with no use action (a plain stick, a carrot-on-a-stick), it may never fire - reach for onRightClick instead.
Parameters
body
Returns
this
register()
register(
dp):FunctionRef|undefined
Defined in: item.ts:124
Materialise this item's event behaviours straight into dp - the give function plus the onUse/onAttack self-revoking advancements - for consumers wiring an item without the module tree (the full sibling of registerGive). Returns the give FunctionRef when give() was set, else undefined.
onHeldTick is not wired here: the held sweep needs the framework's tick loop, which only toModule (a module in the tree) provides. Calling this with a held behaviour attached throws, so the drop isn't silent.
Parameters
dp
Datapack
Returns
FunctionRef | undefined
registerGive()
registerGive(
dp):FunctionRef
Defined in: item.ts:108
Emit the give function and return its FunctionRef, for consumers that wire it up directly (e.g. register(dp)) rather than via toModule. Idempotent - many callers share one file.
Parameters
dp
Datapack
Returns
FunctionRef
toModule()
toModule(
name):ConfiguredModule
Defined in: item.ts:135
Compile to a drop-in ConfiguredModule (name = module/scoreboard id).
Parameters
name
string