API Reference

Helix exports ~200 symbols, but you only reach for a couple of dozen when authoring a pack. The rest are the compiler's internals - IR nodes, command handlers, codegen infrastructure - public so the upper layers can build on them, but not something you use to write gameplay.

This page is the curated authoring surface: the classes and factories you actually build packs with, grouped by task. Each links into its full generated page. If you want the exhaustive, every-symbol listing, jump to the full generated reference at the bottom.

Building a pack

Everything hangs off one Datapack. You create functions on it and fill them in against a FunctionContext, where every ctx.<command>() lives.

Symbol	What it's for
Datapack	The pack itself: createFunction, objective, writeDatapack, resource files, report().
FunctionContext	The ctx inside .build() - every command (say, tellraw, if, fill, score ops…) is a method here.
FunctionRef	What createFunction returns; call .build(ctx => …) on it.
version profiles	v1_20_1, v1_20_4, v1_21_4, v26_2 - pass one to new Datapack.

import { Datapack, v26_2 } from "helix";

const dp = new Datapack("demo", v26_2);

const load = dp.createFunction("load");
load.build((ctx) => {
  ctx.say("hello from helix");
});

▶ Open in playground

Compiled output - the real files helix emits for the code above:

data/demo/function/load.mcfunction

say hello from helix

data/minecraft/tags/function/load.json

{
  "values": [
    "demo:load"
  ]
}

Naming a function load (or tick) auto-registers it in the matching minecraft:load / minecraft:tick tag - that's why the tag JSON appears alongside the .mcfunction above.

Targeting entities

Symbol	What it's for
Selector	@a/@e/@p/@s/@r plus a fluent, version-aware filter chain (.tag, .limit, .distance, .gamemode, .nbt, .score…).
ScoreTarget	A score holder - a fake player name or a selector - for objective.score(…).

import { Datapack, v26_2, Selector, text, Color } from "helix";

const dp = new Datapack("demo", v26_2);

const greet = dp.createFunction("greet");
greet.build((ctx) => {
  const admins = Selector.allPlayers().tag("admin").limit(1);
  ctx.tellraw(admins, [
    text("Welcome back, ").color(Color.GRAY),
    text("operator").color(Color.AQUA),
  ]);
});

▶ Open in playground

Compiled output - the real files helix emits for the code above:

data/demo/function/greet.mcfunction

tellraw @a[tag=admin,limit=1] [{"text":"Welcome back, ","color":"gray"},{"text":"operator","color":"aqua"}]

Typed values

Domain concepts are built with their own classes and render version-aware at codegen - never string-interpolated. If a value can't express something yet, the fix is to extend the value's API, not to hand-build a fragment.

Symbol	What it's for
Pos	Coordinates: Pos(x,y,z), Pos.rel(…), Pos.local(…), Pos.here(), .offset, .center.
Block	Block.STONE, Block(id, states), Block.tag(…).
Item	Item stacks with components; renders differently as a give-stack vs predicate JSON.
Nbt	Typed NBT compounds/lists/numbers (Byte/Short/Float/Double/Long).
Id	Namespaced resource ids.

import { Datapack, v26_2, Pos, Block } from "helix";

const dp = new Datapack("demo", v26_2);

const platform = dp.createFunction("platform");
platform.build((ctx) => {
  ctx.fill(Pos.rel(-2, 0, -2), Pos.rel(2, 0, 2), Block.STONE);
  ctx.setblock(Pos.here().offset(0, 1, 0), Block.AIR);
});

▶ Open in playground

Compiled output - the real files helix emits for the code above:

data/demo/function/platform.mcfunction

fill ~-2 ~ ~-2 ~2 ~ ~2 minecraft:stone
setblock ~ ~1 ~ minecraft:air

Scores & math

Symbol	What it's for
Objective	A scoreboard objective (dp.objective(name, kind?)); .score(target) gives a Score.
Score	A live score cell: .set/.add/.remove/.copy and comparisons (.equal, .greaterThan, .lessThan) that become if conditions.
Fixed	Scale-tracked fixed-point scalar for precision-safe runtime math.
ScoreVec3	A 3-vector of scores for runtime vector math.

import { Datapack, v26_2, ScoreTarget } from "helix";

const dp = new Datapack("demo", v26_2);
const score = dp.objective("score");

const reward = dp.createFunction("reward");
reward.build((ctx) => {
  const points = score.score(ScoreTarget("total"));
  ctx.if(points.greaterThan(9), (ctx) => {
    ctx.say("high score!");
    points.set(0, ctx);
  });
});

▶ Open in playground

Compiled output - the real files helix emits for the code above:

data/demo/function/zzz/reward/if_0.mcfunction

say high score!
scoreboard players set total score 0

data/demo/function/reward.mcfunction

execute if score total score matches 9.. run function demo:zzz/reward/if_0

The if body compiles to its own child function - that's why a second .mcfunction appears in the output above.

Text & chat

Symbol	What it's for
text	Build a single styled text span (.color(Color.X), bold/italic, click/hover).
TellrawText	A named, reusable sequence of parts for ctx.tellraw/ctx.title.
ClickEvent / HoverEvent	Interactivity attached to a Text.

Data resources

Loot tables, recipes, predicates, item modifiers, advancements and models are typed builders on the Datapack - the emitted JSON is derived from the same value objects you author commands with.

Symbol	What it's for
Predicate	Referenceable predicate JSON; feeds Selector.predicate.
LootTableDef / ItemModifier	Loot & item-modifier resources.
RecipeDef	Recipe resources.
AdvancementDef / Trigger	Typed advancements.
Model / ItemModel / BlockState	Resource-pack outputs (dp.writeResourcePack).

Build, cost & validation

Symbol	What it's for
buildDatapack	Run codegen in-memory → Map<path, contents> (the disk form is dp.writeDatapack).
analyzeCost / formatCostReport	Worst-case commands/tick and unbounded-@e detection (dp.report()).
validateDatapack	Check emitted JSON against the vanilla schema for the target version (optional Spyglass deps).

---

Full generated reference

Every exported symbol, generated from source with npm run gen:api (build helix first). Reach for these when you need the internals, not just the authoring surface:

• helix - the core compiler (all ~200 exports).
• spool - opt-in conveniences: KitPlugin, installKit, the plugin catalog.
• twine - the opinionated framework: module / area / lifecycle composition, defineItem, StateMachine.

For narrative introductions, start with the Guide; for the authoring concepts in depth, see the helix guide.