JSPrismarine

API reference / @jsprismarine/packs

@jsprismarine/packs ​

Loads a pack stack, Bedrock packs and Java datapacks together, into one set of per-registry definitions.

A PackStack is an ordered list of pack sources. The Bedrock kinds are a loose pack folder, a .mcpack or .mcaddon archive, and a folder of brarchive layers the way BDS ships the vanilla behavior pack; the Java kind is a datapack folder or zip. load(stack) returns a Definitions object, which maps identifier to winning parsed definition for each registry, plus a diagnostics report. The Bedrock registries (blocks, items, entities, loot tables, trade tables, spawn rules, recipes, biomes, features, feature rules, item catalog) resolve by identifier: a later pack wins and its definition replaces the earlier one whole. The Java registries (lootTablesJava, recipesJava, advancements, tags, enchantments, damageTypes, predicates, itemModifiers, functions, dimensionTypes, dimensions, worldgen, keyed by namespaced id, from the 26.3 singular directory names) resolve by Java's rule: a later pack wins per file, except tags, whose values merge across packs unless a later file sets replace.

dimensionTypes holds data/<namespace>/dimension_type/ and dimensions holds data/<namespace>/dimension/, the level stems a datapack adds or overrides. worldgen is one registry for the seventeen data/<namespace>/worldgen/<kind>/ directories in WORLDGEN_REGISTRY_KINDS: the fourteen terrain kinds the data-driven generator reads (biome, block_state_provider, carver, density_function, feature, material_condition, material_rule, noise, noise_settings, placed_feature, processor_list, structure, structure_set, template_pool) plus world_preset, flat_level_generator_preset and multi_noise_biome_source_parameter_list. Its identifier is <kind>/<namespace>:<path>, the shape tag ids use, so data/minecraft/worldgen/noise_settings/overworld.json is noise_settings/minecraft:overworld and worldgenIdentifier('world_preset', 'minecraft:normal') spells the key for a preset. A worldgen file passes the structural validator with any JSON root, because a density function may be a bare constant. The .nbt structure templates sit under data/<namespace>/structure/, which is not a worldgen directory; they do not route and stay with the generator's own template loader. The identifier report does not walk the three registries: the worldgen parsers resolve their references, and the report's field-name heuristic would see only a fraction of them.

functions is the one registry whose data is not parsed JSON. A .mcfunction is text, so its definition carries the file verbatim and @jsprismarine/mcfunction compiles it; a validator is never asked about one, because the line format is not a JSON shape.

A folder of brarchive layers holds whole packs, not one. BDS keeps chemistry, the editor, the server script libraries and four experimental toggles in the same behavior_packs folder as the vanilla layers, and a world composes only the ones it turns on. uuids says which, by the header UUID that is a pack's identity: each folder's manifest is read first, the folders of the named packs compose in version order, and the rest are never opened. Omitting uuids composes every pack in the folder, which is what a caller pointing at a folder it assembled itself wants. A UUID no folder declares is reported as source.unknown-pack, so a renamed identity says so instead of composing nothing.

load opens only the Bedrock files a registry owns. A pack folder holds much else - the composed vanilla pack ships 1311 .nbt structures, a 3 MB level.dat and its textures beside 2588 readable files - and a path no registry routes could never reach the result anyway. expandSource, the reader underneath, still returns a pack whole by default and takes a PackFileFilter for a caller that wants less.

typescript
import { VANILLA_BEHAVIOR_PACK_UUID, load, reportIdentifiers } from '@jsprismarine/packs';

const { definitions, diagnostics } = load([
    { kind: 'brarchiveLayers', path: 'bds/behavior_packs', uuids: [VANILLA_BEHAVIOR_PACK_UUID] },
    { kind: 'archive', path: 'my-addon.mcaddon' },
    { kind: 'directory', path: 'worlds/world/behavior_packs/overrides' },
    { kind: 'datapack', path: 'worlds/world/datapacks/gameplay-tweaks' }
]);

definitions.entities.get('minecraft:zombie');
definitions.lootTablesJava.get('minecraft:blocks/stone');

// Every Java identifier the loaded datapacks reference, for the mapping layer.
const referenced = reportIdentifiers(definitions);

The Java side targets data pack format 121.0 (Java 26.3) exactly. pack.mcmeta parses in both the current min_format/max_format form and the legacy single pack_format. A pack whose range misses 121.0 is reported and still loaded, so a strict load rejects it while a normal load keeps going.

A declared overlay directory is never content on its own: it leaves the base view whether or not its range applies. The overlays whose range covers 121.0 then apply in declaration order, each overriding whole files, so a later entry wins over an earlier one and every entry wins over the base. Within one pack an overlay replaces the base file outright, tags included, because merging is what happens between packs. A declared overlay holding no files is reported as a warning, since a misspelled directory name otherwise does nothing in silence.

Between packs, each registry composes by its own merge mode, Java's three: override takes the last pack that has the file, tags concatenates values and clears what came before whenever a pack sets replace, and assign merges key by key. MERGE_MODES holds the mode per registry and mergeJavaDefinition applies it. Every 26.3 data registry but tags overrides; assign is the mode Java gives its language files, which live in a resource pack.

Caching an immutable prefix ​

load can read a composed leading prefix from one V8 cache file and apply the remaining sources on every call. Pass cache with the prefix length, a file path, a fingerprint for mutable source contents, and a stable key for the validator. The cache key also includes the resolved prefix paths and the installed @jsprismarine/packs version. A changed key rebuilds and replaces the cache; a corrupt file emits a warning, then rebuilds from the sources. Strict-mode errors are checked after the live suffix has been composed, so a later pack can still supersede a prefix file.

The server uses this for its pinned Bedrock, overlay, and Java vanilla sources. Its overlay fingerprint includes each file's relative path and contents. World and plugin packs remain after that prefix and are read on every build.

Datapack definitions reference Java identifiers (items in loot entries, blocks in predicates, tag members); reportIdentifiers walks the loaded definitions and resolves each reference. Two things answer. An injectable IdentifierResolver takes the Bedrock side, and its default marks everything unknown; @jsprismarine/mapping is the implementation that fills it. What the resolver does not know falls back to the loaded stack itself, which closes a #tag whose tag file it carries and a reference into a registry a datapack fills, such as one loot table calling another. Those stay Java-shaped inside the server, so there is nothing to translate. Each entry says which answered, and names the pack and the file the reference came from.

The one field name 26.3 reuses is id, which spells an item stack, a damage type tag entry, a mob effect instance, a block state and an attribute modifier's own name. Which registry it points into is read from the keys beside it rather than from the name.

Behind the interface: manifest validation against the documented schema, a lenient JSON parser (comments and trailing commas, which vanilla trade tables use), format_version dispatch, a brarchive reader, a zip reader for .mcpack/.mcaddon, and the Bedrock filter grammar as the vanilla files write it. That means the string form, the integer subject, operator and domain encoding the 1.26 serializer writes, a group map carrying more than one combinator (read as an all_of over its clauses), a combinator holding one test instead of an array, and the legacy shorthand that names the test in the key, as the skeleton's {"other_with_families": "lightning"} does.

