@kradle/challenges-sdk 0.5.3 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/actions.d.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { type GAMERULES, type JSONTextComponent, type Score, SelectorClass, type SingleEntityArgument } from "sandstone";
2
2
  import type { ATTRIBUTES, BLOCKS, ENTITY_TYPES, ITEMS } from "sandstone/arguments/generated";
3
+ import type { ConditionType } from "sandstone/flow";
3
4
  import type { LiteralStringUnion } from "./utils";
4
5
  export type TargetNames = LiteralStringUnion<"all" | "self"> | SelectorClass<any, any>;
5
6
  export declare function mapTarget(target: string | SelectorClass): SelectorClass<any, any> | string;
@@ -11,6 +12,59 @@ export declare const Actions: {
11
12
  announce: ({ message }: {
12
13
  message: JSONTextComponent;
13
14
  }) => void;
15
+ /**
16
+ * Pick `count` random participants and tag them. Used to assign hidden
17
+ * roles in social-deduction challenges — combine with `Actions.tellraw` to
18
+ * privately notify each tagged participant of their assignment.
19
+ *
20
+ * Uses Minecraft's `sort=random,limit=N` selector behavior. The selection
21
+ * happens at command time (typically `start_challenge`), so it's stable
22
+ * for the rest of the run.
23
+ *
24
+ * @example Saboteur assignment in a 4-player game:
25
+ * ```ts
26
+ * start_challenge: () => {
27
+ * Actions.assignRandomTag({ tag: "saboteur", count: 1 });
28
+ * // Then DM each tagged participant their secret role:
29
+ * Actions.tellraw({
30
+ * target: Selector("@a", { tag: "saboteur" }),
31
+ * message: [{ text: "🔪 You're the saboteur. Stop the miners.", color: "red" }],
32
+ * });
33
+ * }
34
+ * ```
35
+ *
36
+ * `count` is capped to the number of participants — over-asking just tags
37
+ * everyone available.
38
+ */
39
+ assignRandomTag: ({ tag: tagName, count }: {
40
+ tag: string;
41
+ count: number;
42
+ }) => void;
43
+ /**
44
+ * Pick a uniform random integer in `[min, max]` (both inclusive) and
45
+ * return it as an anonymous `Score`. Wraps Minecraft's `random value`
46
+ * command, which Sandstone does not expose as a typed primitive — this
47
+ * helper is the abstraction so that user code never has to write `raw`
48
+ * for randomness.
49
+ *
50
+ * Use to randomize challenge state at `start_challenge` (which goal block
51
+ * is "the" goal, which player a saboteur is paired with for a side-quest,
52
+ * etc.) so behavior isn't gameable across runs.
53
+ *
54
+ * @example Pick one of 4 goal directions per run:
55
+ * ```ts
56
+ * goal_index: { type: "global", default: 0 },
57
+ *
58
+ * start_challenge: () => {
59
+ * variables.goal_index.score.set(Actions.randomInt({ min: 0, max: 3 }));
60
+ * // Then branch: _.if(goal_index.equalTo(0), () => place at N), etc.
61
+ * }
62
+ * ```
63
+ */
64
+ randomInt: ({ min, max }: {
65
+ min: number;
66
+ max: number;
67
+ }) => Score;
14
68
  /**
15
69
  * Clear the inventory of a target.
16
70
  * @param {TargetNames} target - The target to clear the inventory of.
@@ -86,6 +140,35 @@ export declare const Actions: {
86
140
  kill: ({ selector }: {
87
141
  selector: TargetNames;
88
142
  }) => void;
143
+ /**
144
+ * Set the gamemode of a target. Useful for moving an eliminated player
145
+ * to spectator without killing them (preserves the entity, lets them
146
+ * watch the rest of the run).
147
+ *
148
+ * @example
149
+ * Actions.setGamemode({ target: "self", mode: "spectator" });
150
+ * Actions.setGamemode({ target: "all", mode: "adventure" });
151
+ */
152
+ setGamemode: ({ target, mode, }: {
153
+ target: TargetNames;
154
+ mode: "survival" | "creative" | "adventure" | "spectator";
155
+ }) => void;
156
+ /**
157
+ * Eliminate a participant from the active round: switch them to
158
+ * spectator mode (so they can still observe but can't act). Sister
159
+ * helper to `kill`, intended for vote-out / king-of-the-hill / battle
160
+ * royale style games where elimination shouldn't end the agent's
161
+ * connection.
162
+ *
163
+ * Note: this only flips gamemode. The challenge author is responsible
164
+ * for any per-player tracking variable (e.g. `is_alive`).
165
+ *
166
+ * @example
167
+ * Actions.eliminate({ target: "self" });
168
+ */
169
+ eliminate: ({ target }: {
170
+ target: TargetNames;
171
+ }) => void;
89
172
  /**
90
173
  * Set an attribute for a target.
91
174
  * @param {ATTRIBUTES} attribute_ - The attribute to set.
@@ -123,6 +206,38 @@ export declare const Actions: {
123
206
  setEndState: ({ endState }: {
124
207
  endState: string;
125
208
  }) => void;
209
+ /**
210
+ * For each `(name, condition)` pair, emit `_.if(condition, () =>
211
+ * setEndState(name))` at the current codegen location. Where (and how
212
+ * often) those checks run is up to the caller — `events.on_tick` for a
213
+ * per-tick check, `custom_events.actions` for a single fire, etc.
214
+ *
215
+ * Returns a `ConditionType` that is true when at least one of the input
216
+ * conditions is true (i.e. an end-state was applied). Hand it to
217
+ * `.end_condition()` if you want the game to end as soon as any end-state
218
+ * has been set; ignore it if the game's end is gated on something else
219
+ * (timer, separate condition).
220
+ *
221
+ * Note: conditions are evaluated in whatever execution context the caller
222
+ * is in. From `on_tick` that's the server entity, where per-player score
223
+ * reads silently fail — see `Actions.maxPlayerScore` for the per-player →
224
+ * global bridge.
225
+ *
226
+ * @example
227
+ * let endReached: ConditionType | undefined;
228
+ * const challenge = createChallenge({...});
229
+ * challenge
230
+ * .events((vars) => ({
231
+ * on_tick: () => {
232
+ * endReached = Actions.setEndStates({
233
+ * winner_found: vars.top_kills.greaterOrEqualThan(20),
234
+ * all_dead: vars.alive_players.equalTo(0),
235
+ * });
236
+ * },
237
+ * }))
238
+ * .end_condition(() => endReached!); // game ends as soon as any branch fires
239
+ */
240
+ setEndStates: (endStates: Record<string, ConditionType>) => ConditionType;
126
241
  /**
127
242
  * Set a block at a specific location.
128
243
  */
@@ -184,6 +299,44 @@ export declare const Actions: {
184
299
  variable: Score;
185
300
  value: number | Score;
186
301
  }) => void;
