Skip to content

helix / FunctionContext

Class: FunctionContext

Defined in: core/frontend/context/index.ts:13

The author-facing context. It is just the shared plumbing (ContextBase): emit/call/version/child functions. EVERY ctx.<command>() method - sugar (say, tellraw, score ops, if, give, …) and vanilla (weather, effect, …) alike - is a FunctionContext.prototype augmentation that lives WITH its command in src/core/commands/<cmd>.ts (interface + prototype). Importing src/core/commands (done by the frontend barrel) installs them all, so each command is fully self-contained and the public API stays ctx.<command>(...).

Extends

  • ContextBase

Constructors

Constructor

new FunctionContext(fn, _version): FunctionContext

Defined in: core/frontend/context/base.ts:15

Parameters

fn

FunctionNode

_version

VersionProfile

Returns

FunctionContext

Inherited from

ContextBase.constructor

Properties

_version

protected _version: VersionProfile

Defined in: core/frontend/context/base.ts:19

Inherited from

ContextBase._version


fn

fn: FunctionNode

Defined in: core/frontend/context/base.ts:18

Inherited from

ContextBase.fn

Accessors

version

Get Signature

get version(): VersionProfile

Defined in: core/frontend/context/base.ts:23

The target version, so child contexts and helpers can gate on it.

Returns

VersionProfile

Inherited from

ContextBase.version

Methods

advancement()

advancement(): AdvancementBuilder

Defined in: core/commands/advancement.ts:75

advancement - ctx.advancement()...

Returns

AdvancementBuilder


atEntity()

atEntity(selector, build, align?): void

Defined in: core/commands/at_entity.ts:68

Run the commands emitted in build anchored at selector's position with one execute at <selector> [align <axes>] run …. A single command inlines into the run clause; multiple commands commit to one child function and the wrapper runs … run function <child> - so the selector is evaluated once, not re-scanned per command (important when it's an expensive @a[…,nbt={…}] filter). Pass align (e.g. "xyz") to snap the anchor to the block grid first - needed when block ops (fill/place) ride an entity at a fractional position.

Parameters

selector

Selector

build

(ctx) => void

align?

Swizzle

Returns

void


attribute()

attribute(): AttributeBuilder

Defined in: core/commands/attribute.ts:71

attribute - ctx.attribute()...

Returns

AttributeBuilder


ban()

ban(targets, reason?): BanBuilder

Defined in: core/commands/ban.ts:25

ban - ctx.ban()...

Parameters

targets

Selector

reason?

string

Returns

BanBuilder


banIp()

banIp(target, reason?): BanIpBuilder

Defined in: core/commands/ban-ip.ts:24

ban-ip - ctx.banIp()...

Parameters

target

string

reason?

string

Returns

BanIpBuilder


banlist()

banlist(): BanlistBuilder

Defined in: core/commands/banlist.ts:31

banlist - ctx.banlist()...

Returns

BanlistBuilder


block()

block(pos): NbtHolder

Defined in: core/frontend/data.ts:101

A block's NBT as a holder: ctx.block(Pos.here()).remove("Items[0]").

Parameters

pos

PosValue

Returns

NbtHolder


bossbar()

bossbar(): BossbarBuilder

Defined in: core/commands/bossbar.ts:144

bossbar - ctx.bossbar()...

Returns

BossbarBuilder


call()

call(node): void

Defined in: core/frontend/context/base.ts:31

Parameters

node

FunctionRef

Returns

void

Inherited from

ContextBase.call


clear()

clear(targets?, item?, maxCount?): ClearBuilder

Defined in: core/commands/clear.ts:25

clear - ctx.clear()...

Parameters

targets?

Selector

item?

ItemValue

maxCount?

number

Returns

ClearBuilder


clone()

clone(begin?, end?, destination?): CloneBuilder

Defined in: core/commands/clone.ts:537

clone - ctx.clone()...

Parameters

begin?

PosValue

end?

PosValue

destination?

PosValue

Returns

CloneBuilder


createChildFunction()

createChildFunction(suffix): FunctionNode

Defined in: core/frontend/context/base.ts:45

A uniquely-named nested function for control-flow bodies (if/elif/else, at). Public so the if augmentation in commands/if.ts can build child bodies.

