@spyglassmc/java-edition 0.3.8 → 0.3.9

package/lib/mcfunction/tree/patch.js

@@ -116,44 +116,38 @@ export function getPatch(release) {
             },
             data: {
                 children: {
-                    get: DataSource,
-                    merge: DataTarget,
-                    modify: {
-                        children: {
-                            block: {
-                                children: {
-                                    targetPos: {
-                                        children: {
-                                            targetPath: DataModifyOperation,
-                                        },
-                                    },
-                                },
-                            },
-                            entity: {
+                    get: getDataPatch('target', 'path'),
+                    merge: getDataPatch('target', 'nbt', {
+                        isMerge: true,
+                        vaultAccessType: 1 /* SymbolAccessType.Write */,
+                    }),
+                    modify: getDataPatch('target', 'targetPath', {
+                        nbtAccessType: 1 /* SymbolAccessType.Write */,
+                        vaultAccessType: 1 /* SymbolAccessType.Write */,
+                        children: (type) => ({
+                            append: getDataModifySource(type, {
+                                isListIndex: true,
+                            }),
+                            insert: {
                                 children: {
-                                    target: {
-                                        children: {
-                                            targetPath: DataModifyOperation,
-                                        },
-                                    },
-                                },
-                            },
-                            storage: {
-                                children: {
-                                    target: {
-                                        properties: {
-                                            category: 'storage',
-                                            accessType: 1 /* SymbolAccessType.Write */,
-                                        },
-                                        children: {
-                                            targetPath: DataModifyOperation,
-                                        },
-                                    },
+                                    index: getDataModifySource(type, {
+                                        isListIndex: true,
+                                    }),
                                 },
                             },
-                        },
-                    },
-                    remove: DataSource,
+                            merge: getDataModifySource(type, {
+                                isMerge: true,
+                            }),
+                            prepend: getDataModifySource(type, {
+                                isListIndex: true,
+                            }),
+                            set: getDataModifySource(type),
+                        }),
+                    }),
+                    remove: getDataPatch('target', 'path', {
+                        nbtAccessType: 1 /* SymbolAccessType.Write */,
+                        vaultAccessType: 1 /* SymbolAccessType.Write */,
+                    }),
                 },
             },
             debug: {
@@ -174,8 +168,29 @@ export function getPatch(release) {
                     unless: ExecuteCondition,
                 },
             },
+            function: {
+                children: {
+                    name: {
+                        ...(ReleaseVersion.cmp(release, '1.20.2') >= 0
+                            ? {
+                                children: {
+                                    // Added in 23w31a (1.20.2, pack format 16)
+                                    arguments: {
+                                        properties: {
+                                            dispatcher: 'minecraft:macro_function',
+                                            dispatchedBy: 'name',
+                                        },
+                                    },
+                                    with: getDataPatch('source', 'path'),
+                                },
+                            }
+                            : {}),
+                    },
+                },
+            },
             ...(ReleaseVersion.cmp(release, '1.17') >= 0
                 ? {
+                    // Added in 20w46a (1.17, pack format 7)
                     item: {
                         children: {
                             replace: {
@@ -329,6 +344,7 @@ export function getPatch(release) {
             },
             ...(ReleaseVersion.cmp(release, '1.18') >= 0
                 ? {
+                    // Added in 21w37a (1.18, pack format 8)
                     jfr: {
                         permission: 4,
                     },
@@ -340,13 +356,17 @@ export function getPatch(release) {
             list: {
                 permission: 0,
             },
-            ...(ReleaseVersion.cmp(release, '1.16') >= 0
+            ...(ReleaseVersion.isBetween(release, '1.16', '1.19')
                 ? {
+                    // Added in 20w06a (1.16, pack format 5)
+                    // Removed in 22w19a (1.19, pack format 10)
                     locatebiome: {
                         children: {
                             biome: {
                                 properties: {
                                     category: 'worldgen/biome',
+                                    // Allowed in 1.18.2-pre1 (1.18.2, pack format 9)
+                                    allowTag: ReleaseVersion.cmp(release, '1.18.2') >= 0,
                                 },
                             },
                         },
@@ -421,6 +441,7 @@ export function getPatch(release) {
             },
             ...(ReleaseVersion.cmp(release, '1.17') >= 0
                 ? {
+                    // Added in 1.17 Pre-release 1 (1.17, pack format 7)
                     perf: {
                         permission: 4,
                     },
@@ -428,18 +449,33 @@ export function getPatch(release) {
                 : {}),
             ...(ReleaseVersion.cmp(release, '1.19') >= 0
                 ? {
+                    // Added in 22w18a (1.19, pack format 10)
                     place: {
                         children: {
+                            jigsaw: {
+                                children: {
+                                    pool: {
+                                        children: {
+                                            target: {
+                                                properties: {
+                                                    category: 'jigsaw_block_name',
+                                                    allowUnknown: true,
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
                             template: {
                                 children: {
                                     template: {
                                         properties: {
-                                            category: 'structure'
-                                        }
-                                    }
-                                }
-                            }
-                        }
+                                            category: 'structure',
+                                        },
+                                    },
+                                },
+                            },
+                        },
                     },
                 }
                 : {}),
@@ -447,6 +483,53 @@ export function getPatch(release) {
             publish: {
                 permission: 4,
             },
+            ...(ReleaseVersion.cmp(release, '1.20.2') >= 0
+                ? {
+                    // Added in 23w31a (1.20.2, pack format 16)
+                    random: {
+                        children: {
+                            reset: {
+                                children: {
+                                    sequence: {
+                                        properties: {
+                                            category: 'random_sequence',
+                                            allowUnknown: true,
+                                        },
+                                    },
+                                },
+                            },
+                            roll: {
+                                children: {
+                                    range: {
+                                        children: {
+                                            sequence: {
+                                                properties: {
+                                                    category: 'random_sequence',
+                                                    allowUnknown: true,
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                            value: {
+                                children: {
+                                    range: {
+                                        children: {
+                                            sequence: {
+                                                properties: {
+                                                    category: 'random_sequence',
+                                                    allowUnknown: true,
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                }
+                : {}),
             recipe: {
                 children: {
                     give: RecipeTargets,
@@ -462,6 +545,18 @@ export function getPatch(release) {
             'save-on': {
                 permission: 4,
             },
+            schedule: {
+                children: {
+                    clear: {
+                        children: {
+                            function: {
+                                parser: 'minecraft:function',
+                                properties: undefined,
+                            },
+                        },
+                    },
+                },
+            },
             scoreboard: {
                 children: {
                     objectives: {
@@ -514,6 +609,24 @@ export function getPatch(release) {
                     },
                 },
             },
+            summon: {
+                children: {
+                    entity: {
+                        children: {
+                            pos: {
+                                children: {
+                                    nbt: {
+                                        properties: {
+                                            dispatcher: 'minecraft:entity',
+                                            dispatchedBy: 'entity',
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
             tag: {
                 children: {
                     targets: {
@@ -522,6 +635,9 @@ export function getPatch(release) {
                                 children: {
                                     name: {
                                         parser: 'spyglassmc:tag',
+                                        properties: {
+                                            usageType: 'definition',
+                                        },
                                     },
                                 },
                             },
@@ -584,8 +700,9 @@ export function getPatch(release) {
             tell: {
                 permission: 0,
             },
-            ...(ReleaseVersion.cmp(release, '1.20.2') >= 0
+            ...(ReleaseVersion.cmp(release, '1.20.3') >= 0
                 ? {
+                    // Added in 23w43a (1.20.3, pack format 22)
                     tick: {
                         permission: 3,
                     },
@@ -594,6 +711,14 @@ export function getPatch(release) {
             tm: {
                 permission: 0,
             },
+            ...(ReleaseVersion.cmp(release, '1.20.5') >= 0
+                ? {
+                    // Added in 24w04a (1.20.5, pack format 29)
+                    transfer: {
+                        permission: 3,
+                    },
+                }
+                : {}),
             trigger: {
                 permission: 0,
                 children: {
@@ -658,54 +783,124 @@ const AdvancementTargets = Object.freeze({
         },
     },
 });
-const DataSource = Object.freeze({
-    children: {
-        storage: {
-            children: {
-                source: {
-                    properties: {
-                        category: 'storage',
+/**
+ * Return the command tree patch for anything related to data sources as used in
+ * `data`, `execute if` and `execute store` commands.
+ *
+ * A **vault** refers to a block, an entity, or a storage that contains NBT data.
+ *
+ * e.g., in a syntax like
+ * `block <targetPos>|entity <target>|storage <target>) <targetPath>`, the
+ * `<targetPos>` and `<target>` arguments identify a vault, and the
+ * `<targetPath>` argument is an NBT path that points to data in the vault.
+ *
+ * @param vaultKey Key of the argument identifying a vault. This argument should
+ *                 be a vec3, an entity, or a storage resource location.
+ * @param nbtKey Key of the argument containing an NBT tag or an NBT path.
+ * @param nbtAccessType Access type for the NBT argument. This is only
+ *                      meaningful for NBT paths and should be enforced by the
+ *                      NBT path checker.
+ *                      Note this usually match `vaultAccessType`. The only case
+ *                      where they don't match is in `data merge`, where the
+ *                      vault is being written to while the NBT argument is
+ *                      being read from.
+ *                      @default {@link SymbolAccessType.Read}
+ * @param vaultAccessType Access type for the vault. This is only meaningful for
+ *                        storage vaults and should be enforced by the resource
+ *                        location checker.
+ *                        @see {@link nbtAccessType}
+ *                        @default {@link SymbolAccessType.Read}
+ * @param children Optional patch for children after the NBT argument.
+ */
+function getDataPatch(vaultKey, nbtKey, { children, isPredicate = false, isMerge = false, nbtAccessType = 0 /* SymbolAccessType.Read */, vaultAccessType = 0 /* SymbolAccessType.Read */, } = {}) {
+    return Object.freeze({
+        children: {
+            block: {
+                children: {
+                    [`${vaultKey}Pos`]: {
+                        children: {
+                            [nbtKey]: {
+                                properties: {
+                                    dispatcher: 'minecraft:block',
+                                    dispatchedBy: `${vaultKey}Pos`,
+                                    accessType: nbtAccessType,
+                                    isPredicate,
+                                    isMerge,
+                                },
+                                ...children ? { children: children('block') } : {},
+                            },
+                        },
                     },
                 },
             },
-        },
-    },
-});
-const DataTarget = Object.freeze({
-    children: {
-        storage: {
-            children: {
-                target: {
-                    properties: {
-                        category: 'storage',
-                        accessType: 1 /* SymbolAccessType.Write */,
+            entity: {
+                children: {
+                    [vaultKey]: {
+                        children: {
+                            [nbtKey]: {
+                                properties: {
+                                    dispatcher: 'minecraft:entity',
+                                    dispatchedBy: vaultKey,
+                                    accessType: nbtAccessType,
+                                    isPredicate,
+                                    isMerge,
+                                },
+                                ...children ? { children: children('entity') } : {},
+                            },
+                        },
+                    },
+                },
+            },
+            storage: {
+                children: {
+                    [vaultKey]: {
+                        properties: {
+                            category: 'storage',
+                            accessType: vaultAccessType,
+                            usageType: 'definition',
+                        },
+                        children: {
+                            [nbtKey]: {
+                                properties: {
+                                    dispatcher: 'minecraft:storage',
+                                    dispatchedBy: vaultKey,
+                                    accessType: nbtAccessType,
+                                    isPredicate,
+                                    isMerge,
+                                },
+                                ...children ? { children: children('storage') } : {},
+                            },
+                        },
                     },
                 },
             },
         },
-    },
-});
-const DataModifySource = Object.freeze({
-    children: {
-        from: DataSource,
-    },
-});
-const DataModifyOperation = Object.freeze({
+    });
+}
+const getDataModifySource = (type, { isMerge = false, isListIndex = false, } = {}) => Object.freeze({
     children: {
-        append: DataModifySource,
-        insert: {
+        from: getDataPatch('source', 'sourcePath'),
+        string: getDataPatch('source', 'sourcePath'),
+        value: {
             children: {
-                index: DataModifySource,
+                value: {
+                    properties: {
+                        dispatcher: `minecraft:${type}`,
+                        dispatchedBy: type === 'block' ? 'targetPos' : 'target',
+                        indexedBy: 'targetPath',
+                        isMerge,
+                        isListIndex,
+                    },
+                },
             },
         },
-        merge: DataModifySource,
-        prepend: DataModifySource,
-        set: DataModifySource,
     },
 });
 const ExecuteCondition = Object.freeze({
     children: {
-        data: DataSource,
+        data: getDataPatch('source', 'path', {
+            isPredicate: true,
+        }),
         predicate: {
             children: {
                 predicate: {
@@ -719,7 +914,11 @@ const ExecuteCondition = Object.freeze({
 });
 const ExecuteStoreTarget = Object.freeze({
     children: {
-        ...DataTarget.children,
+        ...getDataPatch('target', 'path', {
+            nbtAccessType: 1 /* SymbolAccessType.Write */,
+            vaultAccessType: 1 /* SymbolAccessType.Write */,
+        })
+            .children,
         bossbar: {
             children: {
                 id: {
@@ -757,6 +956,9 @@ const LootSource = Object.freeze({
 const ObjectiveWriteTargets = Object.freeze({
     children: {
         targets: {
+            properties: {
+                usageType: 'definition',
+            },
             children: {
                 objective: {
                     properties: {

package/lib/mcfunction/tree/patchValidator.d.ts

@@ -0,0 +1,7 @@
+import type * as core from '@spyglassmc/core';
+import type { RootTreeNode } from '@spyglassmc/mcfunction';
+/**
+ * Validate that parsers requiring patches have been patched in the tree.
+ */
+export declare function validatePatchedTree(tree: RootTreeNode, logger: core.Logger): void;
+//# sourceMappingURL=patchValidator.d.ts.map

package/lib/mcfunction/tree/patchValidator.js

@@ -0,0 +1,25 @@
+/**
+ * A set of parsers that must be patched with a `properties` field.
+ */
+const PatchRequiredParsers = new Set([
+    'minecraft:nbt_compound_tag',
+    'minecraft:nbt_path',
+    'minecraft:nbt_tag',
+    'minecraft:resource_location',
+    'minecraft:uuid',
+]);
+/**
+ * Validate that parsers requiring patches have been patched in the tree.
+ */
+export function validatePatchedTree(tree, logger) {
+    walk(tree, []);
+    function walk(node, path) {
+        if (node.type === 'argument' && PatchRequiredParsers.has(node.parser) && !node.properties) {
+            logger.warn(`[validatePatchedTree] Patch required: ${node.parser} at ${path.join('.')}`);
+        }
+        for (const [key, value] of Object.entries(node.children ?? {})) {
+            walk(value, [...path, key]);
+        }
+    }
+}
+//# sourceMappingURL=patchValidator.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spyglassmc/java-edition",
-  "version": "0.3.8",
+  "version": "0.3.9",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -17,16 +17,15 @@
     "release:dry": "npm publish --dry-run"
   },
   "dependencies": {
-    "@spyglassmc/core": "0.4.5",
-    "@spyglassmc/json": "0.3.7",
-    "@spyglassmc/locales": "0.3.5",
-    "@spyglassmc/mcfunction": "0.2.7",
-    "@spyglassmc/mcdoc": "0.3.8",
-    "@spyglassmc/nbt": "0.3.8"
+    "@spyglassmc/core": "0.4.6",
+    "@spyglassmc/json": "0.3.8",
+    "@spyglassmc/locales": "0.3.6",
+    "@spyglassmc/mcfunction": "0.2.8",
+    "@spyglassmc/mcdoc": "0.3.9",
+    "@spyglassmc/nbt": "0.3.9"
   },
   "devDependencies": {
-    "fast-glob": "^3.2.5",
-    "vanilla-datapack-data": "SPGoding/vanilla-datapack#634cc1bf99c37bdb99cde101713f55abbbbe5e95"
+    "fast-glob": "^3.2.5"
   },
   "publishConfig": {
     "access": "public"