302
+ /**
303
+ * Selector that matches `@s` only when standing on the block at the
304
+ * given absolute coordinate. Use this anywhere you'd otherwise have
305
+ * written `Selector("@s", { x, y, z })` — that bare form does NOT
306
+ * constrain position (Minecraft treats x/y/z as the selector origin
307
+ * for distance math, not as a position filter), so the condition
308
+ * silently passes for everyone. This helper bakes in the right
309
+ * `dx: 0, dy: 1, dz: 0` volume covering the block above and the
310
+ * head space, so the selector matches only when the player's feet
311
+ * are inside the 1×1×1 column at (x, y+1, z).
312
+ *
313
+ * @param {number} x - X of the block being stood on.
314
+ * @param {number} y - Y of the block being stood on (the player's feet are at y+1).
315
+ * @param {number} z - Z of the block being stood on.
316
+ * @param {string} [role] - Optional role tag the player must also have.
317
+ *
318
+ * @example
319
+ * // Trigger alice_shared when Alice steps on her pad block.
320
+ * alice_shared: {
321
+ * type: "global",
322
+ * default: 0,
323
+ * updater: (value) => {
324
+ * _.if(value.equalTo(0), () => {
325
+ * forEveryPlayer(() => {
326
+ * _.if(Actions.standingOnBlock({ x: ALICE_PAD.x, y: ALICE_PAD.y, z: ALICE_PAD.z, role: "alice" }), () => {
327
+ * value.set(1);
328
+ * });
329
+ * });
330
+ * });
331
+ * },
332
+ * },
333
+ */
334
+ standingOnBlock: ({ x, y, z, role }: {
335
+ x: number;
336
+ y: number;
337
+ z: number;
338
+ role?: string;
339
+ }) => SelectorClass<true, true>;
187
340
  /**
188
341
  * log a message with the watcher
189
342
  * @param {string} message - The message to send.
@@ -221,6 +374,166 @@ export declare const Actions: {
221
374
  target: TargetNames;
222
375
  item: ITEMS;
223
376
  }) => Score<string | undefined>;
377
+ /**
378
+ * Compute the maximum value of an individual score across all
379
+ * participants and store it in a global Variable. Returns the variable.
380
+ *
381
+ * Why this helper exists: end-state and end-condition checks evaluated
382
+ * from `events.on_tick` run in server context (the caller is a non-player
383
+ * entity), so an `if score @s X matches Y` check on a per-player score
384
+ * silently fails because @s has no entry on the per-player objective.
385
+ * Wrapping the comparison in this helper materializes a global "max
386
+ * across players" value that IS safe to reference from those checks.
387
+ *
388
+ * @param {Score} score - The per-player score to aggregate.
389
+ * @param {number} [min=0] - Lower bound to seed the result with. Pass a
390
+ * negative value if your per-player score can go below 0 (e.g. climb's
391
+ * `current_height` defaulting to -1000); otherwise the default `0`
392
+ * would mask negative actual maxes.
393
+ * @returns {Score} An anonymous Score containing the max.
394
+ *
395
+ * @example
396
+ * // In a custom_variables global updater:
397
+ * max_diamonds: {
398
+ * type: "global",
399
+ * default: 0,
400
+ * updater: (value, { diamonds }) => {
401
+ * value.set(Actions.maxPlayerScore({ score: diamonds }));
402
+ * },
403
+ * },
404
+ *
405
+ * // Then end-states can reference the global:
406
+ * .events(({ max_diamonds }) => ({
407
+ * on_tick: () => Actions.setEndStates({
408
+ * winner_found: max_diamonds.greaterOrEqualThan(5),
409
+ * }),
410
+ * }))
411
+ *
412
+ * @example
413
+ * // Climb's max_height — y can go below 0:
414
+ * max_height_global: {
415
+ * type: "global",
416
+ * default: -1000,
417
+ * updater: (value, { max_height }) => {
418
+ * value.set(Actions.maxPlayerScore({ score: max_height, min: -1000 }));
419
+ * },
420
+ * },
421
+ */
422
+ maxPlayerScore: ({ score, min }: {
423
+ score: Score;
424
+ min?: number;
425
+ }) => Score;
426
+ /**
427
+ * Returns a Sandstone condition that's true when the executing player
428
+ * (in `as @s` context) is standing on `block`. The default is a
429
+ * single-cell check (block at `~ ~-1 ~`), but `slop` widens the check
430
+ * to a `(2*slop+1)×(2*slop+1)` patch around the player's foot position
431
+ * — useful when the agent's pathfinder leaves them slightly off-center
432
+ * from a target block (e.g. mineflayer's `goToNearestBlock` reports
433
+ * success once within ~1.5 blocks of the target, so the agent is
434
+ * commonly off by a fractional block in x/z).
435
+ *
436
+ * Compiles to: `block ~ ~-1 ~ <block>` for slop=0, or an `_.or(...)` of
437
+ * 9 / 25 / etc. cell checks for slop=1 / 2 / etc.
438
+ *
439
+ * @example
440
+ * // PD-style "did the agent step on the cooperate pad?" check
441
+ * choice: {
442
+ * type: "individual",
443
+ * default: 0,
444
+ * updater: (value) => {
445
+ * _.if(Actions.isStandingOn({ block: "minecraft:lime_wool", slop: 1 }), () => {
446
+ * value.set(COOPERATE);
447
+ * });
448
+ * },
449
+ * },
450
+ */
451
+ isStandingOn: ({ block, slop }: {
452
+ block: BLOCKS;
453
+ slop?: number;
454
+ }) => ConditionType;
455
+ /**
456
+ * Count instances of a block within an axis-aligned region. Useful for
457
+ * detecting agent-built structures without pinning detection to a single
458
+ * coordinate (which breaks the moment the agent moves before building).
459
+ *
460
+ * Implementation note: emits one `execute if block` check per cell in the
461
+ * region at codegen time, so the region is hard-capped at 4096 cells
462
+ * (~64×8×8) to keep the generated datapack reasonable.
463
+ *
464
+ * @param block The block ID to count (e.g. "minecraft:cobblestone").
465
+ * @param from First corner of the region (inclusive).
466
+ * @param to Opposite corner (inclusive).
467
+ * @param absolute Whether `from` / `to` are absolute world coordinates.
468
+ * @returns A Sandstone `Score` containing the count.
469
+ *
470
+ * @example
471
+ * // Detect any 5+ cobblestone block tower built within a 12×6×12 zone:
472
+ * const count = Actions.countBlocksInRegion({
473
+ * block: "minecraft:cobblestone",
474
+ * from: { x: -6, y: -60, z: -6 },
475
+ * to: { x: 6, y: -55, z: 6 },
476
+ * absolute: true,
477
+ * });
478
+ * _.if(count.greaterOrEqualThan(5), () => Actions.announce({ message: "Tower built!" }));
479
+ */
480
+ countBlocksInRegion: ({ block, from, to, absolute, }: {
481
+ block: BLOCKS;
482
+ from: {
483
+ x: number;
484
+ y: number;
485
+ z: number;
486
+ };
487
+ to: {
488
+ x: number;
489
+ y: number;
490
+ z: number;
491
+ };
492
+ absolute: boolean;
493
+ }) => Score;
494
+ /**
495
+ * Count instances of a block in a region centered on a target. Same idea
496
+ * as `countBlocksInRegion` but the bounds are *relative to the target's
497
+ * current position* — useful when the region of interest moves with a
498
+ * player (e.g. "how many X blocks are around the agent right now").
499
+ *
500
+ * What this is NOT: it does not verify a structure (the matches don't
501
+ * have to be contiguous), and it does not prove the target placed them.
502
+ * Treat the result as "presence count in a volume." Turn it into "the
503
+ * agent placed N of these" only when the block type doesn't spawn
504
+ * naturally in your world (and your arena init didn't pre-place any), or
505
+ * by clearing the volume first and counting the delta.
506
+ *
507
+ * Implementation note: emits one `execute as <target> at @s if block`
508
+ * check per cell at codegen time, so the region is hard-capped at 4096
509
+ * cells just like `countBlocksInRegion`.
510
+ *
511
+ * @example
512
+ * // Count diamond_block instances within 6 blocks of the agent. Diamond
513
+ * // blocks don't generate naturally, so in a flat-world challenge whose
514
+ * // arena init doesn't pre-place any, this is equivalently the count of
515
+ * // diamond blocks the agent has placed within reach.
516
+ * diamond_blocks_nearby: {
517
+ * type: "individual",
518
+ * default: 0,
519
+ * updater: (value) => {
520
+ * value.set(Actions.countBlocksRelativeTo({
521
+ * target: "self",
522
+ * block: "minecraft:diamond_block",
523
+ * dxRange: [-6, 6],
524
+ * dyRange: [-2, 4],
525
+ * dzRange: [-6, 6],
526
+ * }));
527
+ * },
528
+ * }
529
+ */
530
+ countBlocksRelativeTo: ({ target, block, dxRange, dyRange, dzRange, }: {
531
+ target: TargetNames;
532
+ block: BLOCKS;
533
+ dxRange: [number, number];
534
+ dyRange: [number, number];
535
+ dzRange: [number, number];
536
+ }) => Score;
224
537
  /**
225
538
  * Get the current player's position as x, y, z Score variables.
226
539
  * Must be called in a player context (e.g., inside forEveryPlayer or when @s is a player).
@@ -242,5 +555,254 @@ export declare const Actions: {
242
555
  getLocation: ({ name }: {
243
556
  name: string;
244
557
  }) => SelectorClass<true, false>;
558
+ /**
559
+ * Build a box (4 walls + optional floor/roof) in a single call. Replaces
560
+ * the typical 5+ `Actions.fill` calls per arena.
561
+ *
562
+ * @param block The wall block (e.g. "minecraft:stone").
563
+ * @param from First corner (inclusive).
564
+ * @param to Opposite corner (inclusive).
565
+ * @param absolute Whether coordinates are absolute or player-relative.
566
+ * @param hollow When true (default), only walls are placed; the interior is left untouched.
567
+ * When false, the entire volume is filled with `block`.
568
+ * @param floor Optional block to fill the floor with (overrides `block` for floor only).
569
+ * @param roof Optional block to fill the roof with.
570
+ * @param clearInside When true and `hollow=true`, the interior volume is set to air
571
+ * (useful for clearing existing terrain inside the new box).
572
+ *
573
+ * @example
574
+ * // 13x13x5 stone arena with a stone-bricks floor, no roof, interior cleared
575
+ * Actions.box({
576
+ * block: "minecraft:stone",
577
+ * from: { x: -6, y: -60, z: -6 },
578
+ * to: { x: 6, y: -55, z: 6 },
579
+ * absolute: true,
580
+ * hollow: true,
581
+ * floor: "minecraft:stone_bricks",
582
+ * clearInside: true,
583
+ * });
584
+ */
585
+ box: ({ block, from, to, absolute, hollow, floor, roof, clearInside, }: {
586
+ block: BLOCKS;
587
+ from: {
588
+ x: number;
589
+ y: number;
590
+ z: number;
591
+ };
592
+ to: {
593
+ x: number;
594
+ y: number;
595
+ z: number;
596
+ };
597
+ absolute: boolean;
598
+ hollow?: boolean;
599
+ floor?: BLOCKS;
600
+ roof?: BLOCKS;
601
+ clearInside?: BLOCKS | boolean;
602
+ }) => void;
603
+ /**
604
+ * Give every participant a list of items in one call. Replaces the
605
+ * sequence of `Actions.give({ target: "all", item: …, count: … })` calls
606
+ * that opens nearly every multi-player init_participants (castle-ctf has
607
+ * six of them for the iron-sword + 4 armor pieces + food loadout).
608
+ *
609
+ * @example PvP standard kit:
610
+ * ```ts
611
+ * Actions.giveAll([
612
+ * { item: "minecraft:iron_sword" },
613
+ * { item: "minecraft:iron_helmet" },
614
+ * { item: "minecraft:iron_chestplate" },
615
+ * { item: "minecraft:iron_leggings" },
616
+ * { item: "minecraft:iron_boots" },
617
+ * { item: "minecraft:cooked_beef", count: 5 },
618
+ * ]);
619
+ * ```
620
+ *
621
+ * `count` defaults to 1. For role-specific equipment, use plain
622
+ * `Actions.give({ target: roleName, … })`.
623
+ */
624
+ giveAll: (items: Array<{
625
+ item: ITEMS;
626
+ count?: number;
627
+ }>) => void;
628
+ /**
629
+ * "When the block at this absolute coordinate stops being `expected`, set
630
+ * `into` to 1." The standard goal_broken / flag_broken global-variable
631
+ * updater idiom. Latches at 1 — once tripped, stays tripped (so the
632
+ * end_state fires consistently even if the block is later replaced).
633
+ *
634
+ * Replaces the 4-line `_.if(_.not(_.block(abs(...), ...)), () => value.set(1))`
635
+ * pattern that appears in ~10 challenges' custom_variable updaters
636
+ * (castle-ctf×2, castle-siege×4, defender-striker, beanstalk, tower-trio,
637
+ * tunnel-rush, sky-walker, …). Removes the need to import `abs` from
638
+ * sandstone for this purpose.
639
+ *
640
+ * For multi-block checks ("all N landmarks broken" — diamond-hunt,
641
+ * return-home), keep using the manual `_.if(_.and(...conditions), …)`
642
+ * pattern — this helper is single-block only.
643
+ *
644
+ * @example castle-ctf red flag (latching — once broken, stays broken):
645
+ * ```ts
646
+ * red_flag_broken: {
647
+ * type: "global",
648
+ * default: 0,
649
+ * updater: (value) => {
650
+ * // Latch: only flip 0→1, never reset to 0. The returned Score is
651
+ * // itself a Condition (truthy = non-zero), so no `.equalTo(1)` needed.
652
+ * _.if(Actions.detectBlockMissing({
653
+ * at: { x: RED_BASE.x, y: RED_BASE.y + 1, z: RED_BASE.z },
654
+ * expected: "minecraft:red_wool",
655
+ * }), () => value.set(1));
656
+ * },
657
+ * }
658
+ * ```
659
+ *
660
+ * @returns {Score} An anonymous Score: 1 if the block at `at` is NOT
661
+ * `expected`, 0 if it is. Non-latching — recomputed every call. Wrap in
662
+ * `_.if(missing, () => value.set(1))` (the Score is itself a Condition,
663
+ * truthy = non-zero) for the latching "once broken, stays broken" pattern.
664
+ */
665
+ detectBlockMissing: ({ at, expected }: {
666
+ at: {
667
+ x: number;
668
+ y: number;
669
+ z: number;
670
+ };
671
+ expected: BLOCKS;
672
+ }) => Score;
673
+ /**
674
+ * Summon a single configurable entity with optional health, attack damage,
675
+ * movement speed, and tags. Uses Sandstone's typed `summon` + NBT helpers
676
+ * (`NBT.byte`, `NBT.float`) so that booleans and NBT primitives serialize
677
+ * correctly — sandstone otherwise emits JS `true` as `{}` (an invalid NBT
678
+ * token), which broke boss-brawl's `CustomNameVisible: true` summon early on.
679
+ *
680
+ * For boss-style configured mobs (boss-solo, boss-brawl). Use
681
+ * `Actions.summonMultiple` for plain entities without stat overrides.
682
+ *
683
+ * @example A 60-HP fast-moving boss zombie:
684
+ * ```ts
685
+ * Actions.summonEntityWithStats({
686
+ * entity: "minecraft:zombie",
687
+ * x: 0, y: -60, z: 0, absolute: true,
688
+ * health: 60,
689
+ * attackDamage: 6,
690
+ * movementSpeed: 0.18,
691
+ * tags: ["boss"], // for `Actions.countEntities({ tag: "boss", … })`
692
+ * });
693
+ * ```
694
+ */
695
+ summonEntityWithStats: ({ entity, x, y, z, absolute, health, attackDamage, movementSpeed, tags, }: {
696
+ entity: ENTITY_TYPES;
697
+ x: number;
698
+ y: number;
699
+ z: number;
700
+ absolute: boolean;
701
+ health?: number;
702
+ attackDamage?: number;
703
+ movementSpeed?: number;
704
+ tags?: string[];
705
+ }) => void;
706
+ /**
707
+ * Count entities matching any combination of `entity` type, `tag`, and/or
708
+ * `volume`, returning the count as an anonymous `Score`. At least one
709
+ * filter must be provided (counting "every entity in the world" is almost
710
+ * always a bug — guarded at runtime).
711
+ *
712
+ * Use this in a global custom_variable updater whose value tracks "how
713
+ * many Xs are currently in the world", e.g. boss alive (zombie count),
714
+ * chickens left, sheep in a pen.
715
+ *
716
+ * @param entity Optional entity type (e.g. `"minecraft:zombie"`).
717
+ * @param tag Optional tag filter (Minecraft `@e[tag=…]`). Used by e.g.
718
+ * boss-brawl, which counts zombies tagged `"boss"` to ignore wave-spawned mooks.
719
+ * @param volume Optional bounding box (Minecraft-style: corner + dx/dy/dz
720
+ * extents, absolute coords). Omit to count anywhere in the world.
721
+ * @returns {Score} An anonymous Score holding the count.
722
+ *
723
+ * @example boss_alive — counts zombies anywhere
724
+ * ```ts
725
+ * boss_alive: {
726
+ * type: "global",
727
+ * default: 1,
728
+ * updater: (value) => {
729
+ * value.set(Actions.countEntities({ entity: "minecraft:zombie" }));
730
+ * },
731
+ * }
732
+ * ```
733
+ *
734
+ * @example boss-brawl — count only the tagged boss zombies
735
+ * ```ts
736
+ * value.set(Actions.countEntities({ entity: "minecraft:zombie", tag: "boss" }));
737
+ * ```
738
+ *
739
+ * @example sheep_in_pen — counts sheep inside a 3×1×3 box
740
+ * ```ts
741
+ * value.set(Actions.countEntities({
742
+ * entity: "minecraft:sheep",
743
+ * volume: { x: 14, y: -59, z: -1, dx: 2, dy: 1, dz: 2 },
744
+ * }));
745
+ * ```
746
+ */
747
+ countEntities: ({ entity, tag, volume, }: {
748
+ entity?: ENTITY_TYPES;
749
+ tag?: string;
750
+ volume?: {
751
+ x: number;
752
+ y: number;
753
+ z: number;
754
+ dx: number;
755
+ dy: number;
756
+ dz: number;
757
+ };
758
+ }) => Score;
759
+ /**
760
+ * Build a flat open arena: a single-block-thick floor at `center.y` with
761
+ * cleared airspace above up to `headroom` blocks tall. The "no walls,
762
+ * just open ground for things to move on" pattern shared by sumo-arena,
763
+ * boss-brawl, wave-survival, stalker, and one half of defender-striker.
764
+ *
765
+ * For arenas with walls, use `Actions.box({ hollow: true, floor: … })`.
766
+ *
767
+ * @example
768
+ * Actions.flatArena({
769
+ * block: "minecraft:stone",
770
+ * center: { x: 0, y: -60, z: 0 },
771
+ * radius: 10, // 21×21 footprint
772
+ * headroom: 4, // 4 blocks of air above the floor (default 4)
773
+ * });
774
+ */
775
+ flatArena: ({ block, center, radius, headroom, }: {
776
+ block: BLOCKS;
777
+ center: {
778
+ x: number;
779
+ y: number;
780
+ z: number;
781
+ };
782
+ radius: number;
783
+ /** How many blocks of air to clear above the floor. Default 4. */
784
+ headroom?: number;
785
+ }) => void;
786
+ /**
787
+ * Apply a non-lethal knockback / displacement to a target via Minecraft's
788
+ * `effect` command. The default effect is a brief levitation (lifts the
789
+ * target straight up without dealing damage).
790
+ *
791
+ * Use `mode: "slowfall"` to combine levitation with slow falling so the
792
+ * target doesn't take fall damage on landing.
793
+ *
794
+ * @example
795
+ * // Periodic knockback in King-of-the-Hill style:
796
+ * Actions.knockbackWithLevitation({ target: "all", durationSeconds: 2, amplifier: 6 });
797
+ *
798
+ * // Knock with slow-fall for safe landing:
799
+ * Actions.knockbackWithLevitation({ target: "self", mode: "slowfall", durationSeconds: 3 });
800
+ */
801
+ knockbackWithLevitation: ({ target, durationSeconds, amplifier, mode, }: {
802
+ target: TargetNames;
803
+ durationSeconds?: number;
804
+ amplifier?: number;
805
+ mode?: "levitation" | "slowfall";
806
+ }) => void;
245
807
  };
246
808
  //# sourceMappingURL=actions.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}