Generated helpers live under the shared PRIVATE_ROOT folder so they sort away from authored functions (a leading-underscore name sorted them to the top of the list, in the way). The name nests by parent path - tickzzz/tick/if_0zzz/tick/if_0/at_0 - stripping the root from the parent so the prefix doesn't compound into noise on each nesting level.

Parameters

suffix

string

Returns

FunctionNode

Inherited from

ContextBase.createChildFunction


damage()

damage(target?, amount?, damageType?): DamageBuilder

Defined in: core/commands/damage.ts:38

damage - ctx.damage()...

Parameters

target?

Selector

amount?

number

damageType?

DamageType

Returns

DamageBuilder


data()

data(): DataBuilder

Defined in: core/commands/data.ts:168

data - pick a sub-command: .get(), .merge(), .modify(), .remove().

Returns

DataBuilder


datapack()

datapack(): DatapackBuilder

Defined in: core/commands/datapack.ts:72

datapack - ctx.datapack()...

Returns

DatapackBuilder


debug()

debug(): DebugBuilder

Defined in: core/commands/debug.ts:37

debug - ctx.debug()...

Returns

DebugBuilder


defaultgamemode()

defaultgamemode(gamemode): DefaultgamemodeBuilder

Defined in: core/commands/defaultgamemode.ts:24

defaultgamemode - ctx.defaultgamemode()...

Parameters

gamemode

Gamemode

Returns

DefaultgamemodeBuilder


deop()

deop(targets): DeopBuilder

Defined in: core/commands/deop.ts:24

deop - ctx.deop()...

Parameters

targets

Selector

Returns

DeopBuilder


dialog()

dialog(): DialogBuilder

Defined in: core/commands/dialog.ts:33

dialog - ctx.dialog()...

Returns

DialogBuilder


difficulty()

difficulty(): DifficultyBuilder

Defined in: core/commands/difficulty.ts:41

difficulty - ctx.difficulty()...

Returns

DifficultyBuilder


effect()

effect(): EffectBuilder

Defined in: core/commands/effect.ts:45

effect - ctx.effect()...

Returns

EffectBuilder


emit()

emit(node): void

Defined in: core/frontend/context/base.ts:27

Parameters

node

ASTNode

Returns

void

Inherited from

ContextBase.emit


enchant()

enchant(targets, enchantment, level?): EnchantBuilder

Defined in: core/commands/enchant.ts:25

enchant - ctx.enchant()...

Parameters

targets

Selector

enchantment

Enchantment

level?

number

Returns

EnchantBuilder


entity()

entity(target): NbtHolder

Defined in: core/frontend/data.ts:99

An entity's NBT as a holder: ctx.entity(Selector.self()).get("Health").

Parameters

target

Selector

Returns

NbtHolder


execute()

execute(): ExecuteBuilder

Defined in: core/commands/execute.ts:279

A general execute … run … chain. See ExecuteBuilder.

Returns

ExecuteBuilder


experience()

experience(): ExperienceBuilder

Defined in: core/commands/experience.ts:62

experience - ctx.experience()...

Returns

ExperienceBuilder


fetchprofile()

fetchprofile(): FetchprofileBuilder

Defined in: core/commands/fetchprofile.ts:38

fetchprofile - ctx.fetchprofile()...

Returns

FetchprofileBuilder


fill()

fill(from?, to?, block?): FillBuilder

Defined in: core/commands/fill.ts:73

fill - ctx.fill()...

Parameters

from?

PosValue

to?

PosValue

block?

BlockValue

Returns

FillBuilder


fillbiome()

fillbiome(from?, to?, biome?): FillbiomeBuilder

Defined in: core/commands/fillbiome.ts:27

fillbiome - ctx.fillbiome()...

Parameters

from?

PosValue

to?

PosValue

biome?

Biome

Returns

FillbiomeBuilder


forceload()

forceload(): ForceloadBuilder

Defined in: core/commands/forceload.ts:45

forceload - ctx.forceload()...

Returns

ForceloadBuilder


gamemode()

gamemode(gamemode, target?): GamemodeBuilder

Defined in: core/commands/gamemode.ts:25

gamemode - ctx.gamemode()...

Parameters

gamemode

Gamemode

target?

Selector

