sandstone 1.1.2 → 1.1.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sandstone",
   "description": "Sandstone, a Typescript library for Minecraft datapacks & resource packs.",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "contributors": [
     {
       "name": "TheMrZZ - Florian ERNST",
@@ -71,7 +71,7 @@
     "publishToNpm": "bun dev:build && bun publish",
     "format": "bun oxlint src --fix",
     "lint": "bun oxlint src",
-    "update-from-mcdoc": "mcdoc-ts-generator --out-dir \"src/arguments/generated/\" --no-tsconfig"
+    "update-from-mcdoc": "MCDOC_TARGET_VERSION=26.2 mcdoc-ts-generator --out-dir \"src/arguments/generated/\" --no-tsconfig"
   },
   "type": "module",
   "main": "dist/exports/index.js",

package/src/arguments/coords.ts

@@ -1,4 +1,5 @@
 import type { Macroable } from 'sandstone/core'
+import type { AllowConst } from 'sandstone/utils'
 import type { VectorClass } from 'sandstone/variables'
 
 type AbsoluteFloat<MACRO extends boolean = false> = Macroable<`${number}` | number, MACRO>
@@ -19,31 +20,24 @@ type LocalVec2<MACRO extends boolean = false> = Macroable<`${LocalFloat} ${Local
 type VectorArrayComponent<MACRO extends boolean = false> = Macroable<AbsoluteOrRelativeFloat<MACRO> | LocalFloat<MACRO> | number, MACRO>
 
 export type AbsoluteCoordinates<MACRO extends boolean = false> =
-  | [x: AbsoluteFloat<MACRO>, y: AbsoluteFloat<MACRO>, z: AbsoluteFloat<MACRO>]
-  | readonly [x: AbsoluteFloat<MACRO>, y: AbsoluteFloat<MACRO>, z: AbsoluteFloat<MACRO>]
+  | AllowConst<[x: AbsoluteFloat<MACRO>, y: AbsoluteFloat<MACRO>, z: AbsoluteFloat<MACRO>]>
   | VectorClass<[string, string, string]>
   | AbsoluteVec3<MACRO>
 
 export type Coordinates<MACRO extends boolean = false> =
-  | [x: VectorArrayComponent<MACRO>, y: VectorArrayComponent<MACRO>, z: VectorArrayComponent<MACRO>]
-  | readonly [x: VectorArrayComponent<MACRO>, y: VectorArrayComponent<MACRO>, z: VectorArrayComponent<MACRO>]
+  | AllowConst<[x: VectorArrayComponent<MACRO>, y: VectorArrayComponent<MACRO>, z: VectorArrayComponent<MACRO>]>
   | VectorClass<[string, string, string]>
   | AbsoluteOrRelativeVec3<MACRO>
   | LocalVec3<MACRO>
 export type Rotation<MACRO extends boolean = false> =
-  | [
+  | AllowConst<[
       horizontal: Macroable<AbsoluteOrRelativeFloat<MACRO> | number, MACRO>,
       vertical: Macroable<AbsoluteOrRelativeFloat<MACRO> | number, MACRO>,
-    ]
-  | readonly [
-      horizontal: Macroable<AbsoluteOrRelativeFloat<MACRO> | number, MACRO>,
-      vertical: Macroable<AbsoluteOrRelativeFloat<MACRO> | number, MACRO>,
-    ]
+    ]>
   | VectorClass<[string, string]>
   | AbsoluteOrRelativeVec2<MACRO>
 export type ColumnCoordinates<MACRO extends boolean = false> =
-  | [x: VectorArrayComponent<MACRO>, z: VectorArrayComponent<MACRO>]
-  | readonly [x: VectorArrayComponent<MACRO>, z: VectorArrayComponent<MACRO>]
+  | AllowConst<[x: VectorArrayComponent<MACRO>, z: VectorArrayComponent<MACRO>]>
   | VectorClass<[string, string]>
   | AbsoluteOrRelativeVec2<MACRO>
   | LocalVec2<MACRO>

package/src/commands/implementations/block/fill.ts

@@ -1,10 +1,11 @@
-import type { Coordinates, NBTObject, SymbolBlock, SymbolMcdocBlockStates } from 'sandstone/arguments'
+import type { Coordinates, RootNBT, SymbolBlock, SymbolMcdocBlockStates } from 'sandstone/arguments'
 import type { Macroable, TagClass } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core/nodes'
 import { coordinatesParser, nbtResolver } from 'sandstone/variables'
 import { CommandArguments, type FinalCommandOutput } from '../../helpers'
 import type { Registry } from 'sandstone/arguments/generated/registry'
 import { blockStateStringifier, type BlockEntity, type BlockStatic, type ParseBlockState } from './setblock'
+import type { AllowConst } from 'sandstone/utils'
 
 export class FillCommandNode extends CommandNode {
   command = 'fill' as const
@@ -71,7 +72,10 @@ export class FillCommand<MACRO extends boolean> extends CommandArguments {
     to: Macroable<Coordinates<MACRO>, MACRO>,
     block: BLOCK,
     state?: Macroable<BLOCK extends keyof SymbolMcdocBlockStates ? ParseBlockState<NonNullable<SymbolMcdocBlockStates[BLOCK]>> : Record<string, string | boolean | number>, MACRO>,
-    nbt?: Macroable<BLOCK extends keyof SymbolBlock ? NonNullable<SymbolBlock[BLOCK]> : SymbolBlock<'%fallback'>, MACRO>,
+    nbt?: Macroable<BLOCK extends keyof SymbolBlock
+      ? NonNullable<AllowConst<SymbolBlock[Extract<BLOCK, keyof SymbolBlock>]>>
+      : AllowConst<RootNBT>,
+    MACRO>,
   ): FillArgumentsCommand<MACRO>
 
   fill(
@@ -79,7 +83,7 @@ export class FillCommand<MACRO extends boolean> extends CommandArguments {
     to: Macroable<Coordinates<MACRO>, MACRO>,
     block: Macroable<Registry['minecraft:block'], MACRO>,
     state?: Record<string, string | boolean | number>,
-    nbt?: NBTObject,
+    nbt?: AllowConst<RootNBT>,
   ): FillArgumentsCommand<MACRO> {
     const stateStr = state && Object.keys(state).length > 0 ? blockStateStringifier(state) : ''
     const nbtStr = nbt ? nbtResolver(nbt).toString() : ''

package/src/commands/implementations/block/setblock.ts

@@ -1,11 +1,11 @@
-import type { Coordinates, NBTObject, SymbolBlock, SymbolMcdocBlockStates } from 'sandstone/arguments'
+import type { Coordinates, RootNBT, SymbolBlock, SymbolMcdocBlockStates } from 'sandstone/arguments'
 import type { Macroable } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core/nodes'
 import { coordinatesParser, nbtResolver } from 'sandstone/variables'
 import type { FinalCommandOutput } from '../../helpers'
 import { CommandArguments } from '../../helpers'
 import type { Registry } from 'sandstone/arguments/generated/registry'
-import type { NamespacedLiteralUnion } from 'sandstone/utils'
+import type { AllowConst, NamespacedLiteralUnion } from 'sandstone/utils'
 
 /** Converts stringified boolean/numeric literals to actual booleans/numbers */
 export type ParseLiteral<T> = (
@@ -21,7 +21,7 @@ export type ParseBlockState<T> = {
 
 export type BlockEntity = NamespacedLiteralUnion<keyof SymbolBlock>
 
-export type BlockStatic = NamespacedLiteralUnion<Exclude<keyof SymbolMcdocBlockStates, keyof SymbolBlock>>
+export type BlockStatic = NamespacedLiteralUnion<Exclude<keyof SymbolMcdocBlockStates, keyof SymbolBlock>> | 'air' | 'minecraft:air'
 
 export class SetBlockCommandNode extends CommandNode {
   command = 'setblock' as const
@@ -37,24 +37,24 @@ export class SetBlockCommand<MACRO extends boolean> extends CommandArguments {
    * This is the basic form for simple block placement without NBT data.
    *
    * @param pos The coordinates where to place the block. Supports:
-   *           - Absolute: `abs(100, 64, 200)` - exact world coordinates
-   *           - Relative: `['~5', '~1', '~-3']` - relative to command position
-   *           - Local: `['^2', '^', '^-1']` - relative to facing direction
-   *           - Mixed: `[100, '~5', '^2']` - combination of systems
+   *             - Absolute: `abs(100, 64, 200)` - exact world coordinates
+   *             - Relative: `['~5', '~1', '~-3']` - relative to command position
+   *             - Local: `['^2', '^', '^-1']` - relative to facing direction
+   *             - Mixed: `[100, '~5', '^2']` - combination of systems
    *
    * @param block The block type to place (e.g., `'minecraft:stone'`, `'oak_log'`).
    *
    * @param state Optional block state properties as an object. The available
-   *             properties are type-checked based on the block type:
-   *             - Oak log: `{ axis: 'x' | 'y' | 'z' }`
-   *             - Redstone wire: `{ power: 0-15, north: 'none' | 'side' | 'up', ... }`
-   *             - Stairs: `{ facing: 'north' | 'south' | 'east' | 'west', half: 'top' | 'bottom', ... }`
+   *              properties are type-checked based on the block type:
+   *               - Oak log: `{ axis: 'x' | 'y' | 'z' }`
+   *               - Redstone wire: `{ power: 0-15, north: 'none' | 'side' | 'up', ... }`
+   *               - Stairs: `{ facing: 'north' | 'south' | 'east' | 'west', half: 'top' | 'bottom', ... }`
    *
-   * @param type How to handle the placement. Options:
-   *            - `'replace'` (default): Silently replace any existing block
-   *            - `'destroy'`: Break existing block, dropping items and playing sound
-   *            - `'keep'`: Only place if the target location is air
-   *            - `'strict'`: Replace without issuing block updates
+   * @param flag How to handle the placement. Options:
+   *              - `'replace'` (default): Silently replace any existing block
+   *              - `'destroy'`: Break existing block, dropping items and playing sound
+   *              - `'keep'`: Only place if the target location is air
+   *              - `'strict'`: Replace without issuing block updates
    *
    * @example
    * ```ts
@@ -82,7 +82,7 @@ export class SetBlockCommand<MACRO extends boolean> extends CommandArguments {
     pos: Macroable<Coordinates<MACRO>, MACRO>,
     block: BLOCK,
     state?: Macroable<BLOCK extends keyof SymbolMcdocBlockStates ? ParseBlockState<NonNullable<SymbolMcdocBlockStates[Extract<BLOCK, keyof SymbolMcdocBlockStates>]>> : Record<string, string | boolean | number>, MACRO>,
-    type?: 'destroy' | 'keep' | 'replace' | 'strict',
+    flag?: 'destroy' | 'keep' | 'replace' | 'strict',
   ): FinalCommandOutput
 
   /**
@@ -95,23 +95,27 @@ export class SetBlockCommand<MACRO extends boolean> extends CommandArguments {
    * @param pos The coordinates where to place the block. Same format as basic variant.
    *
    * @param block The block type to place. Must be a block that supports NBT data:
-   *             - `'minecraft:chest'` - for containers
-   *             - `'minecraft:command_block'` - for command storage
-   *             - `'minecraft:sign'` - for text display
-   *             - `'minecraft:spawner'` - for mob spawning
+   *               - `'minecraft:chest'` - for containers
+   *               - `'minecraft:command_block'` - for command storage
+   *               - `'minecraft:sign'` - for text display
+   *               - `'minecraft:spawner'` - for mob spawning
    *
    * @param state Optional block state properties as an object. Type-checked based on block:
-   *             - Chest: `{ facing: 'north' | 'south' | 'east' | 'west', type: 'single' | 'left' | 'right', ... }`
-   *             - Command block: `{ facing: 'north' | 'south' | 'east' | 'west' | 'up' | 'down', conditional: true | false }`
-   *             - Sign: `{ rotation: 0-15 }` or `{ facing: ... }` for wall signs
+   *               - Chest: `{ facing: 'north' | 'south' | 'east' | 'west', type: 'single' | 'left' | 'right', ... }`
+   *               - Command block: `{ facing: 'north' | 'south' | 'east' | 'west' | 'up' | 'down', conditional: true | false }`
+   *               - Sign: `{ rotation: 0-15 }` or `{ facing: ... }` for wall signs
    *
    * @param nbt The NBT data object defining the block's properties:
-   *           - For chests: `{ Items: [{ Slot: 0, id: 'diamond', Count: 1 }] }`
-   *           - For signs: `{ front_text: { messages: [...] } }`
-   *           - For command blocks: `{ Command: 'say Hello' }`
-   *           - For spawners: `{ SpawnData: { id: 'minecraft:zombie' } }`
+   *             - For chests: `{ Items: [{ Slot: 0, id: 'diamond', Count: 1 }] }`
+   *             - For signs: `{ front_text: { messages: [...] } }`
+   *             - For command blocks: `{ Command: 'say Hello' }`
+   *             - For spawners: `{ SpawnData: { id: 'minecraft:zombie' } }`
    *
-   * @param type Placement behavior, same as basic variant.
+   * @param flag How to handle the placement. Options:
+   *              - `'replace'` (default): Silently replace any existing block
+   *              - `'destroy'`: Break existing block, dropping items and playing sound
+   *              - `'keep'`: Only place if the target location is air
+   *              - `'strict'`: Replace without issuing block updates
    *
    * @example
    * ```ts
@@ -139,8 +143,11 @@ export class SetBlockCommand<MACRO extends boolean> extends CommandArguments {
     pos: Macroable<Coordinates<MACRO>, MACRO>,
     block: BLOCK,
     state?: Macroable<BLOCK extends keyof SymbolMcdocBlockStates ? ParseBlockState<NonNullable<SymbolMcdocBlockStates[Extract<BLOCK, keyof SymbolMcdocBlockStates>]>> : Record<string, string | boolean | number>, MACRO>,
-    nbt?: Macroable<BLOCK extends keyof SymbolBlock ? NonNullable<SymbolBlock[Extract<BLOCK, keyof SymbolBlock>]> : SymbolBlock<'%fallback'>, MACRO>,
-    type?: 'destroy' | 'keep' | 'replace' | 'strict',
+    nbt?: Macroable<BLOCK extends keyof SymbolBlock
+      ? NonNullable<AllowConst<SymbolBlock[Extract<BLOCK, keyof SymbolBlock>]>>
+      : AllowConst<RootNBT>,
+    MACRO>,
+    flag?: 'destroy' | 'keep' | 'replace' | 'strict',
   ): FinalCommandOutput
 
   setblock(
@@ -158,7 +165,7 @@ export class SetBlockCommand<MACRO extends boolean> extends CommandArguments {
       : blockStateStringifier(arg3 as any as Record<string, string | number | boolean>)
     const nbt = typeof arg4 === 'string' || arg4 === undefined ?
       ''
-      : nbtResolver(arg4 as any as NBTObject).toString()
+      : nbtResolver(arg4 as any as RootNBT).toString()
     const setblockType = typeof arg4 === 'string' ? arg4 : arg5
 
     return this.finalCommand([coordinatesParser(pos), `${block}${state}${nbt}`, setblockType])

package/src/commands/implementations/entity/execute.ts

@@ -14,6 +14,7 @@ import type {
   SingleEntityArgumentOf,
   SymbolBlock,
   SymbolMcdocBlockStates,
+  RootNBT,
 } from 'sandstone/arguments'
 import { blockStateStringifier } from '../block/setblock'
 import type { SandstoneCommands } from 'sandstone/commands'
@@ -28,7 +29,7 @@ import type { Node } from 'sandstone/core/nodes'
 import { ContainerCommandNode } from 'sandstone/core/nodes'
 import type { _RawMCFunctionClass } from 'sandstone/core/resources/datapack/mcfunction'
 import type { SandstonePack } from 'sandstone/pack'
-import { makeCallable, type NamespacedLiteralUnion } from 'sandstone/utils'
+import { type AllowConst, makeCallable, type NamespacedLiteralUnion } from 'sandstone/utils'
 import type { DataPointClass } from 'sandstone/variables/Data'
 import type { ObjectiveClass } from 'sandstone/variables/Objective'
 import type { ItemPredicateClass } from 'sandstone/variables/ItemPredicate'
@@ -561,15 +562,16 @@ export class ExecuteIfUnlessCommand<MACRO extends boolean> extends ExecuteComman
       ? ParseBlockState<NonNullable<SymbolMcdocBlockStates[Extract<BLOCK, keyof SymbolMcdocBlockStates>]>>
       : Record<string, string | boolean | number> | undefined, MACRO>,
     nbt: Macroable<BLOCK extends keyof SymbolBlock
-      ? NonNullable<SymbolBlock[Extract<BLOCK, keyof SymbolBlock>]>
-      : SymbolBlock<'%fallback'>, MACRO>,
+      ? NonNullable<AllowConst<SymbolBlock[Extract<BLOCK, keyof SymbolBlock>]>>
+      : AllowConst<RootNBT>,
+    MACRO>,
   ): ExecuteCommand<MACRO>
 
   block(
     pos: Macroable<Coordinates<MACRO>, MACRO>,
     block: Macroable<Registry['minecraft:block'], MACRO>,
     state?: Macroable<Record<string, string | boolean | number>, MACRO>,
-    nbt?: Macroable<NBTObject, MACRO>,
+    nbt?: Macroable<AllowConst<RootNBT>, MACRO>,
   ) {
     const stateStr = state && typeof state === 'object' && Object.keys(state).length > 0
       ? blockStateStringifier(state as Record<string, string | number | boolean>)

package/src/commands/implementations/entity/summon.ts

@@ -5,6 +5,7 @@ import { NBT, nbtResolver } from 'sandstone/variables/nbt/NBTs'
 import { coordinatesParser } from 'sandstone/variables/parsers'
 import { CommandArguments } from '../../helpers'
 import type { Registry } from 'sandstone/arguments/generated/registry'
+import { AllowConst } from 'sandstone/utils'
 
 export class SummonCommandNode extends CommandNode {
   command = 'summon' as const
@@ -50,7 +51,7 @@ export class SummonCommand<MACRO extends boolean> extends CommandArguments {
   summon<ENTITY extends Macroable<Registry['minecraft:entity_type'], MACRO>>(
     entity: ENTITY,
     pos?: Macroable<Coordinates<MACRO>, MACRO>,
-    nbt?: Macroable<ENTITY extends keyof SymbolEntity ? NonNullable<SymbolEntity[ENTITY]> : RootNBT, MACRO>,
+    nbt?: Macroable<AllowConst<ENTITY extends keyof SymbolEntity ? NonNullable<SymbolEntity[ENTITY]> : RootNBT>, MACRO>,
   ) {
     const args: unknown[] = [entity]
     if (pos !== undefined) {

package/src/utils.ts

@@ -721,4 +721,6 @@ export type SmartRange<Min extends number, Max extends number> = (
       : ToNegative<PositiveRange<1, Abs<Min>>> | 0 | PositiveRange<1, Max>
     :
       PositiveRange<Min, Max>
-)
+)
+
+export type AllowConst<T> = T | (readonly [T])[0]