Validation has two layers. structuralValidator, the default, checks required keys and container types per registry and parses every filters key with the filter grammar. bedrockSchemaValidator checks a definition against Mojang's own JSON Schema for its registry and format_version. composeValidators joins them, and validator in the load options takes the result:

typescript
import { bedrockSchemaValidator, composeValidators, readBedrockSchemas, structuralValidator } from '@jsprismarine/packs';

const validator = composeValidators(structuralValidator, bedrockSchemaValidator(readBedrockSchemas(samplesCheckout)));

The schemas are read off disk rather than bundled, because bedrock-samples/LICENSE.md reserves all rights; pnpm --filter @jsprismarine/bedrock-data run fetch:sources puts a checkout in the cache. A file picks its schema by the engine's own rule, the same version or the closest one that is not greater, and a file older than every published schema checks against none. Mojang publishes a root document for entities, items, blocks, biomes, spawn rules and the crafting catalog; recipes, loot tables, trade tables, features and feature rules have none and keep the structural checks alone.

One repair is applied to the schemas as they load: every oneOf reads as anyOf. Mojang's generator writes a variant union as oneOf, which JSON Schema reads as "exactly one", and the variants overlap. Filter Group Map is "type": "object" with no required key, so it matches every object and a plain filter test matches two arms at once; Block Descriptor lists the same $ref as two of its three arms. Read literally, the published schemas reject 347 files of the vanilla behavior pack, all of them valid. Read as anyOf, the pack validates clean and the arms stay checked.

The Java half checks against SpyglassMC/vanilla-mcdoc through @spyglassmc/mcdoc, from @jsprismarine/packs/mcdocValidator:

typescript
import { composeValidators, structuralValidator } from '@jsprismarine/packs';
import { createMcdocValidator } from '@jsprismarine/packs/mcdocValidator';

const validator = composeValidators(structuralValidator, await createMcdocValidator({ root: mcdocCheckout }));

Construction is asynchronous because binding the schema modules is; the validator it returns is synchronous, so load stays synchronous. vanilla-mcdoc gates fields by release with #[since=] and #[until=], so the release decides what the checker accepts: the 26.3 vanilla datapack reports one finding at 26.3 and thousands at 26.1. Checking needs no network and no registry contents. Structure, keys, types, enums, unions, dispatch on type and the release gating all work from a local checkout; what a local run cannot answer is whether an #[id=(registry=...)] reference names something that exists, which is reportIdentifiers' question rather than this one's.

A vanilla-mcdoc finding is a warning by default, where a bedrock-samples finding is an error. The asymmetry is the provenance: Mojang's schemas describe Mojang's data, while vanilla-mcdoc is a community reconstruction that trails Mojang's releases. At 26.3 it rejects recipe/map_extending.json, which vanilla ships with "result": {} where the schema wants an id, and dropping a shipped vanilla recipe over that is worse than reporting it. Pass severity: 'error' for the stricter reading.

The four @spyglassmc packages are optional peer dependencies and mcdocValidator is not re-exported from the package index, because they pull 91 transitive packages that the eleven workspace packages importing the loader have no use for. Install them to use the validator.

Unknown keys load anyway and are reported once per pack; strict: true turns an error into a PackLoadError, and a warning never fails a load.

Repeats of the same pack, code and message collapse into one diagnostic, so a pattern that holds for a whole pack costs one line of the report rather than one per file. A collapsed diagnostic carries occurrences, the number of files it covers, and paths, the first five of them, so the report still leads to the files.

A file counts as superseded only when a later pack with a valid manifest provides the same path. A superseded file in a registry keyed by its definition identifier is still parsed: another layer can put a different identifier in the same file. A superseded file in a path-addressed registry is skipped, because its path is its identifier and the later file fully replaces it. As a result, invalid JSON and validation diagnostics from skipped loot tables, trade tables, and item catalogs are no longer reported. Other superseded files that fail to parse are reported as warnings, since they cannot reach the composed result. The shipped vanilla layers need this for content-addressed entities: two layers carry an entities/npc.json that patches a saved pack rather than defining an entity, and a later layer carries the real one. The Java side has no such rule, because its tags merge across packs instead of replacing one another.

To measure a directory stack's load time and how many routed files the loader parses, build the package and pass its pack directories in stack order:

sh
pnpm --filter @jsprismarine/packs build
pnpm --filter @jsprismarine/packs run bench:path-addressed -- path/to/base-pack path/to/override-pack

Classes ​

Interfaces ​

BedrockSchemaSet ​

Defined in: packages/packs/src/bedrockSchemas.ts:35

The schemas read off disk, indexed the two ways the validator needs them.

Properties ​

byId ​

readonly byId: ReadonlyMap<string, Readonly<Record<string, unknown>>>

Defined in: packages/packs/src/bedrockSchemas.ts:37

Every schema by its $id, which is its path under json_schemas with spaces percent-encoded.

versionsByDocument ​

readonly versionsByDocument: ReadonlyMap<string, readonly DocumentVersion[]>

Defined in: packages/packs/src/bedrockSchemas.ts:43

The format-version directories that hold a given document, oldest first. Keyed by the document's path with the version directory removed, such as server/entity/ActorDocument.json.

BedrockSchemaValidatorOptions ​

Defined in: packages/packs/src/bedrockSchemaValidator.ts:89

Options for bedrockSchemaValidator.

Properties ​

limit? ​

optional limit?: number

Defined in: packages/packs/src/bedrockSchemaValidator.ts:97

How many violations one file reports before the rest are summarized. One malformed union arm can produce hundreds of Ajv errors, and the first few name the field. Defaults to 10.

severity? ​

optional severity?: DiagnosticSeverity

Defined in: packages/packs/src/bedrockSchemaValidator.ts:91

The severity a schema violation reports at. Defaults to error.

DatapackSource ​

Defined in: packages/packs/src/sources.ts:58

A Java datapack: a folder or zip with pack.mcmeta and data/ at its root. It fills the Java registries, where a later pack wins per file except tags, which merge.

Properties ​

kind ​

kind: "datapack"

Defined in: packages/packs/src/sources.ts:59

path ​

path: string

Defined in: packages/packs/src/sources.ts:60

Definition ​

Defined in: packages/packs/src/load.ts:19

One winning definition after the stack is composed.

Properties ​

data ​

data: unknown

Defined in: packages/packs/src/load.ts:30

The parsed definition, replaced whole by a later pack, never merged.

formatVersion? ​

optional formatVersion?: FormatVersion

Defined in: packages/packs/src/load.ts:28

The file's parsed format_version, when it declares one.

identifier ​

identifier: string

Defined in: packages/packs/src/load.ts:21

The identifier the definition is registered under; a pack-relative path for the path-addressed registries.

pack ​

pack: string

Defined in: packages/packs/src/load.ts:24

The name of the pack the winning definition came from.

path ​

path: string

Defined in: packages/packs/src/load.ts:26

The pack-relative path of the file.

registry ​