Returns

GamemodeBuilder


gamerule()

gamerule(): GameruleBuilder

Defined in: core/commands/gamerule.ts:729

gamerule - ctx.gamerule()...

Returns

GameruleBuilder


help()

help(command?): HelpBuilder

Defined in: core/commands/help.ts:23

help - ctx.help()...

Parameters

command?

string

Returns

HelpBuilder


if()

if(condition, thenFn): IfBuilder

Defined in: core/commands/if.ts:363

if/elif/else control flow; bodies compile to child functions.

Parameters

condition

ExpressionNode

thenFn

(ctx) => void

Returns

IfBuilder


item()

item(): ItemBuilder

Defined in: core/commands/item.ts:69

item - ctx.item()...

Returns

ItemBuilder


jfr()

jfr(): JfrBuilder

Defined in: core/commands/jfr.ts:31

jfr - ctx.jfr()...

Returns

JfrBuilder


kick()

kick(targets, reason?): KickBuilder

Defined in: core/commands/kick.ts:25

kick - ctx.kick()...

Parameters

targets

Selector

reason?

string

Returns

KickBuilder


kill()

kill(targets?): KillBuilder

Defined in: core/commands/kill.ts:24

kill - ctx.kill()...

Parameters

targets?

Selector

Returns

KillBuilder


list()

list(): ListBuilder

Defined in: core/commands/list.ts:26

list - ctx.list()...

Returns

ListBuilder


locate()

locate(): LocateBuilder

Defined in: core/commands/locate.ts:37

locate - ctx.locate()...

Returns

LocateBuilder


loot()

loot(): LootBuilder

Defined in: core/commands/loot.ts:249

loot - ctx.loot()...

Returns

LootBuilder


me()

me(action): MeBuilder

Defined in: core/commands/me.ts:24

me - ctx.me()...

Parameters

action

string

Returns

MeBuilder


msg()

msg(targets, message): MsgBuilder

Defined in: core/commands/msg.ts:25

msg - ctx.msg()...

Parameters

targets

Selector

message

string

Returns

MsgBuilder


native()

native(name, ...args): NativeCall

Defined in: core/commands/native.ts:69

Call a native server-plugin command (a Paper Brigadier command) instead of expanding to vanilla commands. Only emitted on a "paper" build; on a "vanilla" build it runs the .fallback(...) body, or errors if none was given. name is the command id (Id("paper:pathfind") or a bare string); args are typed values (Selector, Pos, …) rendered version-aware.

Parameters

name

string | IdValue

args

...ArgInput[]

Returns

NativeCall


op()

op(targets): OpBuilder

Defined in: core/commands/op.ts:24

op - ctx.op()...

Parameters

targets

Selector

Returns

OpBuilder


pardon()

pardon(targets): PardonBuilder

Defined in: core/commands/pardon.ts:24

pardon - ctx.pardon()...

Parameters

targets

Selector

Returns

PardonBuilder


pardonIp()

pardonIp(target): PardonIpBuilder

Defined in: core/commands/pardon-ip.ts:23

pardon-ip - ctx.pardonIp()...

Parameters

target

string

Returns

PardonIpBuilder


particle()

particle(name?, pos?, delta?, speed?, count?): ParticleBuilder

Defined in: core/commands/particle.ts:35

particle - ctx.particle()...

Parameters

name?

Particle

pos?

PosValue

delta?

PosValue

speed?

number

count?

number

Returns

ParticleBuilder


perf()

perf(): PerfBuilder

Defined in: core/commands/perf.ts:31

perf - ctx.perf()...

Returns

PerfBuilder


place()

place(): PlaceBuilder

Defined in: core/commands/place.ts:55

place - ctx.place()...

Returns

PlaceBuilder


player()

player(name): Player

Defined in: core/commands/give.ts:78

A named player as a selector helper: ctx.player("Steve").giveItem(...).

Parameters

name

string

Returns

Player


playerGive()

playerGive(selector, item, count?): void

Defined in: core/commands/give.ts:76

give <target> <item> [count] - accepts a rich Item, a bare id string, or a legacy ItemSpec.

Parameters

selector

Selector

item

string | ItemValue | ItemSpec

count?

number

Returns

void


playsound()

playsound(sound?): PlaysoundBuilder

