sandstone 1.1.1 → 1.1.2

package/src/arguments/jsonTextComponent.ts

@@ -1,265 +1,9 @@
-import type { LiteralUnion } from 'sandstone/utils'
-import type { ComponentClass } from 'sandstone/variables/abstractClasses'
-import type { VectorClass } from 'sandstone/variables/Coordinates'
-import type { BASIC_COLORS } from './basics'
-import type { MultipleEntitiesArgument } from './selector'
+import { Text, TextObject, TextStyle } from './generated/util/text'
 
-export type JSONContentTypes = 'text' | 'translatable' | 'score' | 'selector' | 'keybind' | 'nbt'
+export type JSONContentTypes = NonNullable<TextObject['type']>
 
-// To be valid, a chat component must contain one content tag: text, translate, score, selector, keybind, or nbt.
-export type ContentTag<Type extends JSONContentTypes> = (Type extends 'text'
-  ? {
-      type?: 'text'
-      /** A string containing plain text to display directly. Can also be a number or boolean that is displayed directly. */
-      text: string | number | boolean
-    }
-  : Type extends 'translatable'
-    ? {
-        /** A translation identifier, to be displayed as the corresponding text in the player's selected language. */
-        translate: string
+export type FormattingTags = TextStyle
 
-        /** Optional. Depreciated. A list of raw JSON text component arguments to be inserted into slots in the translation text.  */
-        with?: ContentTag<JSONContentTypes>[]
+export type JSONTextComponent = Text
 
-        /** Optional. A raw JSON text component that will be used in place of a translation if it is missing */
-        fallback?: ContentTag<JSONContentTypes>
-      }
-    : Type extends 'score'
-      ? {
-          type?: 'score'
-          /**
-           * Displays a score holder's current score in an objective.
-           *
-           * Displays nothing if the given score holder or the given objective do not exist,
-           * or if the score holder is not tracked in the objective.
-           */
-          score: {
-            /**
-             * The name of the score holder whose score should be displayed.
-             * This can be a selector like @p or an explicit name.
-             */
-            name: MultipleEntitiesArgument<false>
-
-            /** The internal name of the objective to display the player's score in. */
-            objective: string
-
-            /** Optional. If present, this value is used regardless of what the score would have been. */
-            value?: number
-          }
-        }
-      : Type extends 'selector'
-        ? {
-            type?: 'selector'
-            /**
-             * An entity selector. Displayed as the name of the player or entity found by the selector.
-             *
-             * If more than one player or entity is found by the selector,
-             * their names are displayed in either the form "Name1 and Name2" or the form "Name1, Name2, Name3, and Name4".
-             */
-            selector: string
-
-            /** Optional, defaults to {"color": "gray", "text": ", "}. Used as the separator between different names, if the component selects multiple entities. */
-            separator?: JSONTextPrimitives | ContentTag<JSONContentTypes>
-          }
-        : Type extends 'keybind'
-          ? {
-              type?: 'keybind'
-              /**
-               * A keybind identifier, to be displayed as the name of the button that is currently bound to a certain action.
-               * For example, {"keybind": "key.inventory"} will display "e" if the player is using the default control scheme.
-               */
-              keybind: string
-            }
-          : Type extends 'nbt'
-            ? {
-                type?: 'nbt'
-                /**
-                 * The NBT path used for looking up NBT values from an entity, a block entity or an NBT storage.
-                 *
-                 * NBT strings display their contents.
-                 * Other NBT values are displayed as SNBT with no spacing or linebreaks.
-                 *
-                 * How values are displayed depends on the value of `interpret`.
-                 */
-                nbt: string
-
-                /**
-                 * Optional.
-                 * If true, the game will try to parse the text of each NBT value as a raw JSON text component.
-                 *
-                 * This usually only works if the value is an NBT string containing JSON, since JSON and SNBT are not compatible.
-                 *
-                 * If parsing fails, displays nothing.
-                 *
-                 * @default false
-                 */
-                interpret?: boolean
-              } & NBTTarget
-            : never) &
-  ChildrenTags &
-  FormattingTags &
-  InteractivityTags
-
-type NBTTarget =
-  | {
-      /**
-       * The coordinates of the block entity from which the NBT value is obtained.
-       * The coordinates can be absolute or relative.
-       */
-      block: string | VectorClass<[string, string, string]>
-    }
-  | {
-      /** The target selector for the entity or entities from which the NBT value is obtained. */
-      entity: MultipleEntitiesArgument<false>
-    }
-  | {
-      /** The namespaced ID of the command storage from which the NBT value is obtained */
-      storage: string
-    }
-
-type ChildrenTags = {
-  /**
-   * Optional. A list of child raw JSON text components to be displayed after this one.
-   *
-   * Child text components inherit all formatting and interactivity from the parent component,
-   * unless they explicitly override them.
-   */
-  extra?: (JSONTextPrimitives | ContentTag<JSONContentTypes>)[]
-}
-
-export type FormattingTags = {
-  /** Optional. The color to render the content in. */
-  color?: LiteralUnion<BASIC_COLORS>
-
-  /**
-   * Optional.
-   * The resource location of the font for this component in the resource pack within assets/<namespace>/font.
-   *
-   * @default "minecraft:default"
-   */
-  font?: string
-
-  /** Optional. Whether to render the content in bold. */
-  bold?: boolean
-
-  /**
-   * Optional. Whether to render the content in italics.
-   *
-   * Note that text which is italicized by default, such as custom item names,
-   * can be unitalicized by setting this to false.
-   */
-  italic?: boolean
-
-  /** Optional. Whether to underline the content. */
-  underlined?: boolean
-
-  /** Optional. Whether to strikethrough the content. */
-  strikethrough?: boolean
-
-  /** Optional. Whether to render the content obfuscated. */
-  obfuscated?: boolean
-}
-
-type InteractivityTags = {
-  /**
-   * Optional. When the text is shift-clicked by a player, this string is inserted in their chat input.
-   * It does not overwrite any existing text the player was writing. This only works in chat messages.
-   */
-  insertion?: string | number | boolean
-
-  /**
-   * Optional. Allows for events to occur when the player clicks on text.
-   * Only work in chat messages and written books, unless specified otherwise.
-   */
-  clickEvent?: {
-    /**
-     * The action to perform when clicked.
-     *
-     * Valid values are:
-     * - `open_url`: Opens `value` as a URL in the user's default web browser.
-     *
-     * - `open_file`: Opens the file at `value` on the user's computer. This is used in messages automatically generated
-     * by the game (e.g., on taking a screenshot) and cannot be used by players for security reasons.
-     *
-     * - `run_command`: Works in signs, but only on the root text component, not on any children. Activated by using the sign.
-     * In chat and written books, this has `value` entered in chat as though the player typed it themselves and pressed enter.
-     * This can be used to run commands, provided the player has the required permissions. Since they are being run from chat,
-     * commands must be prefixed with the usual `/` slash. In signs, the command is run by the server at the sign's location,
-     * with the player who used the sign as @s. Since they are run by the server, sign commands have the same permission level as a command block,
-     * instead of using the player's permission level, are not restricted by chat length limits, and do not need to be prefixed with a `/` slash.
-     *
-     * - `suggest_command`: Opens chat and fills in `value`. If a chat message was already being composed, it is overwritten.
-     *
-     * - `change_page`: Can only be used in written books. Changes to page `value` if that page exists.
-     *
-     * - `copy_to_clipboard`: Copies `value` to the clipboard.
-     */
-    action: 'open_url' | 'open_file' | 'run_command' | 'suggest_command' | 'change_page' | 'copy_to_clipboard'
-
-    /** The URL, file path, chat, command or book page used by the specified action. */
-    value: string
-  }
-
-  /** Optional. Allows for a tooltip to be displayed when the player hovers their mouse over text. */
-  hoverEvent?:
-    | {
-        /**
-         * The type of tooltip to show.
-         *
-         * Valid values are:
-         * - `show_text `: Shows a raw JSON text component.
-         * - `show_item `: Shows the tooltip of an item as if it was being hovering over it in an inventory.
-         * - `show_entity `: Shows an entity's name, type, and UUID. Used by `selector`.
-         */
-        action: 'show_text'
-
-        /**
-         * The formatting of this tag varies depending on the action.
-         *
-         * `show_text`: Another raw JSON text component. Can be any valid text component type: string, array, or object.
-         * Note that clickEvent and hoverEvent do not function within the tooltip.
-         * `show_item`: The item that should be displayed.
-         * `show_entity`: The entity that should be displayed.
-         */
-        contents: JSONTextPrimitives | ContentTag<JSONContentTypes>
-      }
-    | {
-        action: 'show_item'
-
-        /** The item that should be displayed. */
-        contents: {
-          /** The namespaced item ID. Present `minecraft:air` if invalid. */
-          id: string
-
-          /** Optional. Size of the item stack. */
-          count?: number
-
-          /** Optional. A string containing the serialized NBT of the additional information about the item. */
-          tag?: string
-        }
-      }
-    | {
-        action: 'show_entity'
-
-        /** The entity that should be displayed */
-        contents: {
-          /** Optional. Hidden if not present. A raw JSON text that is displayed as the name of the entity. */
-          name?: string
-
-          /** A string containing the type of the entity. Should be a namespaced entity ID. Present `minecraft:pig` if invalid. */
-          type: string
-
-          /** A string containing the UUID of the entity in the hyphenated hexadecimal format. Should be a valid UUID. */
-          id: string
-        }
-      }
-}
-
-export type JSONTextPrimitives = string | boolean | number | ComponentClass
-
-/*
- * A JSON text component, that can be displayed in several locations: in-game chat, books, signs, titles...
- *
- * Warning: Empty lists are not supported by the game, but typing this way is restrictive.
- */
-export type JSONTextComponent = JSONTextPrimitives | ContentTag<JSONContentTypes> | JSONTextComponent[]
+export type { TextObject }