registry: "blocks" | "items" | "entities" | "lootTables" | "tradeTables" | "spawnRules" | "recipes" | "biomes" | "features" | "featureRules" | "itemCatalog" | "lootTablesJava" | "recipesJava" | "advancements" | "tags" | "blockTransformers" | "enchantments" | "damageTypes" | "predicates" | "itemModifiers" | "functions" | "dimensionTypes" | "dimensions" | "worldgen"

Defined in: packages/packs/src/load.ts:22

DefinitionFile ​

Defined in: packages/packs/src/validation.ts:15

A definition file as handed to a validator, before composition.

Properties ​

data ​

data: unknown

Defined in: packages/packs/src/validation.ts:19

path ​

path: string

Defined in: packages/packs/src/validation.ts:18

The pack-relative path of the file.

registry ​

registry: "blocks" | "items" | "entities" | "lootTables" | "tradeTables" | "spawnRules" | "recipes" | "biomes" | "features" | "featureRules" | "itemCatalog" | "lootTablesJava" | "recipesJava" | "advancements" | "tags" | "blockTransformers" | "enchantments" | "damageTypes" | "predicates" | "itemModifiers" | "functions" | "dimensionTypes" | "dimensions" | "worldgen"

Defined in: packages/packs/src/validation.ts:16

Diagnostic ​

Defined in: packages/packs/src/diagnostics.ts:5

One finding reported while loading a pack stack.

Properties ​

code ​

code: string

Defined in: packages/packs/src/diagnostics.ts:8

A stable machine-readable code, such as manifest.invalid or definition.unknown-key.

message ​

message: string

Defined in: packages/packs/src/diagnostics.ts:13

occurrences? ​

optional occurrences?: number

Defined in: packages/packs/src/diagnostics.ts:15

How many files the finding covers. Set only on a collapsed diagnostic, so one file reports no count.

pack ​

pack: string

Defined in: packages/packs/src/diagnostics.ts:10

The name of the pack the finding belongs to, or its source path before the manifest is read.

path? ​

optional path?: string

Defined in: packages/packs/src/diagnostics.ts:12

The file within the pack, when the finding concerns one file; the first file when several share the finding.

paths? ​

optional paths?: readonly string[]

Defined in: packages/packs/src/diagnostics.ts:17

The first COLLAPSED_PATH_LIMIT files the finding covers, in report order. Set with occurrences.

severity ​

severity: DiagnosticSeverity

Defined in: packages/packs/src/diagnostics.ts:6

DocumentVersion ​

Defined in: packages/packs/src/bedrockSchemas.ts:27

One format-version directory that holds a given document.

Properties ​

id ​

id: string

Defined in: packages/packs/src/bedrockSchemas.ts:31

The $id of the document in that directory.

version ​

version: FormatVersion

Defined in: packages/packs/src/bedrockSchemas.ts:29

The parsed directory name, such as 1.26.50.

FilterGroup ​

Defined in: packages/packs/src/filters.ts:86

A normalized combinator over nested filters.

Properties ​

combinator ​

combinator: "all_of" | "any_of" | "none_of"

Defined in: packages/packs/src/filters.ts:88

filters ​

filters: Filter[]

Defined in: packages/packs/src/filters.ts:89

kind ​

kind: "group"

Defined in: packages/packs/src/filters.ts:87

FilterTest ​

Defined in: packages/packs/src/filters.ts:68

One normalized filter test.

Properties ​

domain? ​

optional domain?: string | number | boolean

Defined in: packages/packs/src/filters.ts:81

Extra context for a few tests, such as the equipment slot for has_equipment. The schema types it like value, and the 1.26 serializer writes the slot as an integer in the piglin's files, so it stays as written rather than being forced to a name.

kind ​

kind: "test"

Defined in: packages/packs/src/filters.ts:69

operator ​

operator: FilterOperator

Defined in: packages/packs/src/filters.ts:74

Defaults to == when the file writes none.

subject ​

subject: "self" | "other" | "player" | "target" | "parent" | "baby" | "block" | "damager" | "holder" | "item"

Defined in: packages/packs/src/filters.ts:72

Defaults to self when the file writes none.

test ​

test: string

Defined in: packages/packs/src/filters.ts:70

value? ​

optional value?: string | number | boolean

Defined in: packages/packs/src/filters.ts:82

IdentifierResolver ​

Defined in: packages/packs/src/identifiers.ts:44

Resolves Java identifiers per registry. @jsprismarine/mapping implements this seam; this package only defines it.

A resolver is asked about plain identifiers only. Tag references resolve against the loaded tags, which the resolver cannot see, so reportIdentifiers answers those itself.

Methods ​

resolve() ​

resolve(registry, javaId): IdentifierResolution

Defined in: packages/packs/src/identifiers.ts:51

Resolves one referenced identifier.

Parameters ​
registry ​

string

The Java registry the reference points into, such as item or block.

javaId ​

string

The namespaced id; tag references keep their # prefix.

Returns ​

IdentifierResolution

JavaRoute ​

Defined in: packages/packs/src/javaRegistries.ts:151

Where one datapack file routes: its registry and the id it registers under.

Properties ​

identifier ​

identifier: string

Defined in: packages/packs/src/javaRegistries.ts:158

The namespaced id. Tag ids carry the tagged registry as a prefix, such as block/minecraft:mineable/axe, because one datapack tags many registries and ids repeat across them.

registry ​

registry: "lootTablesJava" | "recipesJava" | "advancements" | "tags" | "blockTransformers" | "enchantments" | "damageTypes" | "predicates" | "itemModifiers" | "functions" | "dimensionTypes" | "dimensions" | "worldgen"

Defined in: packages/packs/src/javaRegistries.ts:152

taggedRegistry? ​

optional taggedRegistry?: string

Defined in: packages/packs/src/javaRegistries.ts:160

The registry a tag file tags, such as block or worldgen/biome. Only set for tags.

worldgenKind? ​

optional worldgenKind?: "biome" | "block_state_provider" | "carver" | "density_function" | "feature" | "flat_level_generator_preset" | "material_condition" | "material_rule" | "multi_noise_biome_source_parameter_list" | "noise" | "noise_settings" | "placed_feature" | "processor_list" | "structure" | "structure_set" | "template_pool" | "world_preset"

Defined in: packages/packs/src/javaRegistries.ts:162

The worldgen directory the file sits in, such as noise_settings. Only set for worldgen.

LoadOptions ​

Defined in: packages/packs/src/load.ts:40

Options for load.

Properties ​

cache? ​

optional cache?: PrefixCacheOptions

Defined in: packages/packs/src/load.ts:46

Caches an immutable leading prefix as one V8 file, then composes later sources on every load.

strict? ​

optional strict?: boolean

Defined in: packages/packs/src/load.ts:42

Fail the load when an error is reported, instead of reporting and continuing. Warnings never fail it.

validator? ​

optional validator?: DefinitionValidator

Defined in: packages/packs/src/load.ts:44

Replaces the structural validator, so schema-based validation can take over.

LoadResult ​

Defined in: packages/packs/src/load.ts:50

What load returns: the composed definitions plus the full report.

Properties ​

definitions ​

definitions: Definitions

Defined in: packages/packs/src/load.ts:51