Defined in: core/commands/playsound.ts:133

playsound - ctx.playsound()...

Parameters

sound?

IdValue

Returns

PlaysoundBuilder


publish()

publish(allowCommands?, gamemode?, port?): PublishBuilder

Defined in: core/commands/publish.ts:24

publish - ctx.publish()...

Parameters

allowCommands?

boolean

gamemode?

Gamemode

port?

number

Returns

PublishBuilder


random()

random(min, max): RandomValueNode

Defined in: core/commands/random.ts:37

Roll a random value, gated on the target version: random was added in 1.20.3, so authoring against an older target throws HERE (at the call). Returns a version-neutral node other commands (e.g. score storeResult) consume - it is not emitted on its own.

Parameters

min

number

max

number

Returns

RandomValueNode


recipe()

recipe(): RecipeBuilder

Defined in: core/commands/recipe.ts:32

recipe - ctx.recipe()...

Returns

RecipeBuilder


reload()

reload(): ReloadBuilder

Defined in: core/commands/reload.ts:23

reload - ctx.reload()...

Returns

ReloadBuilder


return_()

return_(value?): ReturnBuilder

Defined in: core/commands/return.ts:26

return - ctx.return_()...

Parameters

value?

number

Returns

ReturnBuilder


returnRun()

returnRun(build): void

Defined in: core/commands/execute.ts:281

return run <command> - return the result of running build's command.

Parameters

build

(ctx) => void

Returns

void


ride()

ride(): RideBuilder

Defined in: core/commands/ride.ts:32

ride - ctx.ride()...

Returns

RideBuilder


rotate()

rotate(target?, rotation?): RotateBuilder

Defined in: core/commands/rotate.ts:34

rotate - ctx.rotate()...

Parameters

target?

Selector

rotation?

PosValue

Returns

RotateBuilder


saveAll()

saveAll(): SaveAllBuilder

Defined in: core/commands/save-all.ts:26

save-all - ctx.saveAll()...

Returns

SaveAllBuilder


saveOff()

saveOff(): SaveOffBuilder

Defined in: core/commands/save-off.ts:23

save-off - ctx.saveOff()...

Returns

SaveOffBuilder


saveOn()

saveOn(): SaveOnBuilder

Defined in: core/commands/save-on.ts:23

save-on - ctx.saveOn()...

Returns

SaveOnBuilder


say()

say(text): void

Defined in: core/commands/saycommand.ts:16

say <text> - broadcast a chat message.

Parameters

text

string

Returns

void


schedule()

schedule(): ScheduleBuilder

Defined in: core/commands/schedule.ts:42

schedule - ctx.schedule()...

Returns

ScheduleBuilder


scoreAdd()

scoreAdd(score): void

Defined in: core/commands/score_add.ts:37

scoreboard players add - add to a score.

Parameters

score

Score

Returns

void


scoreEnable()

scoreEnable(selector, objective): void

Defined in: core/commands/score_enable.ts:36

scoreboard players enable - enable a trigger objective for players.

Parameters

selector

Selector

objective

Objective

Returns

void


scoreGet()

scoreGet(score): void

Defined in: core/commands/score_get.ts:36

scoreboard players get <target> <objective> - read a score.

Parameters

score

Score

Returns

void


scoreInit()

scoreInit(objective): void

Defined in: core/commands/objective_init.ts:29

scoreboard objectives add - declare/init an objective.

Parameters

objective

Objective

Returns

void


scoreOp()

scoreOp(a, op, b): void

Defined in: core/commands/score_op.ts:44

scoreboard players operation <a> <op> <b> - score arithmetic.

Parameters

a

Score

op

ScoreOperator

b

Score

Returns

void


scoreRemove()

scoreRemove(score): void

Defined in: core/commands/score_remove.ts:37

scoreboard players remove - subtract from a score (value must be ≥ 0).

Parameters

score

Score

Returns

void


scoreSet()

scoreSet(score): void

Defined in: core/commands/score_set.ts:37

scoreboard players set - set a score to a literal.

Parameters

score

Score

Returns

void


scoreSetScore()

scoreSetScore(score, score2): void

Defined in: core/commands/score_set_score.ts:36

scoreboard players operation <a> = <b> - copy one score into another.

