sandstone 1.0.0-beta.4 → 1.0.0

package/src/variables/Score.ts

@@ -13,7 +13,7 @@ import type {
 } from 'sandstone/arguments'
 import type { ExecuteCommand, SandstoneCommands } from 'sandstone/commands'
 import type { NotNode } from 'sandstone/flow'
-import { nbtStringifier, type ConditionClass } from 'sandstone/variables'
+import { nbtResolver, type ConditionClass } from 'sandstone/variables'
 import * as util from 'util'
 import { MacroArgument } from '../core/Macro'
 import type { SandstonePack } from '../pack'
@@ -96,7 +96,7 @@ export class Score extends MacroArgument implements ConditionClass, ComponentCla
   }
 
   toNBT() {
-    return nbtStringifier(this._toChatComponent() as NBTObject)
+    return nbtResolver(this._toChatComponent() as NBTObject).toString()
   }
 
   toJSON() {
@@ -353,6 +353,8 @@ export class Score extends MacroArgument implements ConditionClass, ComponentCla
     return this.binaryOperation('%=', ...args)
   }
 
+  mod = this.modulo
+
   '%=' = this.modulo
 
   /**
@@ -443,6 +445,8 @@ export class Score extends MacroArgument implements ConditionClass, ComponentCla
     return createVariable(this.sandstonePack, this).binaryOperation('*=', ...args)
   }
 
+  times = this.multipliedBy
+
   '*' = this.multipliedBy
 
   /**
@@ -487,6 +491,8 @@ export class Score extends MacroArgument implements ConditionClass, ComponentCla
     return createVariable(this.sandstonePack, this).binaryOperation('%=', ...args)
   }
 
+  modBy = this.moduloBy
+
   '%' = this.moduloBy
 
   /** COMPARISONS OPERATORS */
@@ -548,20 +554,20 @@ export class Score extends MacroArgument implements ConditionClass, ComponentCla
    *
    * @param objective The related objective. If not specified, default to the same objective as the current target.
    */
-  greaterOrEqualThan(targets: MultipleEntitiesArgument<false>, objective?: ObjectiveArgument): ConditionClass
+  greaterThanOrEqualTo(targets: MultipleEntitiesArgument<false>, objective?: ObjectiveArgument): ConditionClass
 
   /**
    * Check if the current score is greater or equal than the given amount or score.
    *
    * @param amountOrTargetScore The amount or score compare the current score against.
    */
-  greaterOrEqualThan(amountOrTargetScore: number | Score): ConditionClass
+  greaterThanOrEqualTo(amountOrTargetScore: number | Score): ConditionClass
 