diagnostics ​

diagnostics: readonly Diagnostic[]

Defined in: packages/packs/src/load.ts:52

Manifest ​

Defined in: packages/packs/src/manifest.ts:28

A parsed and validated manifest.json.

Properties ​

dependencies ​

dependencies: ManifestDependency[]

Defined in: packages/packs/src/manifest.ts:32

formatVersion ​

formatVersion: number

Defined in: packages/packs/src/manifest.ts:29

header: ManifestHeader

Defined in: packages/packs/src/manifest.ts:30

modules ​

modules: ManifestModule[]

Defined in: packages/packs/src/manifest.ts:31

ManifestDependency ​

Defined in: packages/packs/src/manifest.ts:22

A dependency on another pack's header UUID.

Properties ​

uuid ​

uuid: string

Defined in: packages/packs/src/manifest.ts:23

version ​

version: FormatVersion

Defined in: packages/packs/src/manifest.ts:24

ManifestHeader ​

Defined in: packages/packs/src/manifest.ts:7

The identity block of a pack manifest.

Properties ​

minEngineVersion? ​

optional minEngineVersion?: FormatVersion

Defined in: packages/packs/src/manifest.ts:11

name ​

name: string

Defined in: packages/packs/src/manifest.ts:8

uuid ​

uuid: string

Defined in: packages/packs/src/manifest.ts:9

version ​

version: FormatVersion

Defined in: packages/packs/src/manifest.ts:10

ManifestModule ​

Defined in: packages/packs/src/manifest.ts:15

One module entry of a pack manifest.

Properties ​

type ​

type: string

Defined in: packages/packs/src/manifest.ts:16

uuid ​

uuid: string

Defined in: packages/packs/src/manifest.ts:17

version ​

version: FormatVersion

Defined in: packages/packs/src/manifest.ts:18

McmetaParseResult ​

Defined in: packages/packs/src/mcmeta.ts:109

What parseMcmeta returns; mcmeta is undefined when the file is unusable.

Properties ​

diagnostics ​

diagnostics: Diagnostic[]

Defined in: packages/packs/src/mcmeta.ts:111

mcmeta? ​

optional mcmeta?: PackMcmeta

Defined in: packages/packs/src/mcmeta.ts:110

PackFiles ​

Defined in: packages/packs/src/sources.ts:73

One pack's files, flattened: brarchive containers are already expanded.

Properties ​

files ​

files: Map<string, Uint8Array<ArrayBufferLike>>

Defined in: packages/packs/src/sources.ts:77

File bytes by pack-relative path with / separators.

origin ​

origin: string

Defined in: packages/packs/src/sources.ts:75

Where the pack came from, used in diagnostics until the manifest names it.

PackFormatRange ​

Defined in: packages/packs/src/mcmeta.ts:18

An inclusive range of pack formats a pack or overlay supports.

Properties ​

max ​

max: PackFormat

Defined in: packages/packs/src/mcmeta.ts:24

The newest supported format. A max_format declared as a bare major reads as that whole major, so the minor here is Number.MAX_SAFE_INTEGER.

min ​

min: PackFormat

Defined in: packages/packs/src/mcmeta.ts:19

PackMcmeta ​

Defined in: packages/packs/src/mcmeta.ts:34

A parsed pack.mcmeta.

Properties ​

description? ​

optional description?: unknown

Defined in: packages/packs/src/mcmeta.ts:35

formats? ​

optional formats?: PackFormatRange

Defined in: packages/packs/src/mcmeta.ts:37

The supported format range, when the pack declares one.

overlays ​

overlays: PackOverlay[]

Defined in: packages/packs/src/mcmeta.ts:39

Overlay entries in declaration order; a later entry wins over an earlier one.

PackOverlay ​

Defined in: packages/packs/src/mcmeta.ts:28

One overlay directory with the format range it applies to.

Properties ​

directory ​

directory: string

Defined in: packages/packs/src/mcmeta.ts:29

formats ​

formats: PackFormatRange

Defined in: packages/packs/src/mcmeta.ts:30

PrefixCacheOptions ​

Defined in: packages/packs/src/prefixCache.ts:15

Identifies the vanilla source prefix to cache while the rest of the stack stays live.

Properties ​

filePath ​

readonly filePath: string

Defined in: packages/packs/src/prefixCache.ts:17

File that holds the serialized prefix. The loader replaces it when the key changes.

fingerprint ​

readonly fingerprint: string

Defined in: packages/packs/src/prefixCache.ts:21

Hash of mutable overlay contents and any other caller-owned cache inputs.

prefixLength ​

readonly prefixLength: number

Defined in: packages/packs/src/prefixCache.ts:19

Number of leading stack sources that make up the immutable prefix.

validatorKey ​

readonly validatorKey: string

Defined in: packages/packs/src/prefixCache.ts:23

Stable identifier for the validator used to build the cached definitions.

ReferencedIdentifier ​

Defined in: packages/packs/src/identifiers.ts:65

One referenced Java identifier with how it resolves and how often it appears.

Properties ​

id ​

id: string

Defined in: packages/packs/src/identifiers.ts:69

The namespaced id, normalized to carry a namespace; tag references keep their #.

pack ​

pack: string

Defined in: packages/packs/src/identifiers.ts:74

The pack holding the first definition that references the id, in report order.

path ​

path: string

Defined in: packages/packs/src/identifiers.ts:76

That definition's pack-relative path.

references ​

references: number

Defined in: packages/packs/src/identifiers.ts:78

How many identifier-valued fields across the loaded definitions reference this id.

registry ​

registry: string

Defined in: packages/packs/src/identifiers.ts:67

The Java registry the reference points into, such as item or worldgen/biome.

resolution ​

resolution: IdentifierResolution

Defined in: packages/packs/src/identifiers.ts:70

source ​

source: IdentifierSource

Defined in: packages/packs/src/identifiers.ts:72

What answered: the loaded pack stack, or the injected resolver.

TagData ​

Defined in: packages/packs/src/datapack.ts:27

A tag file's shape after merging across the stack.

Properties ​

replace ​

replace: boolean

Defined in: packages/packs/src/datapack.ts:29

Whether any contributing pack set replace, discarding earlier values.

values ​

values: unknown[]

Defined in: packages/packs/src/datapack.ts:31

The merged entries in pack order: plain ids or { id, required } objects.

ValidationFinding ​

Defined in: packages/packs/src/validation.ts:8

One finding a validator reports about a single definition file.

Properties ​

code ​

code: string

Defined in: packages/packs/src/validation.ts:10

message ​

message: string

Defined in: packages/packs/src/validation.ts:11

severity ​

severity: DiagnosticSeverity

Defined in: packages/packs/src/validation.ts:9

ZipBudget ​

Defined in: packages/packs/src/zip.ts:33

How many more bytes the archives of one load may expand to. Hand the same budget to the readZip of an archive and of the archives nested in it, so nesting cannot multiply the allowance.

Properties ​

remaining ​

remaining: number

Defined in: packages/packs/src/zip.ts:34

ZipLimits ​

Defined in: packages/packs/src/zip.ts:44