Parameters

score

Score

score2

Score

Returns

void


seed()

seed(): SeedBuilder

Defined in: core/commands/seed.ts:23

seed - ctx.seed()...

Returns

SeedBuilder


setblock()

setblock(pos, block): SetblockBuilder

Defined in: core/commands/setblock.ts:70

setblock <pos> <block> - chain .keep() etc. for the mode.

Parameters

pos

PosValue

block

BlockValue

Returns

SetblockBuilder


setidletimeout()

setidletimeout(minutes): SetidletimeoutBuilder

Defined in: core/commands/setidletimeout.ts:23

setidletimeout - ctx.setidletimeout()...

Parameters

minutes

number

Returns

SetidletimeoutBuilder


setworldspawn()

setworldspawn(pos?, rotation?): SetworldspawnBuilder

Defined in: core/commands/setworldspawn.ts:24

setworldspawn - ctx.setworldspawn()...

Parameters

pos?

PosValue

rotation?

PosValue

Returns

SetworldspawnBuilder


spawnpoint()

spawnpoint(targets?, pos?, rotation?): SpawnpointBuilder

Defined in: core/commands/spawnpoint.ts:25

spawnpoint - ctx.spawnpoint()...

Parameters

targets?

Selector

pos?

PosValue

rotation?

PosValue

Returns

SpawnpointBuilder


spectate()

spectate(target?, player?): SpectateBuilder

Defined in: core/commands/spectate.ts:24

spectate - ctx.spectate()...

Parameters

target?

Selector

player?

Selector

Returns

SpectateBuilder


spreadplayers()

spreadplayers(center?, spreadDistance?, maxRange?, respectTeams?, targets?): SpreadplayersBuilder

Defined in: core/commands/spreadplayers.ts:28

spreadplayers - ctx.spreadplayers()...

Parameters

center?

PosValue

spreadDistance?

number

maxRange?

number

respectTeams?

boolean

targets?

Selector

Returns

SpreadplayersBuilder


stop()

stop(): StopBuilder

Defined in: core/commands/stop.ts:23

stop - ctx.stop()...

Returns

StopBuilder


stopsound()

stopsound(targets?): StopsoundBuilder

Defined in: core/commands/stopsound.ts:89

stopsound - ctx.stopsound()...

Parameters

targets?

Selector

Returns

StopsoundBuilder


stopwatch()

stopwatch(): StopwatchBuilder

Defined in: core/commands/stopwatch.ts:43

stopwatch - ctx.stopwatch()...

Returns

StopwatchBuilder


storage()

storage(id): NbtHolder

Defined in: core/frontend/data.ts:97

Command storage as an NBT holder: ctx.storage(Id("ns:id")).set(...).

Parameters

id

IdValue

Returns

NbtHolder


summon()

summon(entity, pos?, nbt?): SummonBuilder

Defined in: core/commands/summon.ts:24

summon - ctx.summon()...

Parameters

entity

EntityType

pos?

PosValue

nbt?

NbtValue

Returns

SummonBuilder


summonIf()

summonIf(cond, display): void

Defined in: core/commands/entity_guard.ts:60

Summon display only when cond holds - e.g. an idempotent spawn: ctx.summonIf(cog.notExist, cog). Emits one guarded line (execute unless entity <sel> run summon ...), no helper function.

Parameters

cond

EntityCondition

display

DisplayValue

Returns

void


swing()

swing(targets?): SwingBuilder

Defined in: core/commands/swing.ts:32

swing - ctx.swing()...

Parameters

targets?

Selector

Returns

SwingBuilder


tag()

tag(): TagBuilder

Defined in: core/commands/tag.ts:37

tag - ctx.tag()...

Returns

TagBuilder


team()

team(): TeamBuilder

Defined in: core/commands/team.ts:151

team - ctx.team()...

Returns

TeamBuilder


teammsg()

teammsg(message): TeammsgBuilder

Defined in: core/commands/teammsg.ts:24

teammsg - ctx.teammsg()...

Parameters

message

string

Returns

TeammsgBuilder


teleport()

teleport(targets?, location?, rotation?): TeleportBuilder

Defined in: core/commands/teleport.ts:34

teleport - ctx.teleport()...

Parameters