package/src/arguments/nbt.ts

@@ -1,9 +1,34 @@
-import type { NBTClass } from 'sandstone/variables/nbt/NBTs'
+import type { TextObject } from './generated/util/text'
+import { TextComponentClass } from 'sandstone/variables'
+import type {
+  NBTByte,
+  NBTByteArray,
+  NBTClass,
+  NBTDouble,
+  NBTFloat,
+  NBTInt,
+  NBTIntArray,
+  NBTLong,
+  NBTLongArray,
+  NBTShort,
+} from 'sandstone/variables/nbt/NBTs'
 
 export interface NBTSerializable {
   toNBT(): string
 }
 
-export type NBTObject = string | number | boolean | URL | undefined | NBTSerializable | { [key: string]: NBTObject | undefined } | NBTObject[] | NBTClass
+export type NBTObject = string | number | boolean | URL | undefined | NBTSerializable | TextComponentClass | TextObject | { [key: string]: NBTObject | undefined } | NBTObject[] | NBTClass
 
-export type RootNBT = Record<string, NBTObject | undefined>
+export type RootNBT = Record<`${any}${string}`, NBTObject | undefined>
+
+/**
+ * Recursively walks a type, unioning Sandstone NBT primitive classes with their plain JSON equivalents
+ */
+export type MCDocToJSON<T> =
+  T extends NBTInt | NBTFloat | NBTDouble | NBTByte | NBTShort | NBTLong ? (number | T) :
+  T extends NBTIntArray | NBTLongArray | NBTByteArray ? (number | T)[] :
+  T extends (...args: any[]) => any ? T :
+  T extends NBTSerializable | TextComponentClass ? T :
+  T extends ReadonlyArray<infer U> ? Array<MCDocToJSON<U>> :
+  T extends object ? { [K in keyof T]: MCDocToJSON<T[K]> } :
+  T

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