Limits for one readZip.

Properties ​

budget? ​

optional budget?: ZipBudget

Defined in: packages/packs/src/zip.ts:48

What the read may spend, shared with nested reads; a fresh createZipBudget by default.

maxEntryBytes? ​

optional maxEntryBytes?: number

Defined in: packages/packs/src/zip.ts:46

The most one entry may expand to; MAX_ZIP_ENTRY_BYTES by default.

Type Aliases ​

BedrockPackSource ​

BedrockPackSource = { kind: "directory"; path: string; } | { kind: "archive"; path: string; } | { kind: "brarchiveLayers"; path: string; uuids?: readonly string[]; }

Defined in: packages/packs/src/sources.ts:25

A Bedrock pack source: definitions keyed by identifier, later pack wins whole.

Union Members ​

Type Literal ​

{ kind: "directory"; path: string; }

A loose pack folder with manifest.json at its root.

Type Literal ​

{ kind: "archive"; path: string; }

A .mcpack (one pack) or .mcaddon (several .mcpack members).

Type Literal ​

{ kind: "brarchiveLayers"; path: string; uuids?: readonly string[]; }

A folder of layered pack folders the way BDS ships vanilla: vanilla, vanilla_1.14, ... Each layer is a pack; layers apply in version order.

kind ​

kind: "brarchiveLayers"

path ​

path: string

uuids? ​

optional uuids?: readonly string[]

Which packs in the folder to compose, by header UUID. Every folder is a layer of some pack, so this selects whole packs rather than individual layers.

Every pack in the folder by default, which is what a caller pointing at a folder it assembled itself wants. BDS keeps several unrelated packs in one behavior_packs folder - chemistry, the editor and the experimental toggles beside vanilla - and a world composes only the ones it turns on, so a caller pointing at that folder says which. VANILLA_BEHAVIOR_PACK_UUID is the vanilla one.

BedrockSchema ​

BedrockSchema = Readonly<Record<string, unknown>>

Defined in: packages/packs/src/bedrockSchemas.ts:24

One schema document, keyed in a BedrockSchemaSet by its $id.

DefinitionRegistries ​

DefinitionRegistries = Record<RegistryId | JavaRegistryId, Map<string, Definition>>

Defined in: packages/packs/src/load.ts:37

The mutable registries the loaders fill while a stack composes.

DefinitionValidator ​

DefinitionValidator = (file) => ValidationFinding[]

Defined in: packages/packs/src/validation.ts:28

Validates one definition file. The loader ships a structural validator (structuralValidator) and accepts a replacement through its options, so schema-based validation can take over later without changing the load interface.

Parameters ​

file ​

DefinitionFile

Returns ​

ValidationFinding[]

Definitions ​

Definitions = Readonly<Record<RegistryId | JavaRegistryId, ReadonlyMap<string, Definition>>>

Defined in: packages/packs/src/load.ts:34

The composed result of a load: per registry, identifier to winning definition.

DiagnosticSeverity ​

DiagnosticSeverity = "error" | "warning"

Defined in: packages/packs/src/diagnostics.ts:2

How much a diagnostic matters: an error fails a strict load, a warning never does.

Filter ​

Filter = FilterTest | FilterGroup

Defined in: packages/packs/src/filters.ts:93

A parsed filter: one test or a combinator over nested filters.

FilterOperator ​

FilterOperator = "==" | "!=" | "<" | "<=" | ">" | ">="

Defined in: packages/packs/src/filters.ts:38

A comparison operator, normalized to the canonical spellings.

FilterSubject ​

FilterSubject = typeof FILTER_SUBJECTS[number]

Defined in: packages/packs/src/filters.ts:35

Whom a filter test reads.

FormatVersion ​

FormatVersion = readonly [number, number, number]

Defined in: packages/packs/src/formatVersion.ts:6

A parsed format_version, normalized to three numeric parts. Bedrock files write it as a dotted string such as "1.26.50" or "1.10", and manifests write versions as [1, 26, 50] arrays.

IdentifierResolution ​

IdentifierResolution = "known" | "loss" | "unknown"

Defined in: packages/packs/src/identifiers.ts:34

How one Java identifier resolves to this runtime: known reaches Bedrock or resolves inside the pack stack, loss is on the reviewed loss allow list, unknown is neither.

IdentifierSource ​

IdentifierSource = "pack" | "resolver"

Defined in: packages/packs/src/identifiers.ts:58

What accounted for a referenced identifier.

JavaRegistryId ​

JavaRegistryId = typeof JAVA_REGISTRY_IDS[number]

Defined in: packages/packs/src/javaRegistries.ts:39

One Java-sourced registry.

MergeMode ​

MergeMode = "override" | "tags" | "assign"

Defined in: packages/packs/src/javaRegistries.ts:50

How a registry composes when more than one pack provides the same id. These are Java's three modes:

  • override: the last pack that has the file wins, whole.
  • tags: values concatenate in pack order, and a file that sets replace discards everything earlier.
  • assign: the objects merge key by key, a later pack's key winning.

PackFileFilter ​

PackFileFilter = (packPath) => boolean

Defined in: packages/packs/src/sources.ts:98

Which of a pack's files the caller wants the bytes of, by pack-relative path.

A pack folder holds far more than definitions - the composed vanilla Bedrock pack ships 1311 .nbt structures and a 3 MB .dat beside its 2588 readable files - and opening each of those costs a syscall pair and a buffer for content the caller then ignores. A caller that knows which paths it can use says so here and the rest are never opened.

manifest.json and the __brarchive/ containers are read whichever way this answers, because a pack cannot be expanded without them. The filter then applies to each container's members, so an archive's unwanted files are dropped too.

Parameters ​

packPath ​

string

Returns ​

boolean

PackFormat ​

PackFormat = readonly [number, number]

Defined in: packages/packs/src/mcmeta.ts:12

A Java data pack format: major and minor. The 26.3 data format is 121.0.

PackSource ​

PackSource = BedrockPackSource | DatapackSource

Defined in: packages/packs/src/sources.ts:67

One member of a PackStack. Later members win over earlier ones when both define the same identifier.

PackStack ​

PackStack = readonly PackSource[]

Defined in: packages/packs/src/sources.ts:70

The ordered list of pack sources a world runs.

RegistryId ​

RegistryId = typeof REGISTRY_IDS[number]

Defined in: packages/packs/src/registries.ts:26

One registry a loaded pack stack fills.

WorldgenRegistryKind ​

WorldgenRegistryKind = typeof WORLDGEN_REGISTRY_KINDS[number]

Defined in: packages/packs/src/javaRegistries.ts:132

One of WORLDGEN_REGISTRY_KINDS.

Variables ​

COLLAPSED_PATH_LIMIT ​

const COLLAPSED_PATH_LIMIT: 5 = 5

Defined in: packages/packs/src/diagnostics.ts:21

How many file paths a collapsed diagnostic names before it only counts.

DATA_PACK_FORMAT ​

const DATA_PACK_FORMAT: PackFormat

Defined in: packages/packs/src/mcmeta.ts:15

The data pack format this loader targets: 121.0, from the 26.3 version.json.