targets?

Selector

location?

PosValue

rotation?

PosValue

Returns

TeleportBuilder


tellraw()

tellraw(target, message): void

Defined in: core/commands/tellraw.ts:50

tellraw <target> <message> - rich text (strings, parts, or a list).

Parameters

target

Selector

message

TellrawContent

Returns

void


test()

test(): TestBuilder

Defined in: core/commands/test.ts:128

test - ctx.test()...

Returns

TestBuilder


tick()

tick(): TickBuilder

Defined in: core/commands/tick.ts:63

tick - ctx.tick()...

Returns

TickBuilder


time()

time(): TimeBuilder

Defined in: core/commands/time.ts:107

time - ctx.time()...

Returns

TimeBuilder


title()

title(): TitleBuilder

Defined in: core/commands/title.ts:53

title - ctx.title()...

Returns

TitleBuilder


transfer()

transfer(hostname, port?, players?): TransferBuilder

Defined in: core/commands/transfer.ts:24

transfer - ctx.transfer()...

Parameters

hostname

string

port?

number

players?

Selector

Returns

TransferBuilder


trigger()

trigger(objective, value?): void

Defined in: core/commands/trigger.ts:40

trigger <objective> [set <value>] - fire a trigger objective.

Parameters

objective

Objective

value?

number

Returns

void


unpublish()

unpublish(): UnpublishBuilder

Defined in: core/commands/unpublish.ts:23

unpublish - ctx.unpublish()...

Returns

UnpublishBuilder


waypoint()

waypoint(): WaypointBuilder

Defined in: core/commands/waypoint.ts:53

waypoint - ctx.waypoint()...

Returns

WaypointBuilder


weather()

weather(): WeatherBuilder

Defined in: core/commands/weather.ts:40

weather - ctx.weather()...

Returns

WeatherBuilder


whenEntity()

whenEntity(selector, build, mode?): void

Defined in: core/commands/entity_guard.ts:70

Run each command emitted in build only when an entity matches selector

  • one execute (if|unless) entity <selector> run <command> line per emitted command (mode defaults to "if"). The body runs against a child context, so this is the API-level way to wrap a block of commands in an entity guard without touching the IR. Pair with Selector.volume(...) for "every player inside a box" triggers.

Parameters

selector

Selector

build

(ctx) => void

mode?

"if" | "unless"

Returns

void


whenItems()

whenItems(target, slot, item, build, mode?): void

Defined in: core/commands/items_guard.ts:67

Run each command emitted in build only when target's slot holds an item matching item - one execute (if|unless) items entity <target> <slot> <item_predicate> run <command> line per emitted command (mode defaults to "if"). item is matched as an item predicate built from the same ItemValue you'd give, so the check sees the exact components (name/lore/model) the item was granted with. Use this to act on a precise slot when an equipment/holding predicate (worn slots only) can't reach it.

Parameters

target

Selector

slot

string

item

ItemValue

build

(ctx) => void

mode?

"if" | "unless"

Returns

void


whenPlayerNear()

whenPlayerNear(pos, radius, build, unlessSelector?): void

Defined in: core/commands/near_guard.ts:92

Run each command emitted in build only when a player is within radius blocks of pos. Pass unlessSelector to additionally gate on that entity being absent (a re-arm guard, so a held-down trigger doesn't refire).

By default this is a single presence check - execute positioned <pos> if entity @a[distance=..radius] … run <command> - so the body runs once no matter how many players are in range.

Opt into a per-player handle by declaring a second build parameter: the body then runs as @a[distance=..radius], once per nearby player, with the passed Selector (@s) bound to that player. Use this only when the body needs the player (e.g. ctx.tellraw(player, …)); the extra as-fan-out is why it isn't the default.

Parameters

pos

PosValue

radius

number

build

(ctx, player) => void

unlessSelector?

Selector

Returns

void


whitelist()

whitelist(): WhitelistBuilder

Defined in: core/commands/whitelist.ts:52

whitelist - ctx.whitelist()...

Returns

WhitelistBuilder


worldborder()

worldborder(): WorldborderBuilder

Defined in: core/commands/worldborder.ts:64

worldborder - ctx.worldborder()...

Returns

WorldborderBuilder

Released under the MIT License · Credits