sandstone 1.0.0-beta.4 → 1.0.0

package/src/commands/implementations/server/schedule.ts

@@ -1,5 +1,6 @@
 import type { TimeArgument } from 'sandstone/arguments'
 import type { Macroable, Node } from 'sandstone/core'
+import { isMacroArgument } from 'sandstone/core/Macro'
 import { ContainerCommandNode } from 'sandstone/core/nodes'
 import type { MCFunctionClass, MCFunctionNode } from 'sandstone/core/resources/datapack'
 import type { TagClass } from 'sandstone/core/resources/datapack/tag'
@@ -61,7 +62,10 @@ export class ScheduleCommand<MACRO extends boolean> extends CommandArguments<typ
    * ```
    */
   clear = (func: Macroable<MCFunctionClass<any, any> | string | TagClass<'function'>, MACRO>) => {
-    const result = this.finalCommand(['clear', `${func}`])
+    const funcArg = isMacroArgument(this.sandstoneCore, func)
+      ? func
+      : `${func}`
+    const result = this.finalCommand(['clear', funcArg])
     return result
   }
 
@@ -101,6 +105,10 @@ export class ScheduleCommand<MACRO extends boolean> extends CommandArguments<typ
       return this.finalCommand(['function', undefined, delay, type], node)
     }
 
-    return this.finalCommand(['function', `${func}`, delay, type], node)
+    const funcArg = isMacroArgument(this.sandstoneCore, func)
+      ? func
+      : `${func}`
+
+    return this.finalCommand(['function', funcArg, delay, type], node)
   }
 }

package/src/commands/implementations/world/data.ts

@@ -3,7 +3,7 @@ import { type MacroArgument, type Macroable } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core/nodes'
 import { makeCallable } from 'sandstone/utils'
 import { DataPointClass, type VectorClass } from 'sandstone/variables'
-import { nbtStringifier } from 'sandstone/variables/nbt/NBTs'
+import { nbtResolver } from 'sandstone/variables/nbt/NBTs'
 import { coordinatesParser, targetParser } from 'sandstone/variables/parsers'
 import { CommandArguments, type FinalCommandOutput } from '../../helpers'
 
@@ -156,7 +156,7 @@ export class DataMergeCommand<MACRO extends boolean> extends CommandArguments {
    * @param nbt The NBT to merge with.
    */
   block = (targetPos: Macroable<Coordinates<MACRO>, MACRO>, nbt: Macroable<NBTObject, MACRO>) =>
-    this.finalCommand(['block', coordinatesParser(targetPos), nbtStringifier(nbt)])
+    this.finalCommand(['block', coordinatesParser(targetPos), nbtResolver(nbt)])
 
   /**
    * Merge the NBT of the given entity, with the given NBT.
@@ -165,7 +165,7 @@ export class DataMergeCommand<MACRO extends boolean> extends CommandArguments {
    * @param nbt The NBT to merge with.
    */
   entity = <T extends string>(target: Macroable<SingleEntityArgumentOf<MACRO, T>, MACRO>, nbt: Macroable<NBTObject, MACRO>) =>
-    this.finalCommand(['entity', targetParser(target), nbtStringifier(nbt)])
+    this.finalCommand(['entity', targetParser(target), nbtResolver(nbt)])
 
   /**
    * Merge the NBT of the given storage path, with the given NBT.
@@ -174,7 +174,7 @@ export class DataMergeCommand<MACRO extends boolean> extends CommandArguments {
    * @param nbt The NBT to merge with.
    */
   storage = (target: Macroable<string, MACRO>, nbt: Macroable<NBTObject, MACRO>) =>
-    this.finalCommand(['storage', target, nbtStringifier(nbt)])
+    this.finalCommand(['storage', target, nbtResolver(nbt)])
 }
 
 export class DataModifyFromCommand<MACRO extends boolean> extends CommandArguments {
@@ -302,7 +302,7 @@ export class DataModifyValuesCommand<MACRO extends boolean> extends CommandArgum
   /**
    * Modify the NBT with the given value.
    */
-  value = (value: Macroable<NBTObject, MACRO>) => this.finalCommand(['value', nbtStringifier(value)])
+  value = (value: Macroable<NBTObject, MACRO>) => this.finalCommand(['value', nbtResolver(value)])
 }
 
 export class DataModifyTypeCommand<MACRO extends boolean> extends CommandArguments {

package/src/commands/implementations/world/item.ts

@@ -9,7 +9,7 @@ import type {
 import type { ItemModifierClass, Macroable } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core/nodes'
 import type { LiteralUnion } from 'sandstone/utils'
-import { nbtStringifier } from 'sandstone/variables'
+import { nbtResolver } from 'sandstone/variables'
 import { coordinatesParser, targetParser } from 'sandstone/variables/parsers'
 import type { FinalCommandOutput } from '../../helpers'
 import { CommandArguments } from '../../helpers'
@@ -44,7 +44,7 @@ export class ItemSourceCommand<MACRO extends boolean> extends CommandArguments {
     count?: Macroable<number, MACRO>,
   ) {
     if (typeof countOrNBT === 'object') {
-      return this.finalCommand(['with', `${item}${nbtStringifier(countOrNBT)}`, count])
+      return this.finalCommand(['with', `${item}${nbtResolver(countOrNBT)}`, count])
     }
     return this.finalCommand(['with', item, countOrNBT])
   }

package/src/commands/implementations/world/time.ts

@@ -1,4 +1,4 @@
-import type { TimeArgument } from 'sandstone/arguments'
+import type { Registry, TimeArgument } from 'sandstone/arguments'
 import type { Macroable, WorldClockClass } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core/nodes'
 import { CommandArguments } from '../../helpers'
@@ -32,11 +32,11 @@ export class TimeArguments<MACRO extends boolean> extends CommandArguments {
    * Queries current time.
    *
    * @param type Specifies the time to query. Can be one of the following:
-   * - `daytime`: the number of game ticks since dawn. (the in-game daytime modulo 24000)
    * - `gametime`: the age of the world in game ticks. (the game time modulo 2147483647)
-   * - `day`: the number of in-game days passed. (the in-game daytime divided by 24000, then modulo 2147483647)
+   * - `time`: an alias for the `minecraft:overworld` timeline
+   * - Any data-driven timeline (eg. `minecraft:villager_schedule`)
    */
-  query = (type: Macroable<LiteralUnion<'daytime' | 'gametime' | 'day'>, MACRO>) => this.finalCommand(['query', type])
+  query = (type: Macroable<'gametime' | 'time' | Registry['minecraft:timeline'], MACRO>) => this.finalCommand(['query', type])
 
   /**
    * Sets the in-game daytime.
@@ -46,7 +46,7 @@ export class TimeArguments<MACRO extends boolean> extends CommandArguments {
    * - `s`: a second, 20 gameticks;
    * - `t` (default and omitable): a single gametick; the default unit.
    */
-  set = (time: Macroable<TimeArgument | LiteralUnion<'day' | 'night' | 'noon' | 'midnight'>, MACRO>) =>
+  set = (time: Macroable<TimeArgument | NamespacedLiteralUnion<'day' | 'night' | 'noon' | 'midnight'>, MACRO>) =>
     this.finalCommand(['set', time])
 }
 

package/src/core/Macro.ts

@@ -39,8 +39,6 @@ export class MacroArgument {
 
 export type Macroable<T, MACRO extends boolean> = MACRO extends true ? T | MacroArgument : T
 
-export type MacroString<T, MACRO extends boolean> = MACRO extends true ? T | string : T
-
 export function isMacroArgument(core: SandstoneCore, arg: any) {
   if (typeof arg === 'object' && Object.hasOwn(arg, 'toMacro')) {
     // eslint-disable-next-line prefer-destructuring

package/src/core/nodes.ts

@@ -1,5 +1,6 @@
 import type { SandstonePack } from 'sandstone/pack'
 import type { LoopArgument } from 'sandstone/variables'
+import { ResolvedNBT } from 'sandstone/variables/nbt/NBTs'
 import * as util from 'util'
 import { formatDebugString } from '../utils'
 import { isMacroArgument, type MacroArgument } from './Macro'
@@ -110,10 +111,25 @@ export abstract class CommandNode<ARGS extends unknown[] = unknown[]> extends No
       if (arg !== undefined && arg !== null) {
         // Yes these are cursed, unfortunately, there's not really a better way to do this as visitors only visit the root nodes.
         if (typeof arg === 'object') {
-          if (isMacroArgument(this.sandstoneCore, arg)) {
+          if (arg instanceof ResolvedNBT) {
+            // ResolvedNBT carries macro info forward from nbtResolver recursion,
+            // so we can detect $(...) substitutions that originated inside nested
+            // NBT values rather than from a top-level MacroArgument object.
+            if (arg.containsMacro) {
+              this.isMacro = true
+            }
+            filteredArgs.push(arg)
+          } else if (isMacroArgument(this.sandstoneCore, arg)) {
             this.isMacro = true
 
             filteredArgs.push((arg as MacroArgument).toMacro())
+          } else if (Object.hasOwn(arg, '_hasMacro') && (arg as { _hasMacro: boolean })._hasMacro) {
+            // Selector (and any similar complex arg that stringifies `$(...)`
+            // via its own toString) exposes macro info via _hasMacro so the
+            // command can still be flagged as a macro command.
+            this.isMacro = true
+
+            filteredArgs.push(arg)
           } else if (Object.hasOwn(arg, 'toLoop')) {
             filteredArgs.push((arg as LoopArgument).toLoop())
           } else {

package/src/core/resources/datapack/mcfunction.ts

@@ -19,8 +19,6 @@ import { CallableResourceClass } from '../resource'
 import { TagClass } from './tag'
 import type { DataPointClass } from 'sandstone/variables'
 
-const tags: Record<string, TagClass<'function'>> = {}
-
 // interface AttributeWrapper {
 //  attributes: string[]
 // }
@@ -342,15 +340,20 @@ export class _RawMCFunctionClass<
       func = this as unknown as MCFunctionClass<undefined, undefined>
     }
     if (typeof tag === 'string') {
-      if (tags[tag]) {
-        tags[tag].push(func)
+      // Cache lives on SandstoneCore so its lifetime matches the core (cleared on reset).
+      // This prevents stale TagClass references from a previous pack surviving across
+      // watch-mode rebuilds and silently dropping the tag from the new build's output.
+      const existing = this.core.functionTags.get(tag)
+      if (existing) {
+        existing.push(func)
       } else {
-        tags[tag] = new TagClass(this.core, 'function', tag, {
+        const newTag = new TagClass(this.core, 'function', tag, {
           values: [func],
           addToSandstoneCore: true,
           creator: 'sandstone',
           onConflict: 'append',
         })
+        this.core.functionTags.set(tag, newTag)
       }
     } else {
       tag.push(func)
@@ -391,6 +394,10 @@ export class _RawMCFunctionClass<
           false,
         )
         this.core.exitMCFunction()
+        // Mark as generated so the later generateResources iteration doesn't re-run
+        // the callback (which would re-execute with undefined params and append a
+        // second broken command to the body).
+        this.generated = true
       } else if (this.callback.length > 1) {
         throw new Error(`[MCFunctionClass] Function ${this.name} expects ${this.callback.length - 1} params at the call-site`)
       }

package/src/core/resources/datapack/structure.ts

@@ -1,5 +1,6 @@
 /* eslint-disable no-plusplus */
 /* eslint-disable max-len */
+// TODO: prismarine-nbt uses Node.js zlib, needs browser-compatible alternative for playground
 import lodash from 'lodash'
 import prismarine, { type NBT } from 'prismarine-nbt'
 import {

package/src/core/resources/resourcepack/sound.ts

@@ -5,8 +5,6 @@ import type { SandstoneCore } from '../../sandstoneCore'
 import type { ListResource, ResourceClassArguments, ResourceNode } from '../resource'
 import { ResourceClass, jsonStringify } from '../resource'
 
-const sounds: Map<string, SoundsClass> = new Map()
-
 /**
  * A node representing a Minecraft sound.
  */
@@ -63,10 +61,10 @@ export class SoundEventClass<Type extends SOUND_TYPES = SOUND_TYPES> extends Res
       }
 
       if (args.addToSounds) {
-        let def = sounds.get(this.path[0])
+        let def = this.core.sounds.get(this.path[0])
 
         if (!def) {
-          def = sounds
+          def = this.core.sounds
             .set(
               this.path[0],
               new SoundsClass(this.core, this.path[0], {

package/src/core/sandstoneCore.ts

@@ -9,7 +9,9 @@ import type { MCMetaBranches } from './mcmeta'
 import { MCMetaCache } from './mcmeta'
 import type { AwaitNode } from './nodes'
 import type { _RawMCFunctionClass, MCFunctionClass, MCFunctionNode } from './resources/datapack/mcfunction'
+import type { TagClass } from './resources/datapack/tag'
 import { SmithedDependencyClass } from './resources/dependency'
+import type { SoundsClass } from './resources/resourcepack/sound'
 import { type ResourceClass, ResourceNodesMap } from './resources/resource'
 import { SmithedDependencyCache } from './smithed'
 import type { GenericCoreVisitor } from './visitors'
@@ -30,10 +32,22 @@ export class SandstoneCore {
 
   dependencies: ((() => Promise<true | false>) | true | false)[] = []
 
+  /** Cache of auto-generated function tags, keyed by tag name. Cleared on reset. */
+  functionTags: Map<string, TagClass<'function'>> = new Map()
+
+  /** Cache of auto-generated sounds.json definitions, keyed by namespace. Cleared on reset. */
+  sounds: Map<string, SoundsClass> = new Map()
+
+  /** Cache of auto-generated polling trigger check functions, keyed by polling interval. Cleared on reset. */
+  checkTriggers: Record<number, MCFunctionClass<undefined, undefined>> = {}
+
   constructor(public pack: SandstonePack) {
     this.resourceNodes = new ResourceNodesMap()
     this.mcfunctionStack = []
     this.awaitNodes = new Set()
+    this.functionTags = new Map()
+    this.sounds = new Map()
+    this.checkTriggers = {}
 
     // ESM is funny
 
@@ -54,6 +68,9 @@ export class SandstoneCore {
     this._mcMetaCache = undefined
     this._smithed = undefined
     this.dependencies = []
+    this.functionTags.clear()
+    this.sounds.clear()
+    this.checkTriggers = {}
   }
 
   /**

package/src/flow/conditions/variables/block.ts

@@ -1,6 +1,6 @@
 import type { Coordinates, NBTObject } from 'sandstone/arguments'
 import type { SandstoneCore } from 'sandstone/core/sandstoneCore'
-import { coordinatesParser, nbtStringifier } from 'sandstone/variables'
+import { coordinatesParser, nbtResolver } from 'sandstone/variables'
 import { SingleConditionNode } from '../condition'
 import type { Registry } from 'sandstone/arguments/generated/registry'
 import { blockStateStringifier } from 'sandstone/commands/implementations/block/setblock'
@@ -20,7 +20,7 @@ export class BlockConditionNode extends SingleConditionNode {
     const stateStr = this.state && Object.keys(this.state).length > 0
       ? blockStateStringifier(this.state)
       : ''
-    const nbtStr = this.nbt ? nbtStringifier(this.nbt) : ''
+    const nbtStr = this.nbt ? nbtResolver(this.nbt).toString() : ''
     return ['block', coordinatesParser(this.position), `${this.block}${stateStr}${nbtStr}`]
   }
 }

package/src/flow/loops/for_i.ts

@@ -4,7 +4,6 @@ import { LoopArgument } from 'sandstone/variables'
 import { conditionToNode, type Condition } from '..'
 import { IfStatement } from '../if_else'
 import { LoopNode } from '../loop'
-import { analyzeCondition, warnStaticallyFalseCondition } from './staticAnalysis'
 
 export class ForINode extends LoopNode {
   // eslint-disable-next-line max-len
@@ -24,21 +23,24 @@ export class ForINode extends LoopNode {
         () => new IfStatement(sandstoneCore, condition, () => new LoopArgument(sandstoneCore.pack)),
       )
 
-    // Check if we can inline the first iteration via static analysis
-    const analysisResult = typeof initialValue === 'number'
-      ? analyzeCondition(condition, iterator, initialValue)
-      : { canAnalyze: false as const }
+    // TODO: Move this to a visitor, it is too unsafe to have this because of `_continue`, `returnCmd` and nested loops
+    // // Check if we can inline the first iteration via static analysis
+    // const analysisResult = typeof initialValue === 'number'
+    //   ? analyzeCondition(condition, iterator, initialValue)
+    //   : { canAnalyze: false as const }
 
-    if (analysisResult.canAnalyze) {
-      if (analysisResult.result) {
-        // Condition is statically true - inline the first iteration
-        callback(iterator, _continue)
-        iterate(iterator)
-      } else {
-        // Condition is statically false - loop will never execute
-        warnStaticallyFalseCondition('for', `initial value ${initialValue} does not satisfy condition`)
-      }
-    }
+    // if (analysisResult.canAnalyze) {
+    //   if (analysisResult.result) {
+    //     // Condition is statically true - inline the first iteration
+    //     console.log('#### Statically inlining first ForINode iteration')
+    //     console.log(`##### ${sandstoneCore.getCurrentMCFunctionOrThrow().resource.name}`)
+    //     callback(iterator, _continue)
+    //     iterate(iterator)
+    //   } else {
+    //     // Condition is statically false - loop will never execute
+    //     warnStaticallyFalseCondition('for', `initial value ${initialValue} does not satisfy condition`)
+    //   }
+    // }
 
     super(
       sandstoneCore,

package/src/flow/loops/for_of.ts

@@ -1,4 +1,3 @@
-import type { SubCommand } from 'sandstone/commands'
 import type { SandstoneCore } from 'sandstone/core/sandstoneCore'
 import type { DataPointClass, IterableDataClass, Score, StringDataPointClass } from 'sandstone/variables'
 import { LoopArgument } from 'sandstone/variables'

package/src/pack/pack.ts

@@ -481,6 +481,9 @@ export class SandstonePack {
   }
 
   resourceToPath = (name: string, resourceFolders?: readonly string[]): ResourcePath => {
+    if (name === '') {
+      throw new Error('A resource name must not be empty!')
+    }
     let namespace = this.defaultNamespace
     let fullName = name
 
@@ -503,6 +506,11 @@ export class SandstonePack {
   }
 
   registerNewObjective = (objective: ObjectiveClass) => {
+    for (const obj of this.objectives) {
+      if (obj.name === objective.name) {
+        return
+      }
+    }
     this.objectives.add(objective)
   }
 
@@ -523,8 +531,7 @@ export class SandstonePack {
      * @param options.alreadyExists If true, the objective will not be registered as a new one. Defaults to false.
      * @param options.useDefaultNamespace If true (the default), the objective will be created in the default namespace. \
      *                            For example, if the default namespace is `sandstone`, then the objective will be created as `sandstone.objective_name`. \
-     *                            If false, the objective will be created without a namespace. \
-     *                            This argument is ignored if the `name` already contains a namespace (determined by the presence of a dot `"."` or a double underscore `"__"`).
+     *                            If false, the objective will be created without a namespace.
      */
     create: (
       name: string,
@@ -573,7 +580,7 @@ export class SandstonePack {
     } else {
       this.namedVariableIds[name] ??= 0
 
-      return `${name}_${this.namedVariableIds[name]}_${this.packUid}`
+      return `${name}_${this.namedVariableIds[name]++}_${this.packUid}`
     }
   }
 
@@ -971,7 +978,7 @@ export class SandstonePack {
 
       this.ticked[runEvery] = this.Tag('function', name, [])
 
-      this.MCFunction(name, (self) => {
+      const looped = this.MCFunction(name, (self) => {
         this.commands.functionCmd(this.ticked[runEvery])
 
         self.schedule.function(runEvery, 'replace')
@@ -981,7 +988,7 @@ export class SandstonePack {
         this.startAllTicked = this.MCFunction(`__sandstone:ticked/start/${this.packUid.toLowerCase()}`)
         this.loadTags.load.push(this.startAllTicked)
       }
-      this.startAllTicked.push(() => this.commands.schedule.function(this.ticked[runEvery], runEvery, 'replace'))
+      this.startAllTicked.push(() => looped())
 
       return this.ticked[runEvery]
     })()
@@ -1009,7 +1016,7 @@ export class SandstonePack {
     this.tickedCommands[runEvery].push(callback)
   }
 
-  sleep = (delay: TimeArgument): PromiseLike<SleepClass> => new SleepClass(this.core, delay).promise()
+  sleep = (delay: TimeArgument) => new SleepClass(this.core, delay)
 
   Loop = () => new LoopArgument(this)
 

package/src/sandstone.ts

@@ -45,7 +45,7 @@ import type {
 import { SandstonePack } from './pack'
 import type { Flow } from './flow'
 import type { BASIC_CONFLICT_STRATEGIES, LiteralUnion, NamespacedLiteralUnion, SetType } from './utils'
-import { Set } from './utils'
+import { randomUUID, Set } from './utils'
 import * as coordinates from './variables/Coordinates'
 import { ResolveNBTPart } from './variables/ResolveNBT'
 import { setSandstoneContext, hasContext, getSandstoneContext } from './context'
@@ -98,7 +98,7 @@ export function resetSandstonePack(): void {
   }
 }
 
-export { LiteralUnion, NamespacedLiteralUnion, Set, SetType }
+export { LiteralUnion, NamespacedLiteralUnion, randomUUID, Set, SetType }
 
 export { ResolveNBTPart }
 

package/src/utils.ts

@@ -573,3 +573,162 @@ type McdocNegatableIDMapBase<Dispatcher, UnknownValue> = MemberModifiers<Dispatc
 export type McdocNegatableIDMap<Dispatcher, UnknownValue> = Partial<McdocNegatableIDMapBase<Dispatcher, UnknownValue>> & {
   [K in keyof MemberModifiers<Dispatcher>]-?: Record<K, McdocNegatableIDMapBase<Dispatcher, UnknownValue>[K]>
 }[keyof MemberModifiers<Dispatcher>]
+
+export type Enumerate<
+  N extends number,
+  Acc extends number[] = [],
+> = ( number extends N
+  ? number // Guard against wide 'number'
+  : Acc["length"] extends N
+    ? Acc[number]
+    : Enumerate<N, [...Acc, Acc["length"]]>
+)
+
+export type BuildTuple<N extends number, T extends never[] = []> = (
+  number extends N
+    ? never[] // Guard against wide 'number'
+    : T['length'] extends N
+      ? T
+      : BuildTuple<N, [...T, never]>
+)
+
+export type Increment<N extends number> = (
+  number extends N
+    ? number // Guard against wide 'number'
+    : [...BuildTuple<N>, never]['length'] & number
+)
+
+/**
+ * `0..`
+ *
+ * Can be made exclusive of zero via `Exclude<PositiveNumber<N>, 0>`
+ */
+export type PositiveNumber<T extends number> = (
+  number extends T
+    ? never
+    : `${T}` extends `-${string}`
+        ? never
+        : T
+)
+
+/**
+ * `..<0`; Cannot be zero nor above zero.
+ *
+ * Can be made inclusive via `NegativeNumber<N> | 0`
+ */
+export type NegativeNumber<T extends number> = (
+  number extends T
+    ? never
+    : `${T}` extends `-${string}`
+      ? T
+      : never
+)
+
+/** 
+ * No decimal allowed.
+ */
+export type WholeNumber<T extends number> = (
+  number extends T
+    ? never
+    : `${T}` extends `${string}.${string}`
+      ? never
+      : T
+)
+
+/**
+ * `0..` & no decimal allowed.
+ * 
+ * Can be made exclusive of zero via `Exclude<PositiveWholeNumber<N>, 0>`
+ */
+export type PositiveWholeNumber<N extends number> = (
+  PositiveNumber<N> extends never
+    ? never
+    : WholeNumber<N> extends never
+      ? never
+      : N
+)
+
+/**
+ * `..-1` & no decimal allowed.
+ * 
+ * Can include zero via `NegativeWholeNumber<N> | 0`
+ */
+export type NegativeWholeNumber<T extends number> = (
+  number extends T
+    ? never
+    : `${T}` extends `${string}.${string}`
+      ? never
+      : `${T}` extends `-${string}`
+        ? T
+        : never
+)
+
+/**
+ * `0<..<1`; Cannot be zero nor one, below zero, nor above one. 
+ *
+ * Can be made inclusive by adding unioned `0`/`1` literals. (eg. `PositiveFraction<N> | 0 | 1`)
+ */
+export type PositiveFraction<T extends number> = (
+  number extends T
+    ? never
+    : `${T}` extends `0.${string}`
+        ? T
+        : never
+)
+
+/**
+ * `-1<..<0`; Cannot be negative one nor zero, below negative one, nor above zero. 
+ *
+ * Can be made inclusive by adding unioned `-1`/`0` literals. (eg. `NegativeFraction<N> | -1 | 0`)
+ */
+export type NegativeFraction<T extends number> = (
+  number extends T
+    ? never
+    : `${T}` extends `-0.${string}`
+        ? T
+        : never
+)
+
+/**
+ * Converts a positive numeric literal to its negative counterpart.
+ * Example: ToNegative<5> -> -5
+ */
+export type ToNegative<T extends number> = (
+  T extends 0
+    ? 0
+    : `-${T}` extends `${infer N extends number}`
+      ? N
+      : never
+)
+
+/**
+ * Checks if a number literal is negative by checking its string representation.
+ */
+export type IsNegative<N extends number> = `${N}` extends `-${string}` ? true : false
+
+/**
+ * Gets the absolute value of a number.
+ */
+export type Abs<N extends number> = `${N}` extends `-${infer U extends number}` ? U : N
+
+/**
+ * Creates a union of numbers from 0 to N-1.
+ */
+export type RangeTo<N extends number> = Enumerate<N>
+
+/**
+ * Generates a union of numbers between two positive integers (inclusive).
+ */
+export type PositiveRange<Start extends number, End extends number> = Exclude<Enumerate<Increment<End>>, Enumerate<Start>>
+
+/**
+ * The core logic for NBTInt<{ min: -5, max: 2 }>
+ */
+export type SmartRange<Min extends number, Max extends number> = (
+  IsNegative<Min> extends true
+    ? IsNegative<Max> extends true
+      ? ToNegative<PositiveRange<Abs<Max>, Abs<Min>>>
+      : ToNegative<PositiveRange<1, Abs<Min>>> | 0 | PositiveRange<1, Max>
+    :
+      PositiveRange<Min, Max>
+)

package/src/variables/Data.ts

@@ -4,7 +4,7 @@ import type { DataModifyTypeCommand, DataModifyValuesCommand, StoreType } from '
 import type { SandstonePack } from 'sandstone/pack'
 import { DataPointPickClass, isMacroArgument, MacroArgument, MacroLiteral } from '../core/Macro'
 import type { ConditionTextComponentClass } from './abstractClasses'
-import { nbtStringifier } from './nbt/NBTs'
+import { nbtResolver } from './nbt/NBTs'
 import { Score } from './Score'
 
 export type DATA_TYPES = 'entity' | 'block' | 'storage'
@@ -50,7 +50,7 @@ export function NBTpathToString(pack: SandstonePack, paths: DATA_PATH[]) {
         // Special case: array index like [0] - don't add 'd' suffix
         parsedPaths.push(`[${path[0]}]`)
       } else {
-        parsedPaths.push(nbtStringifier(path))
+        parsedPaths.push(nbtResolver(path).toString())
       }
     } else if (path !== '') {
       parsedPaths.push(`${path}${i === paths.length - 1 ? '' : '.'}`)
@@ -307,7 +307,7 @@ export class DataPointClass<TYPE extends DATA_TYPES = any>
   /**
    * @internal
    */
-  toNBT = () => nbtStringifier(this._toChatComponent() as NBTObject)
+  toNBT = () => nbtResolver(this._toChatComponent() as NBTObject).toString()
 }
 
 export class StringDataPointClass<TYPE extends DATA_TYPES = any> extends DataPointClass {

package/src/variables/ItemPredicate.ts

@@ -2,7 +2,7 @@ import type { SymbolDataComponent, SymbolDataComponentPredicate } from 'sandston
 import type { Registry } from 'sandstone/arguments/generated/registry'
 import type { MinMaxBounds } from 'sandstone/arguments/generated/data/util'
 import type { SandstonePack } from 'sandstone/pack'
-import { nbtStringifier } from 'sandstone/variables/nbt/NBTs'
+import { nbtResolver } from 'sandstone/variables/nbt/NBTs'
 import * as util from 'util'
 import { formatDebugString } from '../utils'
 import type { MacroArgument } from 'sandstone/core/Macro'
@@ -196,7 +196,7 @@ export class ItemPredicateClass {
       return `${prefix}${test.component}`
     }
 
-    const valueStr = nbtStringifier(test.value)
+    const valueStr = nbtResolver(test.value).toString()
     return `${prefix}${test.component}${test.operator}${valueStr}`
   }