FILTER_SUBJECTS ​

const FILTER_SUBJECTS: readonly ["self", "other", "player", "target", "parent", "baby", "block", "damager", "holder", "item"]

Defined in: packages/packs/src/filters.ts:21

Whom a filter test reads, in the engine's int16 enum order.

FUNCTION_EXTENSION ​

const FUNCTION_EXTENSION: ".mcfunction" = '.mcfunction'

Defined in: packages/packs/src/javaRegistries.ts:77

The file extension of an mcfunction, which is the one datapack file that is not JSON.

JAVA_REGISTRY_DIRECTORIES ​

const JAVA_REGISTRY_DIRECTORIES: Readonly<Record<string, Exclude<JavaRegistryId, "tags" | "functions" | "worldgen">>>

Defined in: packages/packs/src/javaRegistries.ts:85

The 26.3 directory under data/<namespace>/ for each JSON registry. The directory name is also the name Java uses for the registry in a reference, so the identifier report reads this to turn loot_table into the registry holding the loot tables.

JAVA_REGISTRY_IDS ​

const JAVA_REGISTRY_IDS: readonly ["lootTablesJava", "recipesJava", "advancements", "tags", "blockTransformers", "enchantments", "damageTypes", "predicates", "itemModifiers", "functions", "dimensionTypes", "dimensions", "worldgen"]

Defined in: packages/packs/src/javaRegistries.ts:22

The Java-sourced registries a loaded datapack fills.

dimensionTypes and dimensions hold data/<ns>/dimension_type/ and data/<ns>/dimension/, keyed by namespaced id like the gameplay registries. worldgen is one composite registry for every data/<ns>/worldgen/<kind>/ directory in WORLDGEN_REGISTRY_KINDS; its identifier is <kind>/<namespace>:<path>, the shape tag ids already use, so worldgen/noise_settings/overworld.json registers as noise_settings/minecraft:overworld. One registry rather than seventeen keeps Definitions from growing a key per terrain kind, and the kind prefix is what a reference such as worldgen/structure resolves through.

MAX_ZIP_ENTRY_BYTES ​

const MAX_ZIP_ENTRY_BYTES: number

Defined in: packages/packs/src/zip.ts:20

The most one entry may expand to: 256 MiB. A Bedrock or Java pack file is far smaller; the largest member the server reads, the inner jar of a Java server jar, is under 30 MiB.

MAX_ZIP_TOTAL_BYTES ​

const MAX_ZIP_TOTAL_BYTES: number

Defined in: packages/packs/src/zip.ts:26

The most one load may expand to in all, nested archives included: 1 GiB. A Java server jar and the jar inside it come to under 150 MiB.

MERGE_MODES ​

const MERGE_MODES: Readonly<Record<JavaRegistryId, MergeMode>>

Defined in: packages/packs/src/javaRegistries.ts:57

The merge mode per registry. Every 26.3 data registry but tags overrides. assign is the mode Java gives its language files, which live in a resource pack rather than a datapack, so no registry here selects it yet.

REGISTRY_IDS ​

const REGISTRY_IDS: readonly ["blocks", "items", "entities", "lootTables", "tradeTables", "spawnRules", "recipes", "biomes", "features", "featureRules", "itemCatalog"]

Defined in: packages/packs/src/registries.ts:11

The registries a loaded pack stack fills.

SCHEMA_VALIDATED_REGISTRIES ​

const SCHEMA_VALIDATED_REGISTRIES: readonly ("blocks" | "items" | "entities" | "lootTables" | "tradeTables" | "spawnRules" | "recipes" | "biomes" | "features" | "featureRules" | "itemCatalog")[]

Defined in: packages/packs/src/bedrockSchemaValidator.ts:51

The registries a published root document covers, so a caller can report the gap.

VANILLA_BEHAVIOR_PACK_UUID ​

const VANILLA_BEHAVIOR_PACK_UUID: "fe9f8597-5454-481a-8730-8d070a8e2e58" = 'fe9f8597-5454-481a-8730-8d070a8e2e58'

Defined in: packages/packs/src/sources.ts:22

The header UUID of Mojang's vanilla Bedrock behavior pack.

A Bedrock pack's identity is its header UUID, not its folder name: every world references the packs it runs by UUID, so Mojang cannot change this one without orphaning every saved world, and it has been the same value across every release this project reads. The BDS behavior_packs folder keeps one folder per version of it - vanilla, vanilla_1.14, ... - and all of them carry this UUID, which is what makes them layers of one pack rather than packs of their own.

WORLDGEN_DIRECTORY ​

const WORLDGEN_DIRECTORY: "worldgen" = 'worldgen'

Defined in: packages/packs/src/javaRegistries.ts:101

The directory under data/<namespace>/ whose subdirectories are the worldgen registries.

WORLDGEN_REGISTRY_KINDS ​

const WORLDGEN_REGISTRY_KINDS: readonly ["biome", "block_state_provider", "carver", "density_function", "feature", "flat_level_generator_preset", "material_condition", "material_rule", "multi_noise_biome_source_parameter_list", "noise", "noise_settings", "placed_feature", "processor_list", "structure", "structure_set", "template_pool", "world_preset"]

Defined in: packages/packs/src/javaRegistries.ts:111

The data/<namespace>/worldgen/<kind>/ directories that route into the worldgen registry: the fourteen the data-driven generator reads, plus the three that describe a world's dimensions. Every file in them is JSON; the .nbt structure templates live under data/<namespace>/structure/, which is not a worldgen directory and stays with the generator's own template loader. A worldgen directory outside this list does not route.

structuralValidator ​

const structuralValidator: DefinitionValidator

Defined in: packages/packs/src/validation.ts:215

The structural validator this slice ships: required keys and container types per registry, for Bedrock and Java registries alike. Unknown root keys are warnings, so unrecognized content loads anyway; missing required structure is an error.

unknownResolver ​

const unknownResolver: IdentifierResolver

Defined in: packages/packs/src/identifiers.ts:55

The default resolver: every identifier is unknown, so the report lists them all.

Functions ​

bedrockSchemaValidator() ​

bedrockSchemaValidator(schemas, options?): DefinitionValidator

Defined in: packages/packs/src/bedrockSchemaValidator.ts:123

Builds a validator that checks each definition against the bedrock-samples schema for its registry and format_version. Compose it with structuralValidator through composeValidators: the schemas cover six registries and say nothing about the other five, and they do not close their objects, so unknown keys still need the structural check that reports them.

Parameters ​

schemas ​

BedrockSchemaSet

The schema set from readBedrockSchemas.

options? ​

BedrockSchemaValidatorOptions = {}

Returns ​

DefinitionValidator

A validator reporting one finding per schema violation.

comparePackFormats() ​

comparePackFormats(a, b): number

Defined in: packages/packs/src/mcmeta.ts:60

Compares two formats; negative when a is older than b, zero when equal.

Parameters ​

a ​

PackFormat

b ​

PackFormat

Returns ​

number

compareVersions() ​

compareVersions(a, b): number

Defined in: packages/packs/src/formatVersion.ts:35