-  greaterOrEqualThan(...args: OperationArguments) {
+  greaterThanOrEqualTo(...args: OperationArguments) {
     return this.comparison('>=', `${args[0]}..`, args)
   }
 
-  '>=' = this.greaterOrEqualThan
+  '>=' = this.greaterThanOrEqualTo
 
   /**
    * Check if the current score is strictly lower than the given score.
@@ -592,20 +598,20 @@ export class Score extends MacroArgument implements ConditionClass, ComponentCla
    *
    * @param objective The related objective. If not specified, default to the same objective as the current target.
    */
-  lessOrEqualThan(targets: MultipleEntitiesArgument<false>, objective?: ObjectiveArgument): ConditionClass
+  lessThanOrEqualTo(targets: MultipleEntitiesArgument<false>, objective?: ObjectiveArgument): ConditionClass
 
   /**
    * Check if the current score is lower or equal than the given amount or score.
    *
    * @param amountOrTargetScore The amount or score target to compare the current score against.
    */
-  lessOrEqualThan(amountOrTargetScore: number | Score): ConditionClass
+  lessThanOrEqualTo(amountOrTargetScore: number | Score): ConditionClass
 
-  lessOrEqualThan(...args: OperationArguments) {
+  lessThanOrEqualTo(...args: OperationArguments) {
     return this.comparison('<=', `..${args[0]}`, args)
   }
 
-  '<=' = this.lessOrEqualThan
+  '<=' = this.lessThanOrEqualTo
 
   /**
    * Check if the current score is equal to than the given score.
@@ -627,6 +633,8 @@ export class Score extends MacroArgument implements ConditionClass, ComponentCla
     return this.comparison('=', args[0].toString(), args)
   }
 
+  equals = this.equalTo
+
   '==' = this.equalTo
 
   /**

package/src/variables/Selector.ts

@@ -4,7 +4,7 @@
 import type { GAMEMODES, JSONTextComponent, NBTSerializable, Range, RootNBT, SymbolEntity } from 'sandstone/arguments'
 import type { PredicateClass, SandstoneCore, TagClass } from 'sandstone/core'
 import type { SandstonePack } from 'sandstone/pack'
-import { nbtStringifier } from 'sandstone/variables/nbt/NBTs'
+import { nbtResolver, ResolvedNBT } from 'sandstone/variables/nbt/NBTs'
 import { rangeParser } from 'sandstone/variables/parsers'
 import * as util from 'util'
 import type { Macroable } from '../core/Macro'
@@ -316,6 +316,17 @@ export class SelectorClass<
 
   arguments: SelectorProperties<IsSingle, IsPlayer, SelectorEntityType, MACRO>
 
+  /**
+   * Whether the most recent `toString()` produced a selector string containing
+   * any `$(...)` macro substitution. `CommandNode.getValue()` reads this so it
+   * can flag the surrounding command as a macro command (prefixed with `$`),
+   * even though `toString()` itself returns a plain string (the `$(...)` is
+   * baked in via template literal coercion).
+   *
+   * @internal
+   */
+  _hasMacro = false
+
   constructor(
     protected sandstonePack: SandstonePack,
     public target: '@s' | '@p' | '@a' | '@e' | '@n' | '@r',
@@ -335,10 +346,11 @@ export class SelectorClass<
 
   toString() {
     if (!this.arguments || !Object.keys(this.arguments).length) {
+      this._hasMacro = false
       return this.target
     }
 
-    const result: (readonly [string, string])[] = []
+    const result: (readonly [string, string | ResolvedNBT])[] = []
 
     const args = { ...this.arguments }
 
@@ -349,7 +361,13 @@ export class SelectorClass<
       // Parse potentially multiple nbt
       nbt: (nbt: RootNBT | RootNBT[]) => {
         const nbts = Array.isArray(nbt) ? nbt : [nbt]
-        result.push(...nbts.map((nbt_) => ['nbt', nbtStringifier(nbt_)] as const))
+        for (const nbt_ of nbts) {
+          const resolved = nbtResolver(nbt_)
+          if (resolved.containsMacro) {
+            this._hasMacro = true
+          }
+          result.push(['nbt', resolved] as const)
+        }
       },
 
       // Parse advancements

package/src/variables/Sleep.ts

@@ -69,6 +69,8 @@ export class SleepClass extends AwaitNode {
 
       const timer = new ObjectiveClass(core.pack, name.replace(':', '.'), 'dummy', undefined, { creator: 'sandstone' })
 
+      core.pack.registerNewObjective(timer)
+
       execute.store.result(timer('@s')).run.time.query('gametime')
 
       timer('@s').add(Duration)
@@ -102,14 +104,4 @@ export class SleepClass extends AwaitNode {
 
     core.awaitNodes.add(this)
   }
-
-  promise() {
-    return {
-      // oxlint-disable-next-line no-thenable
-      then: (async (onfullfilled?: () => void | Promise<void>) => {
-        await onfullfilled?.()
-        return this
-      }) as any,
-    }
-  }
 }

package/src/variables/Trigger.ts

@@ -3,8 +3,6 @@ import { _RawMCFunctionClass, type MCFunctionClass } from 'sandstone/core/resour
 import { ObjectiveClass } from './Objective'
 import type { Score } from './Score'
 
-const checkTriggers: Record<number, MCFunctionClass<undefined, undefined>> = {}
-
 export type TriggerHandler =
   | (() => any)
   | MCFunctionClass<undefined, undefined>
@@ -26,14 +24,14 @@ export class TriggerClass<HANDLE extends TriggerHandler> {
 
     registerNewObjective(this.objective)
 
-    if (!checkTriggers[pollingEvery]) {
-      checkTriggers[pollingEvery] = MCFunction(`triggers/check/${pollingEvery}`, {
+    if (!sandstoneCore.checkTriggers[pollingEvery]) {
+      sandstoneCore.checkTriggers[pollingEvery] = MCFunction(`triggers/check/${pollingEvery}`, {
         creator: 'sandstone',
         runEvery: pollingEvery,
       })
     }
 
-    checkTriggers[pollingEvery].push(() => {
+    sandstoneCore.checkTriggers[pollingEvery].push(() => {
       commands.execute.as(`@a[scores={${name}=1..}]`).run(() => {
         const score = this.objective('@s')
 

package/src/variables/nbt/NBTs.ts

@@ -128,7 +128,7 @@ export class NotNBT<VALUE extends RootNBT = RootNBT> extends NBTClass {
     this.nbt = nbt
   }
 
-  [util.inspect.custom] = () => `!${nbtStringifier(this.nbt)}`
+  [util.inspect.custom] = () => `!${nbtResolver(this.nbt)}`
 }
 
 export type NBTAllNumberClasses<Range extends NBTRange = {}> = NBTLong<Range> | NBTShort<Range> | NBTByte<Range> | NBTFloat<Range> | NBTDouble<Range> | NBTInt<Range>
@@ -161,7 +161,7 @@ function customNumber<T extends number | number[], C extends NBTSimpleClasses>(
 function dynamicNBT(template: TemplateStringsArray, ...args: unknown[]): NBTObject {
   const mixedArgs = template.flatMap((s, i) => [s, args[i]]).slice(0, -1) // Remove the last argument, which will always be undefined
   const result = mixedArgs
-    .map((element: any) => (element instanceof NBTClass ? nbtStringifier(element) : element.toString()))
+    .map((element: any) => (element instanceof NBTClass ? nbtResolver(element).toString() : element.toString()))
     .join('')
 
   return parseNBT(NBT, result)
@@ -440,25 +440,45 @@ export const NBT: NBTInterface = makeCallable(
 
     not: (nbt: RootNBT) => new NotNBT(nbt),
 
-    stringify: (nbt: NBTObject) => nbtStringifier(nbt),
+    stringify: (nbt: NBTObject) => nbtResolver(nbt).toString(),
 
     parse: (nbt: string) => parseNBT(NBT, nbt),
   },
   dynamicNBT,
 )
 
-export const nbtStringifier = (nbt: NBTObject | MacroArgument): string => {
+/**
+ * The resolved result of converting a Sandstone NBT value (which may contain
+ * live `MacroArgument` references) into the final Minecraft SNBT string.
+ *
+ * Carries macro information up to `CommandNode.getValue()` so commands with
+ * `$(...)` substitutions can be flagged as macro commands (prefixed with `$`)
+ * even when the macro originated from inside a nested value rather than as
+ * a top-level arg object.
+ */
+export class ResolvedNBT {
+  constructor(
+    public readonly value: string,
+    public readonly containsMacro: boolean,
+  ) {}
+
+  toString(): string {
+    return this.value
+  }
+}
+
+const resolve = (nbt: NBTObject | MacroArgument): ResolvedNBT => {
   if (nbt === null || nbt === undefined) {
     throw new Error('Nullish nbt values are not allowed')
   }
   if (typeof nbt === 'number') {
     // We have a double, integers are now required to be defined with NBT.int
-    return `${nbt}d`
+    return new ResolvedNBT(`${nbt}d`, false)
   }
 
   if (typeof nbt === 'boolean') {
     // We have a boolean
-    return nbt.toString()
+    return new ResolvedNBT(nbt.toString(), false)
   }
 
   if (typeof nbt === 'string') {
@@ -476,22 +496,29 @@ export const nbtStringifier = (nbt: NBTObject | MacroArgument): string => {
     })
 
     if (inspectedStr[0] === '`') {
-      return JSON.stringify(nbt)
+      return new ResolvedNBT(JSON.stringify(nbt), false)
     }
 
-    return inspectedStr
+    return new ResolvedNBT(inspectedStr, false)
   }
 
   if (Array.isArray(nbt)) {
     // We have an array
-    const itemsStr = nbt.map(nbtStringifier).join(',')
-    return `[${itemsStr}]`
+    let containsMacro = false
+    const itemsStr = nbt
+      .map((item) => {
+        const resolved = resolve(item)
+        if (resolved.containsMacro) containsMacro = true
+        return resolved.value
+      })
+      .join(',')
+    return new ResolvedNBT(`[${itemsStr}]`, containsMacro)
   }
 
   // We have an object
   if (nbt instanceof NBTClass) {
     // It's actually a "Minecraft Primitive", like 3b, and not an object
-    return nbt[util.inspect.custom]()
+    return new ResolvedNBT(nbt[util.inspect.custom](), false)
   }
 
   if (typeof nbt === 'object' || typeof nbt === 'function') {
@@ -503,32 +530,56 @@ export const nbtStringifier = (nbt: NBTObject | MacroArgument): string => {
       if (macro === '$()') {
         failedMacro = true
       } else {
-        return macro
+        return new ResolvedNBT(macro, true)
       }
     }
     if ('toNBT' in nbt) {
+      // toNBT itself may recurse through nbtResolver, so reuse its result.
       // @ts-ignore
-      return nbt.toNBT()
+      const toNbtResult = nbt.toNBT()
+      if (toNbtResult instanceof ResolvedNBT) {
+        return toNbtResult
+      }
+      return new ResolvedNBT(String(toNbtResult), false)
     } else if (failedMacro) {
-      throw new Error('[nbtStringifier] A macro variable NBT insertion was attempted in an mcfunction without macros defined.')
+      throw new Error('[nbtResolver] A macro variable NBT insertion was attempted in an mcfunction without macros defined.')
     }
     if (typeof nbt === 'function') {
       /* @ts-ignore */
-      throw new Error(`[nbtStringifier] This should never happen. A function or callable instance (${nbt.constructor?.name}) without toNBT was passed in as an NBT value.`)
+      throw new Error(`[nbtResolver] This should never happen. A function or callable instance (${nbt.constructor?.name}) without toNBT was passed in as an NBT value.`)
     }
     if (nbt.constructor.name !== 'Object') {
       if ('toString' in nbt) {
-        return `${toString}`
+        return new ResolvedNBT(`${toString}`, false)
       } else {
         /* @ts-ignore */
-        throw new Error(`[nbtStringifier] A ${nbt.constructor?.name} was passed in as an NBT value. Hint: define toNBT or toString if this was intentional`)
+        throw new Error(`[nbtResolver] A ${nbt.constructor?.name} was passed in as an NBT value. Hint: define toNBT or toString if this was intentional`)
       }
     }
   }
 
   // It's a real object.
+  let containsMacro = false
   const objectStr = Object.entries(nbt)
-    .map(([key, value]) => `${key}:${nbtStringifier(value as NBTObject)}`)
+    .map(([key, value]) => {
+      const resolved = resolve(value as NBTObject)
+      if (resolved.containsMacro) containsMacro = true
+      return `${key}:${resolved.value}`
+    })
     .join(',')
-  return `{${objectStr}}`
+  return new ResolvedNBT(`{${objectStr}}`, containsMacro)
 }
+
+/**
+ * Resolves a Sandstone NBT value into its Minecraft SNBT string form.
+ *
+ * Unlike the previous `nbtStringifier`, the result is a `ResolvedNBT` object
+ * that preserves whether the value contained `$(...)` macro substitutions.
+ * `CommandNode.getValue()` uses `containsMacro` to decide whether to emit the
+ * command as a macro command (prefixed with `$`).
+ *
+ * Callers that need a plain string (template literals, string concatenation)
+ * can rely on `ResolvedNBT`'s `toString()`, which is called automatically by
+ * JS coercion. To be explicit, call `.toString()` on the result.
+ */
+export const nbtResolver = (nbt: NBTObject | MacroArgument): ResolvedNBT => resolve(nbt)