Appearance
helix / Datapack
Class: Datapack
Defined in: core/ir/datapack.ts:64
Constructors
Constructor
new Datapack(
name,version,target?):Datapack
Defined in: core/ir/datapack.ts:112
Parameters
name
string
version
target?
RuntimeTarget = DEFAULT_TARGET
Returns
Datapack
Properties
files
files:
Map<string,string>
Defined in: core/ir/datapack.ts:99
functions
functions:
Map<string,FunctionNode>
Defined in: core/ir/datapack.ts:74
name
name:
string
Defined in: core/ir/datapack.ts:65
tags
tags:
Map<FunctionTag,Set<string>>
Defined in: core/ir/datapack.ts:100
target
target:
RuntimeTarget
Defined in: core/ir/datapack.ts:73
The runtime this build targets (see RuntimeTarget). Read at codegen via ctx.target; only ctx.native(...) ops branch on it. Set per build so the same source compiles to a portable "vanilla" pack and a "paper" server pack. Swap via useTarget.
timing
timing:
TimingStrategy
Defined in: core/ir/datapack.ts:103
How run-for-a-duration / periodic timing compiles. Swap via useTiming.
version
readonlyversion:VersionProfile
Defined in: core/ir/datapack.ts:66
Accessors
advancementDefs
Get Signature
get advancementDefs():
ReadonlyMap<string,AdvancementDef>
Defined in: core/ir/datapack.ts:290
Registered advancements (name → definition), for codegen.
Returns
ReadonlyMap<string, AdvancementDef>
assetSources
Get Signature
get assetSources(): readonly
string[]
Defined in: core/ir/datapack.ts:522
Source directories registered via addAssets, for codegen.
Returns
readonly string[]
blockModelDefs
Get Signature
get blockModelDefs():
ReadonlyMap<string,Model>
Defined in: core/ir/datapack.ts:471
Registered block models (name → definition), for resource-pack codegen.
Returns
ReadonlyMap<string, Model>
blockStateDefs
Get Signature
get blockStateDefs():
ReadonlyMap<string,BlockState>
Defined in: core/ir/datapack.ts:491
Registered block states (<ns>:<block> → definition), for codegen.
Returns
ReadonlyMap<string, BlockState>
clearStructureVariants
Get Signature
get clearStructureVariants():
ReadonlyMap<string,ClearFill>
Defined in: core/ir/datapack.ts:205
Requested _clear variants (path → fill block), for codegen.
Returns
ReadonlyMap<string, ClearFill>
itemDefinitionDefs
Get Signature
get itemDefinitionDefs():
ReadonlyMap<string,ItemDefinition>
Defined in: core/ir/datapack.ts:455
Registered item definitions (name → definition), for resource-pack codegen.
Returns
ReadonlyMap<string, ItemDefinition>
itemModifierDefs
Get Signature
get itemModifierDefs():
ReadonlyMap<string,ItemModifier>
Defined in: core/ir/datapack.ts:333
Registered item modifiers (name → definition), for codegen.
Returns
ReadonlyMap<string, ItemModifier>
lootTableDefs
Get Signature
get lootTableDefs():
ReadonlyMap<string,LootTableDef>
Defined in: core/ir/datapack.ts:319
Registered loot tables (name → definition), for codegen.
Returns
ReadonlyMap<string, LootTableDef>
modelDefs
Get Signature
get modelDefs():
ReadonlyMap<string,Model>
Defined in: core/ir/datapack.ts:422
Registered models (name → definition), for resource-pack codegen.
Returns
ReadonlyMap<string, Model>
predicateDefs
Get Signature
get predicateDefs():
ReadonlyMap<string,Predicate>
Defined in: core/ir/datapack.ts:273
Registered predicates (name → definition), for codegen.
Returns
ReadonlyMap<string, Predicate>
recipeDefs
Get Signature
get recipeDefs():
ReadonlyMap<string,RecipeDef>
Defined in: core/ir/datapack.ts:347
Registered recipes (name → definition), for codegen.
Returns
ReadonlyMap<string, RecipeDef>
registryFileDefs
Get Signature
get registryFileDefs():
ReadonlyMap<string,unknown>
Defined in: core/ir/datapack.ts:393
Registered raw registry files (<folder>/<name> → JSON), for codegen.
Returns
ReadonlyMap<string, unknown>
registryTagDefs
Get Signature
get registryTagDefs():
ReadonlyMap<string,RegistryTag>
Defined in: core/ir/datapack.ts:378
Registered registry tags (<registry>/<name> → body), for codegen.
Returns
ReadonlyMap<string, RegistryTag>
resourceFileDefs
Get Signature
get resourceFileDefs():
ReadonlyMap<string,unknown>
Defined in: core/ir/datapack.ts:505
Registered raw resource files (<folder>/<name> → JSON), for codegen.
Returns
ReadonlyMap<string, unknown>
structureSources
Get Signature
get structureSources(): readonly
string[]
Defined in: core/ir/datapack.ts:179
Source directories registered via addStructures, for codegen.
Returns
readonly string[]
Methods
addAssets()
addAssets(
dir):this
Defined in: core/ir/datapack.ts:516
Ship every file under dir (recursively) verbatim into the resource pack's assets/ tree, preserving subfolders - for pre-made models, textures, and assets from an existing pack (e.g. custom blocks). Mirrors addStructures; copied at writeResourcePack time. dir should contain a <ns>/… (or minecraft/…) layout as it will sit directly under assets/.
Parameters
dir
string
Returns
this
addStructures()
addStructures(
dir):this
Defined in: core/ir/datapack.ts:173
Ship every .nbt under dir (recursively) into this pack's structure folder - data/<ns>/<structure|structures>/<relative path>.nbt, picking the folder name from the target version. A file cog.nbt becomes the template id <ns>:cog, loadable with /place template (see Clip.swaps). Copied verbatim at writeDatapack time (binary, not generated).
Parameters
dir
string
Returns
this
advancement()
advancement(
name,def):Advancement
Defined in: core/ir/datapack.ts:284
Register an AdvancementDef as data/<ns>/<advancement folder>/<name>.json and return an Advancement id (<ns>:name) to reference it (e.g. from ctx.advancement().revokeOnly(...)). Re-registering the same name throws unless the definition is identical by reference (so shared modules can declare once without ordering hazards), mirroring Datapack.predicate.
Parameters
name
string
def
Returns
blockModel()
blockModel(
name,def):ModelRef
Defined in: core/ir/datapack.ts:465
Register a block Model as assets/<ns>/models/block/<name>.json and return a ModelRef (<ns>:block/<name>) to reference from a BlockState variant. No item definition (blocks aren't items). Re-registering the same name with a different model throws.
Parameters
name
string
def
Returns
blockState()
blockState(
block,def):void
Defined in: core/ir/datapack.ts:481
Register a BlockState overriding the appearance of an existing block (block is a block id - namespace defaults to minecraft:, since blockstate files target real block ids), emitted as assets/<ns>/blockstates/<path>.json. Re-registering the same block with a different definition throws.
Parameters
block
string
def
Returns
void
createFunction()
createFunction(
name, ...tags):FunctionRef
Defined in: core/ir/datapack.ts:556
Parameters
name
string
tags
...FunctionTag[]
Returns
everySeconds()
everySeconds(
seconds,phase?):FunctionRef
Defined in: core/ir/datapack.ts:241
A hook function that runs every seconds seconds (scoreboard clock). phase (in ticks) staggers it within the period - see everyTicks.
Parameters
seconds
number
phase?
number = 0
Returns
everyTicks()
everyTicks(
ticks,phase?):FunctionRef
Defined in: core/ir/datapack.ts:255
A hook function that runs every ticks ticks (scoreboard clock). phase offsets it within the period so several same-period hooks fire on different ticks, spreading per-tick load instead of bunching it.
Parameters
ticks
number
phase?
number = 0
Returns
functionRef()
functionRef(
name):FunctionRef|undefined
Defined in: core/ir/datapack.ts:579
A ref to an already-created function, or undefined if none exists.
Parameters
name
string
Returns
FunctionRef | undefined
getOrCreateFunction()
getOrCreateFunction(
name, ...tags):FunctionRef
Defined in: core/ir/datapack.ts:568
Like createFunction, but reuses an existing function node when one already exists under name (so multiple authors can append to it - e.g. several animated displays adding their setup to the shared load).
Parameters
name
string
tags
...FunctionTag[]
Returns
itemDefinition()
itemDefinition(
name,model,options?,legacyModelData?):ModelRef
Defined in: core/ir/datapack.ts:437
Register a full typed ItemModel as the item definition assets/<ns>/items/<name>.json (1.21.4+), returning a ModelRef (<ns>:name) to attach with Item.X.model(ref). This is the rich sibling of model: use it for the branching item-model arms (condition, select, range_dispatch, composite, special) and tints; model is the flat case. The ItemModel's model references must point at models emitted by model/blockModel or shipped via addAssets. Pass legacyModelData to also work on versions predating the item_model component. Re-registering the same name with a different definition throws.
Parameters
name
string
model
options?
handAnimationOnSwap?
boolean
oversizedInGui?
boolean
legacyModelData?
number
Returns
itemModifier()
itemModifier(
name,modifier):ItemModifierRef
Defined in: core/ir/datapack.ts:327
Register an ItemModifier as data/<ns>/<item_modifier folder>/<name>.json and return an ItemModifierRef (<ns>:name) for /item modify ... <ref>.
Parameters
name
string
modifier
Returns
load()
load(
builder):FunctionRef
Defined in: core/ir/datapack.ts:613
Append to the load function (runs on pack load / /reload).
Parameters
builder
(ctx) => void
Returns
lootTable()
lootTable(
name,table):LootTableRef
Defined in: core/ir/datapack.ts:313
Register a LootTableDef as data/<ns>/<loot_table folder>/<name>.json and return a LootTableRef (<ns>:name) to reference it from /loot ... loot, a container set_loot, or a nested loot entry.
Parameters
name
string
table
Returns
model()
model(
name,def,legacyModelData?):ModelRef
Defined in: core/ir/datapack.ts:409
Register a Model as assets/<ns>/models/item/<name>.json and (on 1.21.4+) its item definition assets/<ns>/items/<name>.json, returning a ModelRef (<ns>:name) to attach with Item.X.model(ref). Pass legacyModelData to also work on versions predating the item_model component (they reference the model by that custom_model_data number). Re-registering the same name with a different Model throws.
Parameters
name
string
def
legacyModelData?
number
Returns
objective()
objective(
name,kind?):Objective
Defined in: core/ir/datapack.ts:540
Parameters
name
string
kind?
ObjectiveKind = "dummy"
Returns
onFinalize()
onFinalize(
fn):void
Defined in: core/ir/datapack.ts:226
Register work to run once at datapack finalisation (before codegen), after all authoring is done - used by deferred emitters like AnimatedDisplay so chained config (e.g. .forSeconds(...)) is settled before they emit.
Parameters
fn
() => void
Returns
void
predicate()
predicate(
name,predicate):PredicateRef
Defined in: core/ir/datapack.ts:267
Register a Predicate as data/<ns>/<predicate folder>/<name>.json and return a PredicateRef (<ns>:name) to reference it from Selector.predicate(...) (@e[predicate=...]) or predicateCheck(...) (if predicate ...). Re-registering the same name throws unless the predicate object is identical by reference (so shared modules can declare once without ordering hazards).
Parameters
name
string
predicate
Returns
printReport()
printReport():
CostReport
Defined in: core/ir/datapack.ts:160
Convenience: run report and print the formatted summary.
Returns
recipe()
recipe(
name,recipe):RecipeRef
Defined in: core/ir/datapack.ts:341
Register a RecipeDef as data/<ns>/<recipe folder>/<name>.json and return a RecipeRef (<ns>:name) for /recipe give|take.
Parameters
name
string
recipe
Returns
registryFile()
registryFile(
folder,name,json):void
Defined in: core/ir/datapack.ts:388
Escape hatch for data types without a typed builder yet (custom dimensions, worldgen, damage types, enchantments, chat types, dialogs, ...): write json verbatim to data/<ns>/<folder>/<name>.json. folder is the registry path (e.g. "dimension", "worldgen/configured_feature", "damage_type").
Parameters
folder
string
name
string
json
unknown
Returns
void
report()
report():
CostReport
Defined in: core/ir/datapack.ts:153
Static per-tick cost analysis: walks the call graph rooted at the tick tag to report worst-case commands/tick and flag functions doing unbounded @e scans. Runs codegen first (into dp.files), so call it once authoring is done. Pure analysis - emits nothing and does not write to disk. Pass through formatCostReport (or printReport) for a readable summary.
Returns
requestClearVariant()
requestClearVariant(
structureId,fill):void
Defined in: core/ir/datapack.ts:190
Register a derived _clear variant of a shipped structure (see Clip.clearWith): structureId is the structure's /place template id (<ns>:path or bare path); fill is the block its solid cells become. codegen emits <path>_clear.nbt with that single-block palette and the air cells dropped. Requesting the same structure with a conflicting fill throws.
Parameters
structureId
string
fill
ClearFill
Returns
void
resourceFile()
resourceFile(
folder,name,json):void
Defined in: core/ir/datapack.ts:500
Escape hatch for resource-pack files without a typed builder yet (sounds.json, fonts, blockstates, atlases, …): write json verbatim to assets/<ns>/<folder>/<name>.json. Mirrors registryFile on the data side.
Parameters
folder
string
name
string
json
unknown
Returns
void
runFinalizers()
runFinalizers():
void
Defined in: core/ir/datapack.ts:231
Run all registered finalizers exactly once (idempotent).
Returns
void
tag()
tag(
registry,name,spec):void
Defined in: core/ir/datapack.ts:358
Register a registry tag (block, item, fluid, entity_type, ...) as data/<ns>/tags/<registry>/<name>.json. Distinct from the function tags (load/tick). Re-registering the same <registry>/<name> appends values (so several modules can extend one tag); pass replace: true to drop members contributed by lower-priority packs. Values are member ids or #tag refs.
Parameters
registry
string
name
string
spec
replace?
boolean
values
string[]
Returns
void
tick()
tick(
builder):FunctionRef
Defined in: core/ir/datapack.ts:620
Append to the tick function (runs every game tick).
Parameters
builder
(ctx) => void
Returns
untag()
untag(
name,tag):void
Defined in: core/ir/datapack.ts:590
Remove name from a function tag (load/tick) without deleting the function itself. Mechanism only: lets a higher layer reparent a self-tagged function (e.g. route every tick member through one owned dispatcher) - it states no policy about whether you should.
Parameters
name
string
tag
FunctionTag
Returns
void
useTarget()
useTarget(
target):this
Defined in: core/ir/datapack.ts:216
Set the runtime this build targets (default: "vanilla"). See RuntimeTarget.
Parameters
target
Returns
this
useTiming()
useTiming(
strategy):this
Defined in: core/ir/datapack.ts:210
Replace the timing backend (default: scoreboard). See TimingStrategy.
Parameters
strategy
TimingStrategy
Returns
this
writeDatapack()
writeDatapack(
outputPath):Promise<void>
Defined in: core/ir/datapack.ts:130
Write this pack to outputPath (functions, tags, data resources, structures, pack.mcmeta). The disk-writing code lives in codegen/write.ts and is loaded lazily via dynamic import(), so merely importing helix (or building a pack in-memory with buildDatapack) never pulls in Node's fs/path - that's what lets the compiler run in a browser. Consequently this is async; await it if you need the files on disk before continuing.
Parameters
outputPath
string
Returns
Promise<void>
writeResourcePack()
writeResourcePack(
outputPath):Promise<void>
Defined in: core/ir/datapack.ts:534
Write this pack's resource pack (assets/ + a resource-format pack.mcmeta) to outputPath - a separate pack from writeDatapack (own folder, own format). Emits generated models + item definitions + resourceFile JSON and copies addAssets dirs verbatim. Async for the same reason as writeDatapack: the disk path is dynamic-imported so the compiler stays browser-safe.
Parameters
outputPath
string
Returns
Promise<void>