Compares two versions; negative when a is older than b, zero when equal.

Parameters ​

a ​

FormatVersion

b ​

FormatVersion

Returns ​

number

composeValidators() ​

composeValidators(...validators): DefinitionValidator

Defined in: packages/packs/src/validation.ts:37

Runs validators in order over one file and concatenates their findings. This is how schema validation joins the structural checks rather than replacing them: the schemas cover part of each half and leave unknown keys open, so both layers have something to say about the same file.

Parameters ​

validators ​

...readonly DefinitionValidator[]

Returns ​

DefinitionValidator

coversFormat() ​

coversFormat(range, format): boolean

Defined in: packages/packs/src/mcmeta.ts:63

Whether the range covers the format, inclusive on both ends.

Parameters ​

range ​

PackFormatRange

format ​

PackFormat

Returns ​

boolean

createZipBudget() ​

createZipBudget(maxBytes?): ZipBudget

Defined in: packages/packs/src/zip.ts:41

A fresh budget for one load.

Parameters ​

maxBytes? ​

number = MAX_ZIP_TOTAL_BYTES

The most the load may expand to; MAX_ZIP_TOTAL_BYTES by default.

Returns ​

ZipBudget

expandSource() ​

expandSource(source, diagnostics, wanted?, budget?): PackFiles[]

Defined in: packages/packs/src/sources.ts:112

Expands one stack member into the packs it holds, in apply order. Unreadable members are reported rather than thrown so one bad pack does not hide the rest of the report.

Parameters ​

source ​

BedrockPackSource

diagnostics ​

Diagnostic[]

wanted? ​

PackFileFilter = EVERY_FILE

Which files to read; see PackFileFilter. Every file by default.

budget? ​

ZipBudget = ...

What an archive and the packs nested in it may expand to, together; a fresh createZipBudget by default.

Returns ​

PackFiles[]

formatToString() ​

formatToString(format): string

Defined in: packages/packs/src/mcmeta.ts:67

Renders a format as major.minor for diagnostics; an open minor renders as major.x.

Parameters ​

format ​

PackFormat

Returns ​

string

identifierForDefinition() ​

identifierForDefinition(registry, path, data): string | undefined

Defined in: packages/packs/src/registries.ts:92

The identifier a definition is registered under: description.identifier from the file's wrapper object where the registry has one, otherwise the pack-relative path. Features declare their wrapper per feature type, so any single minecraft:* wrapper key counts for them.

Parameters ​

registry ​

"blocks" | "items" | "entities" | "lootTables" | "tradeTables" | "spawnRules" | "recipes" | "biomes" | "features" | "featureRules" | "itemCatalog"

path ​

string

data ​

unknown

Returns ​

string | undefined

The identifier, or undefined when the file declares none.

isBrarchive() ​

isBrarchive(bytes): boolean

Defined in: packages/packs/src/brarchive.ts:29

Whether the bytes start with the brarchive magic number.

Parameters ​

bytes ​

Uint8Array

Returns ​

boolean

isPathAddressedRegistry() ​

isPathAddressedRegistry(registry): boolean

Defined in: packages/packs/src/registries.ts:81

Whether a registry identifies a definition by its pack-relative file path.

Parameters ​

registry ​

"blocks" | "items" | "entities" | "lootTables" | "tradeTables" | "spawnRules" | "recipes" | "biomes" | "features" | "featureRules" | "itemCatalog"

The registry a file routes to.

Returns ​

boolean

isWorldgenRegistryKind() ​

isWorldgenRegistryKind(kind): kind is "biome" | "block_state_provider" | "carver" | "density_function" | "feature" | "flat_level_generator_preset" | "material_condition" | "material_rule" | "multi_noise_biome_source_parameter_list" | "noise" | "noise_settings" | "placed_feature" | "processor_list" | "structure" | "structure_set" | "template_pool" | "world_preset"

Defined in: packages/packs/src/javaRegistries.ts:135

Whether a worldgen/ subdirectory name is one this loader routes.

Parameters ​

kind ​

string

Returns ​

kind is "biome" | "block_state_provider" | "carver" | "density_function" | "feature" | "flat_level_generator_preset" | "material_condition" | "material_rule" | "multi_noise_biome_source_parameter_list" | "noise" | "noise_settings" | "placed_feature" | "processor_list" | "structure" | "structure_set" | "template_pool" | "world_preset"

isZip() ​

isZip(bytes): boolean

Defined in: packages/packs/src/zip.ts:66

Whether the bytes start with a zip local file header.

Parameters ​

bytes ​

Uint8Array

Returns ​

boolean

load() ​

load(stack, options?): LoadResult

Defined in: packages/packs/src/load.ts:342

Loads a pack stack into one Definitions object plus a diagnostics report. Packs apply in stack order and a later pack wins by identifier: its definition replaces the earlier one whole, never merged. A pack whose manifest does not validate is skipped and reported.

A Bedrock file that does not parse is an error, except when a later pack in the stack provides the same pack-relative path. That copy replaces this one whole, so the broken file cannot reach the composed result and is reported as a warning instead, which keeps a strict load from failing over a file nothing reads. The vanilla layers rely on it: two of them ship an entities/npc.json that only patches a saved pack, and a later layer carries the real one. The Java half has no equivalent rule, because its tags merge across packs rather than replacing one another.

Parameters ​

stack ​

PackStack

options? ​

LoadOptions = {}

Returns ​

LoadResult

Throws ​

In strict mode, when an error is reported. A warning never fails the load.

loadDatapack() ​

loadDatapack(path, registries, validator, collector): void

Defined in: packages/packs/src/datapack.ts:231

Loads one datapack from a directory or zip into the shared registries. Within the Java half a later pack wins per file, except tags, which merge: values concatenate across packs and a pack that sets replace discards the earlier ones, which is vanilla's rule.

Parameters ​

path ​

string

registries ​

DefinitionRegistries

validator ​

DefinitionValidator

collector ​

DiagnosticCollector

Returns ​

void

mergeJavaDefinition() ​

mergeJavaDefinition(mode, previous, data): unknown

Defined in: packages/packs/src/datapack.ts:217

Composes one file over what earlier packs in the stack left for the same id, by the registry's merge mode.

Parameters ​

mode ​

MergeMode

previous ​

unknown

What earlier packs left, or undefined for the first one.

data ​

unknown

Returns ​

unknown

The composed definition data.

parseFilter() ​

parseFilter(value): Filter

Defined in: packages/packs/src/filters.ts:117

Parses a filter from its JSON form into the normalized shape: aliases resolve to their canonical combinator, integer subjects and operators resolve to their names, and the self and == defaults are filled in.

Parameters ​

value ​

unknown

Returns ​

Filter

Throws ​

When the value does not follow the grammar.

parseLenientJson() ​

parseLenientJson(text): unknown

Defined in: packages/packs/src/lenientJson.ts:23

Parses JSON the way the Bedrock engine reads pack files: line and block comments and trailing commas before ] or } are accepted. Vanilla trade tables and root definition files use both.