@@ -168,7 +168,7 @@ export class SetBlockCommand<MACRO extends boolean> extends CommandArguments {
 export function blockStateStringifier(state: Record<string, string | number | boolean>) {
   let resultPairs: string[] = []
 
-  for (const [key, value] of Object.entries(Object.entries(state))) {
+  for (const [key, value] of Object.entries(state)) {
     resultPairs.push(`${key}=${value}`)
   }
   return `[${resultPairs.join(',')}]`

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

@@ -62,6 +62,8 @@ const isObjective = (arg: any): arg is ObjectiveClass => typeof arg === 'object'
 const isScore = (arg: any): arg is Score => typeof arg === 'object' && Object.hasOwn(arg, 'setDisplay')
 
 export class ExecuteCommandPart<MACRO extends boolean> extends CommandArguments<typeof ExecuteCommandNode> {
+  protected NodeType = ExecuteCommandNode
+
   /**
    * @internal
    */

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

@@ -1,4 +1,4 @@
-import type { BASIC_COLORS, JSONTextComponent, MultipleEntitiesArgument } from 'sandstone/arguments'
+import type { JSONTextComponent, MultipleEntitiesArgument, TextColor } from 'sandstone/arguments'
 import type { Macroable } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core/nodes'
 import { parseJSONText } from 'sandstone/variables/JSONTextComponentClass'
@@ -7,7 +7,7 @@ import { CommandArguments } from '../../helpers'
 
 interface TeamOptions {
   collisionRule: 'always' | 'never' | 'pushOtherTeams' | 'pushOwnTeam'
-  color: BASIC_COLORS
+  color: TextColor
   deathMessageVisibility: 'never' | 'hideForOtherTeams' | 'hideForOwnTeam' | 'always'
   friendlyFire: boolean
   nametagVisibility: 'never' | 'hideForOtherTeams' | 'hideForOwnTeam' | 'always'

package/src/commands/implementations/index.ts

@@ -5,7 +5,7 @@ export * from './block/fill'
 export * from './block/place'
 export * from './block/setblock'
 export * from './entity/attribute'
-export * from './entity/clear'
+export * from './player/clear'
 export * from './entity/damage'
 export * from './entity/effect'
 export * from './entity/enchant'

package/src/commands/implementations/player/bossbar.ts

@@ -1,4 +1,4 @@
-import type { BASIC_COLORS, JSONTextComponent, MultiplePlayersArgumentOf } from 'sandstone/arguments'
+import type { JSONTextComponent, MultiplePlayersArgumentOf, TextColor } from 'sandstone/arguments'
 import type { Macroable } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core/nodes'
 import type { LiteralUnion } from 'sandstone/utils'
@@ -91,7 +91,7 @@ export class BossBarSetCommand<MACRO extends boolean> extends CommandArguments {
    *
    * @param color The new color.
    */
-  color = (color: Macroable<LiteralUnion<BASIC_COLORS>, MACRO>) => this.finalCommand(['color', color])
+  color = (color: Macroable<LiteralUnion<TextColor>, MACRO>) => this.finalCommand(['color', color])
 
   /**
    * Set the boss bar's maximum value.

package/src/commands/implementations/player/dialog.ts

@@ -1,4 +1,4 @@
-import type { MultiplePlayersArgument } from 'sandstone/arguments'
+import type { MCDocToJSON, MultiplePlayersArgument } from 'sandstone/arguments'
 import type { Dialog } from 'sandstone/arguments/generated/data/dialog'
 import type { DIALOGS } from 'sandstone/arguments/generated/_registry/dialogs'
 import type { DialogClass, Macroable } from 'sandstone/core'
@@ -27,11 +27,11 @@ export class DialogCommand<MACRO extends boolean> extends CommandArguments {
    */
   show(
     targets: Macroable<MultiplePlayersArgument<MACRO>, MACRO>,
-    dialog: Macroable<DIALOGS | DialogClass | Dialog, MACRO>,
+    dialog: Macroable<DIALOGS | DialogClass | MCDocToJSON<Dialog>, MACRO>,
   ): FinalCommandOutput {
     const dialogArg = typeof dialog === 'string' || dialog instanceof ResourceClass
       ? dialog
-      : nbtResolver(dialog as Dialog)
+      : nbtResolver(dialog as any)
     return this.finalCommand(['show', targetParser(targets), dialogArg])
   }
 

package/src/commands/implementations/player/give.ts

@@ -1,4 +1,4 @@
-import type { MultiplePlayersArgumentOf, RootNBT, SymbolDataComponent } from 'sandstone/arguments'
+import type { MCDocToJSON, MultiplePlayersArgumentOf, RootNBT, SymbolDataComponent } from 'sandstone/arguments'
 import type { Macroable } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core'
 import { nbtResolver, targetParser } from 'sandstone/variables'
@@ -99,7 +99,7 @@ export class GiveCommand<MACRO extends boolean> extends CommandArguments {
   give<T extends string>(
     targets: Macroable<MultiplePlayersArgumentOf<MACRO, T>, MACRO>,
     item: Macroable<Registry['minecraft:item'], MACRO>,
-    components: Macroable<MemberModifiers<SymbolDataComponent>, MACRO>,
+    components: Macroable<MemberModifiers<MCDocToJSON<SymbolDataComponent>>, MACRO>,
     count?: Macroable<number, MACRO>,
   ): FinalCommandOutput
 

package/src/commands/implementations/player/waypoint.ts

@@ -1,4 +1,4 @@
-import type { BASIC_COLORS, SingleEntityArgumentOf } from 'sandstone/arguments'
+import type { SingleEntityArgumentOf, TextColor } from 'sandstone/arguments'
 import type { Macroable, WaypointStyleClass } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core/nodes'
 import { targetParser } from 'sandstone/variables/parsers'
@@ -39,7 +39,7 @@ export class WaypointModifyArguments<MACRO extends boolean> extends CommandArgum
    *
    * @param name One of the 16 standard Minecraft color names.
    */
-  color(name: Macroable<Exclude<BASIC_COLORS, 'reset'>, MACRO>): FinalCommandOutput
+  color(name: Macroable<Exclude<TextColor, 'reset'>, MACRO>): FinalCommandOutput
 
   /**
    * Resets the waypoint color to its default (randomly chosen by the game, or the entity's team color).
@@ -67,7 +67,7 @@ export class WaypointModifyArguments<MACRO extends boolean> extends CommandArgum
    */
   color(type: 'rgb%', color: [number, number, number]): FinalCommandOutput
 
-  color(type: Macroable<BASIC_COLORS | 'hex' | 'rgb' | 'rgb%', MACRO>, color?: Macroable<number | string | [number, number, number], MACRO>) {
+  color(type: Macroable<TextColor | 'reset' | 'hex' | 'rgb' | 'rgb%', MACRO>, color?: Macroable<number | string | [number, number, number], MACRO>) {
     if (type === 'hex') {
       if (typeof color !== 'number') {
         return this.finalCommand(['color', 'hex', color])

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

@@ -5,14 +5,18 @@ import type {
   RootNBT,
   EntitySlotSelector,
   ContainerSlotSelector,
+  MCDocToJSON,
+  SymbolDataComponent,
+  NBTObject,
 } from 'sandstone/arguments'
 import type { ItemModifierClass, Macroable } from 'sandstone/core'
 import { CommandNode } from 'sandstone/core/nodes'
-import type { LiteralUnion } from 'sandstone/utils'
+import type { LiteralUnion, MemberModifiers } from 'sandstone/utils'
 import { nbtResolver } from 'sandstone/variables'
 import { coordinatesParser, targetParser } from 'sandstone/variables/parsers'
 import type { FinalCommandOutput } from '../../helpers'
 import { CommandArguments } from '../../helpers'
+import { componentPatchStringifier } from '../player/give';
 
 export class ItemCommandNode extends CommandNode {
   command = 'item' as const
@@ -34,17 +38,17 @@ export class ItemSourceCommand<MACRO extends boolean> extends CommandArguments {
    */
   with(
     item: Macroable<Registry['minecraft:item'], MACRO>,
-    nbt: Macroable<RootNBT, MACRO>,
+    components: Macroable<MemberModifiers<MCDocToJSON<SymbolDataComponent>>, MACRO>,
     count: Macroable<number, MACRO>,
   ): FinalCommandOutput
 
   with(
     item: Macroable<Registry['minecraft:item'], MACRO>,
-    countOrNBT?: Macroable<number | RootNBT, MACRO>,
+    countOrNBT?: Macroable<number | MemberModifiers<MCDocToJSON<SymbolDataComponent>>, MACRO>,
     count?: Macroable<number, MACRO>,
   ) {
     if (typeof countOrNBT === 'object') {
-      return this.finalCommand(['with', `${item}${nbtResolver(countOrNBT)}`, count])
+      return this.finalCommand(['with', `${item}${componentPatchStringifier(countOrNBT as any)}`, count])
     }
     return this.finalCommand(['with', item, countOrNBT])
   }
@@ -58,7 +62,7 @@ export class ItemSourceCommand<MACRO extends boolean> extends CommandArguments {
     block: (
       pos: Macroable<Coordinates<MACRO>, MACRO>,
       slot: Macroable<LiteralUnion<ContainerSlotSelector>, MACRO>,
-      modifier?: Macroable<string | ItemModifierClass, MACRO>,
+      modifier?: Macroable<`${any}${string}` | ItemModifierClass, MACRO>,
     ) => this.finalCommand(['from', 'block', pos, slot, modifier]),
 
     /**
@@ -69,7 +73,7 @@ export class ItemSourceCommand<MACRO extends boolean> extends CommandArguments {
     entity: (
       targets: Macroable<MultipleEntitiesArgument<MACRO>, MACRO>,
       slot: Macroable<LiteralUnion<EntitySlotSelector>, MACRO>,
-      modifier?: Macroable<string | ItemModifierClass, MACRO>,
+      modifier?: Macroable<`${any}${string}` | ItemModifierClass, MACRO>,
     ) => this.finalCommand(['from', 'entity', targetParser(targets), slot, modifier]),
   }
 }
@@ -95,7 +99,7 @@ export class ItemCommand<MACRO extends boolean> extends CommandArguments {
     block: (
       pos: Macroable<Coordinates<MACRO>, MACRO>,
       slot: Macroable<LiteralUnion<ContainerSlotSelector>, MACRO>,
-      modifier: Macroable<string | ItemModifierClass, MACRO>,
+      modifier: Macroable<`${any}${string}` | ItemModifierClass, MACRO>,
     ) => this.finalCommand(['modify', 'block', coordinatesParser(pos), slot, modifier]),
 
     /**
@@ -106,7 +110,7 @@ export class ItemCommand<MACRO extends boolean> extends CommandArguments {
     entity: (
       targets: Macroable<MultipleEntitiesArgument<MACRO>, MACRO>,
       slot: Macroable<LiteralUnion<EntitySlotSelector>, MACRO>,
-      modifier: Macroable<string | ItemModifierClass, MACRO>,
+      modifier: Macroable<`${any}${string}` | ItemModifierClass, MACRO>,
     ) => this.finalCommand(['modify', 'entity', targetParser(targets), slot, modifier]),
   }
 

package/src/core/Macro.ts

@@ -100,6 +100,8 @@ export class DataPointPickClass extends MacroArgument {
 }
 
 export class ConditionalDataPointPickClass extends DataPointPickClass implements ConditionClass {
+  declare readonly __conditionClassBrand: true
+
   /**
    * @internal
    */

package/src/core/mcmeta.ts

@@ -3,7 +3,7 @@ import AdmZip from 'adm-zip'
 import fs from 'fs-extra'
 import lodash from 'lodash'
 import { getSandstoneContext } from 'sandstone/context'
-import { fetch, safeWrite } from 'sandstone/utils'
+import { safeWrite } from 'sandstone/utils'
 
 export type MCMetaBranches = 'assets' | 'atlas' | 'data' | 'registries' | 'summary'
 
@@ -46,7 +46,7 @@ export class MCMetaCache {
     this.version = manifest.version
 
     const getZip = async (branch: string) =>
-      new AdmZip(await (await fetch(`https://github.com${this.base}archive/refs/heads/${branch}.zip`)).buffer())
+      new AdmZip(Buffer.from(await (await fetch(`https://github.com${this.base}archive/refs/heads/${branch}.zip`)).arrayBuffer()))
 
     if (!(await fs.pathExists(this.lockFile))) {
       if (manifest.files.length > 10) {
@@ -58,12 +58,18 @@ export class MCMetaCache {
         for await (const [file, text] of Object.entries(manifest.files)) {
           const _path = file.split('/')
 
-          let contents: Buffer | string = await new Promise((res) => {
-            archives[_path[0]].readFileAsync(_path.slice(1).join('/'), (data) => res(data as Buffer))
+          let contents: Buffer<ArrayBufferLike> | string = await new Promise((res, rej) => {
+            archives[_path[0]].readFileAsync(_path.slice(1).join('/'), (data) => {
+              if (data === null) {
+                rej('[mcmeta] adm-zip got null')
+              } else {
+                res(data)
+              }
+            })
           })
 
           if (text) {
-            contents = contents.toString('utf-8')
+            contents = contents.toString()
           }
 
           await safeWrite(path.join(this.path, file), contents as any)
@@ -103,12 +109,18 @@ export class MCMetaCache {
           for await (const [file, text] of Object.entries(manifest.files)) {
             const _path = file.split('/')
 
-            let contents: Buffer | string = await new Promise((res) => {
-              archives[_path[0]].readFileAsync(_path.slice(1).join('/'), (data) => res(data as Buffer))
+            let contents: Buffer<ArrayBufferLike> | string = await new Promise((res, rej) => {
+              archives[_path[0]].readFileAsync(_path.slice(1).join('/'), (data) => {
+                if (data === null) {
+                  rej('[mcmeta] adm-zip got null')
+                } else {
+                  res(data)
+                }
+              })
             })
 
             if (text) {
-              contents = contents.toString('utf-8')
+              contents = contents.toString()
             }
 
             await safeWrite(path.join(this.path, file), contents as any)
@@ -139,12 +151,18 @@ export class MCMetaCache {
                 archives[branch] = await getZip(branch)
               }
 
-              let contents: Buffer | string = await new Promise((res) => {
-                archives[branch].readFileAsync(_path.slice(1).join('/'), (data) => res(data as Buffer))
+              let contents: Buffer<ArrayBufferLike> | string = await new Promise((res, rej) => {
+                archives[branch].readFileAsync(_path.slice(1).join('/'), (data) => {
+                  if (data === null) {
+                    rej('[mcmeta] adm-zip got null')
+                  } else {
+                    res(data)
+                  }
+                })
               })
 
               if (text) {
-                contents = contents.toString('utf-8')
+                contents = contents.toString()
               }
 
               await safeWrite(path.join(this.path, file), contents as any)
@@ -233,7 +251,7 @@ export class MCMetaCache {
 
     const req = await fetch(`https://raw.githubusercontent.com${this.base}${branch}/${relativePath}`)
 
-    const file = await (text ? req.text() : req.buffer())
+    const file = text ? await req.text() : Buffer.from(await req.arrayBuffer())
 
     const finalPath = path.join(this.path, fullPath)
 

package/src/core/resources/custom.ts

@@ -77,7 +77,7 @@ export abstract class CustomResourceClass extends ResourceClass<CustomResourceNo
     ).join('/')}`
   }
 
-  getValue(): string | Buffer | Promise<Buffer> {
+  getValue(): string | ArrayBuffer | Buffer | Promise<ArrayBuffer | Buffer | string> {
     throw new Error(`Custom Resource '${this.type}' getValue function is not defined!`)
   }
 

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

@@ -1,4 +1,4 @@
-import { RESOURCE_PATHS, type MultiplePlayersArgumentOf, type SymbolResource } from 'sandstone/arguments'
+import { type MCDocToJSON, RESOURCE_PATHS, type MultiplePlayersArgumentOf, type SymbolResource } from 'sandstone/arguments'
 import type { ConditionClass } from 'sandstone/variables'
 import { ContainerNode } from '../../nodes'
 import type { SandstoneCore } from '../../sandstoneCore'
@@ -19,16 +19,21 @@ export class AdvancementNode extends ContainerNode implements ResourceNode<Advan
   getValue = () => jsonStringify(this.resource.advancementJSON, this.resource._resourceType as keyof typeof RESOURCE_PATHS)
 }
 
-export type AdvancementClassArguments<AdvancementJSON extends SymbolResource['advancement'] | undefined = undefined> = {
+export type AdvancementClassArguments<AdvancementJSON extends MCDocToJSON<SymbolResource['advancement']> | undefined = undefined> = {
   /**
-   * The advancement's JSON.
+   * The advancement's JSON. NBT primitive classes (`NBTInt`, `NBTFloat`, ...)
+   * are deep-replaced with plain `number` (and `NBTIntArray` etc. with
+   * `number[]`) via `MCDocToJSON`, so you can write raw numeric literals
+   * instead of `NBT.int(5)`.
    */
   json: AdvancementJSON
 } & ResourceClassArguments<'default'>
 
-export class AdvancementClass<AdvancementJSON extends SymbolResource['advancement'] | undefined = undefined>
+export class AdvancementClass<AdvancementJSON extends MCDocToJSON<SymbolResource['advancement']> | undefined = undefined>
   extends ResourceClass<AdvancementNode>
   implements ConditionClass {
+  declare readonly __conditionClassBrand: true
+
   static readonly resourceType = 'advancement'
 
   public advancementJSON: AdvancementClassArguments<AdvancementJSON>['json']