Strict JSON is tried first and is the same answer the cleanup would reach. Outside a string, valid JSON holds no / to start a comment and no comma before a ] or }, so neither pass can touch a text JSON.parse already accepts. It is worth the extra attempt because the cleanup rewrites the whole text character by character twice over, and 8486 of the 8556 files in the composed vanilla Bedrock stack are strict JSON.

Parameters ​

text ​

string

Returns ​

unknown

Throws ​

When the text is not JSON after lenient cleanup.

parseManifest() ​

parseManifest(value, pack): object

Defined in: packages/packs/src/manifest.ts:47

Parses a decoded manifest.json against the documented schema: header with name, uuid and version; modules with at least one entry, each with type, uuid and version; optional dependencies; and a format_version of 1 for skin packs and 2 otherwise.

Parameters ​

value ​

unknown

pack ​

string

The pack name used in diagnostics, usually the source path.

Returns ​

object

The manifest when it validates, plus every finding. A result without a manifest means the pack cannot load.

diagnostics ​

diagnostics: Diagnostic[]

manifest? ​

optional manifest?: Manifest

parseMcmeta() ​

parseMcmeta(data, pack): McmetaParseResult

Defined in: packages/packs/src/mcmeta.ts:119

Parses a decoded pack.mcmeta. A missing or malformed pack block fails the parse; a pack that declares no format at all parses with formats undefined and a diagnostic, so the loader can gate it explicitly.

Parameters ​

data ​

unknown

pack ​

string

Returns ​

McmetaParseResult

parseVersion() ​

parseVersion(value): FormatVersion | undefined

Defined in: packages/packs/src/formatVersion.ts:14

Parses a version from the three shapes pack files use: a dotted string, an array of numbers, or a bare number. Missing parts read as zero.

Parameters ​

value ​

unknown

Returns ​

FormatVersion | undefined

The normalized version, or undefined when the value has no version shape.

readBedrockSchemas() ​

readBedrockSchemas(root): BedrockSchemaSet

Defined in: packages/packs/src/bedrockSchemas.ts:71

Reads every schema under a bedrock-samples checkout.

Parameters ​

root ​

string

The checkout root, or the metadata/json_schemas directory itself.

Returns ​

BedrockSchemaSet

The schemas indexed by $id and by document name per format version.

Throws ​

When the directory holds no schemas.

readBrarchive() ​

readBrarchive(bytes): Map<string, Uint8Array<ArrayBufferLike>>

Defined in: packages/packs/src/brarchive.ts:37

Reads every file of a brarchive, keyed by member name in table order.

Parameters ​

bytes ​

Uint8Array

Returns ​

Map<string, Uint8Array<ArrayBufferLike>>

Throws ​

When the magic, version or sizes do not match.

readZip() ​

readZip(bytes, limits?): Map<string, Uint8Array<ArrayBufferLike>>

Defined in: packages/packs/src/zip.ts:84

Reads every file of a zip archive, keyed by archive path in central directory order. Directory entries (paths ending in /) are skipped.

Nothing is inflated past what the archive declares: each entry must expand to exactly its declared size, which has to fit the entry limit and the budget before any of it is allocated. Entries whose records overlap are refused, so a small archive cannot name one compressed stream many times over.

Parameters ​

bytes ​

Uint8Array

The archive.

limits? ​

ZipLimits = {}

How much the read may expand to; see ZipLimits.

Returns ​

Map<string, Uint8Array<ArrayBufferLike>>

Throws ​

When the archive is malformed, uses an unsupported compression method, has overlapping entries, or would expand past a limit.

reportIdentifiers() ​

reportIdentifiers(definitions, resolver?): ReferencedIdentifier[]

Defined in: packages/packs/src/identifiers.ts:279

Walks every loaded Java definition and reports each referenced Java identifier with its resolution, sorted by registry and id. Tag members count against the registry their tag file tags; every other reference counts by field name per IDENTIFIER_FIELDS, except id, which registryForId decides from its siblings.

The resolver is asked first, so a reviewed loss stays a loss even when the stack also defines the identifier; references the resolver does not know fall back to the pack stack.

Parameters ​

definitions ​

Definitions

The composed pack stack, as import('./load').load returns it.

resolver? ​

IdentifierResolver = unknownResolver

The Bedrock-side resolver; defaults to unknownResolver.

Returns ​

ReferencedIdentifier[]

One entry per distinct referenced identifier, sorted by registry then id.

routeDatapackPath() ​

routeDatapackPath(path): JavaRoute | undefined

Defined in: packages/packs/src/javaRegistries.ts:189

Routes a pack-relative path to its registry and identifier. Paths outside data/, files that are neither JSON nor .mcfunction, registries this loader does not consume, and the built-in packs nested under data/<namespace>/datapacks/ return undefined.

Parameters ​

path ​

string

Returns ​

JavaRoute | undefined

routeForPath() ​

routeForPath(path): "blocks" | "items" | "entities" | "lootTables" | "tradeTables" | "spawnRules" | "recipes" | "biomes" | "features" | "featureRules" | "itemCatalog" | undefined

Defined in: packages/packs/src/registries.ts:70

Routes a pack-relative path to its registry by top-level folder.

Parameters ​

path ​

string

Returns ​

"blocks" | "items" | "entities" | "lootTables" | "tradeTables" | "spawnRules" | "recipes" | "biomes" | "features" | "featureRules" | "itemCatalog" | undefined

The registry, or undefined for paths no registry owns.

selectSchema() ​

selectSchema(schemas, document, formatVersion): string | undefined

Defined in: packages/packs/src/bedrockSchemas.ts:119

Picks the schema a file's format_version selects, by Mojang's own disambiguation rule: the same version, or the closest one that is not greater. A file older than every published schema selects none, because checking it against a newer schema would report fields that did not exist when the file was written.

Parameters ​

schemas ​

BedrockSchemaSet

document ​

string

The document key, such as server/entity/ActorDocument.json.

formatVersion ​

FormatVersion | undefined

Returns ​

string | undefined

The $id of the selected document, or undefined when none applies.

selectSchemaVersion() ​

selectSchemaVersion<Version>(known, fileVersion): Version

Defined in: packages/packs/src/formatVersion.ts:46

Chooses which schema applies to a file: the newest known schema at or below the file's format_version. A file older than every known schema reads with the oldest one, which is how the engine treats ancient files.

Type Parameters ​

Version ​

Version extends string

Parameters ​

known ​

readonly Version[]

Schema versions in any order; each must parse with parseVersion.

fileVersion ​

FormatVersion

Returns ​

Version

The chosen entry of known.

worldgenIdentifier() ​

worldgenIdentifier(kind, id): string

Defined in: packages/packs/src/javaRegistries.ts:142

The identifier a worldgen file registers under: the kind, then the namespaced id, as noise_settings/minecraft:overworld.

Parameters ​

kind ​

"biome" | "block_state_provider" | "carver" | "density_function" | "feature" | "flat_level_generator_preset" | "material_condition" | "material_rule" | "multi_noise_biome_source_parameter_list" | "noise" | "noise_settings" | "placed_feature" | "processor_list" | "structure" | "structure_set" | "template_pool" | "world_preset"

id ​

string

Returns ​

string