API reference / @jsprismarine/blocks

@jsprismarine/blocks

The block half of the content runtime: the Bedrock block definition grammar, the components that grammar names, the per-state model behind the palette, and the jsprismarine_vanilla overlay pack that declares all 1477 palette blocks.

It knows nothing about behavior. A block's components say what it is; a behavior says what it does. The behavior families live in their own package and plug in through BlockHooks and BehaviorRegistry, described under the behavior seam.

The grammar

One block file is format_version, minecraft:block.description, components and permutations:

{
    "format_version": "1.26.50",
    "minecraft:block": {
        "description": {
            "identifier": "minecraft:shelf_mushroom",
            "menu_category": { "category": "nature" },
            "states": { "growth": [0, 1] },
            "traits": { "minecraft:placement_direction": { "enabled_states": ["minecraft:cardinal_direction"] } }
        },
        "components": { "minecraft:loot": "loot_tables/blocks/shelf_mushroom_growth_0.json" },
        "permutations": [
            {
                "condition": "query.block_state('growth') == 1",
                "components": { "minecraft:loot": "loot_tables/blocks/shelf_mushroom_growth_1.json" }
            }
        ]
    }
}

parseBlockDefinition reads one file into a BlockDefinitionDocument. Bad data comes back as a Diagnostic with the same shape @jsprismarine/packs and @jsprismarine/content use, never as a throw, so one broken file cannot stop a load. A BlockError means a mistake against this package's own interface instead: a state the block does not carry, a runtime id outside the palette.

The parser also reads internal_vanilla_data, the undocumented key all 98 of Mojang's own data-driven block files carry. Its block_archetype is how Mojang attaches engine code to a data-driven block, and this package reads it as a behavior name for exactly that reason.

Schema versions

format_version picks the newest known schema at or below the file's version, through selectSchemaVersion from @jsprismarine/packs. Three versions are known, and each difference comes from a file in the repository's pinned sources.

Version	What changes
1.16.100	The oldest the runtime reads. Mining time, blast resistance, light output and light dampening are written as minecraft:destroy_time, minecraft:explosion_resistance, minecraft:block_light_emission and minecraft:block_light_absorption.
1.19.40	Those four are replaced by minecraft:destructible_by_mining, minecraft:destructible_by_explosion, minecraft:light_emission and minecraft:light_dampening.
1.26.20	description.traits exists. Blocks.json forbids the nine legacy on_* and ticking components plus minecraft:breathability and minecraft:unit_cube at the top level, and Permutation.json forbids a longer list inside a permutation.

A file that uses a component its version does not have loads with the rest of its components and a block.component-version warning. A file that uses a forbidden one gets a block.component-forbidden error for that component only.

Components

createBlockComponentRegistry() returns a ComponentRegistry<BlockHooks> holding 57 factories: the 49 names in Mojang's metadata/json_schemas/server/block/1.26.20/Components.json, the four property components Mojang renamed at 1.19.40, minecraft:custom_components, and this package's three overlay components. Mojang component schemas follow the corresponding schema files, including the defaults they declare; project components follow their documented shapes.

Measured against the real data: Mojang's 98 vanilla block files in bedrock-samples v1.26.50.4 use 20 distinct components under components, plus minecraft:transformation which appears only inside shelf_mushroom's permutations, for 21 in all. That matches the count of 20 in the research note, which counted the base lists. The note's "8 permutations" for shelf_mushroom is one short; the file has nine. src/vanillaBlocks.test.ts checks both numbers and prints the tally.

The three components this project adds

These project components carry metadata the Bedrock block schema does not provide, so the overlay writes them under this project's namespace:

• jsprismarine:block_properties carries friction at Java's precision, random_tick, requires_correct_tool, push_reaction and whether the row came from Java or from the fallback. Mojang's minecraft:friction caps at 0.9 and Java's blue ice is 0.989; minecraft:random_ticking is an internal component Blocks.json forbids at the top level of a current file.
• jsprismarine:behavior names the behavior family. It is the same idea as minecraft:custom_components, which stays registered so a pack that writes the Mojang key keeps working, and sits beside it because Mojang marked that hook deprecated while its version 2 still needs two experimental toggles.
• jsprismarine:container_open_sound names the sound the server plays after opening this block's container screen. For example, "jsprismarine:container_open_sound": "random.chestopen".

No component binds a handler

Every factory returns {}. A component's hooks list is the upper bound of what its parameters let a block reach, which is how the server finds the blocks that can ever see onTick, onRandomTick, onEntityFallOn or onRedstoneUpdate without running anything. onEntity is raised by an entity executing a named event on its home block:

registry.hooksOf('minecraft:tick'); // Set { 'onTick' }
registry.hooksOf('minecraft:friction'); // Set {}

When a block breaks, Prismarine reads minecraft:loot from the active state first and rolls the named behavior-pack table. If the state has no such component, it resolves the block state to Java and rolls that Java block's table.

States and the palette

A BlockStateModel holds one block's states and the dense index of each combination. The canonical order is the states sorted by name, which is the order the block's NBT compound is written in before it is hashed into a network runtime id, so an index here and the wire agree on which state is which. Within that order the first state is the most significant digit, so incrementing an index walks the last state's values first. A bit reads as a boolean however the capture wrote it.

A BlockPalette assigns a dense runtime id per state by walking blocks in identifier order and each block's states in index order. Those ids are the array indices the flattened tables and chunk storage read, not the FNV-1a hashes the network carries. vanillaBlockPalette() builds one from @jsprismarine/minecraft's captured catalog: 1477 blocks over 22079 states.

const palette = vanillaBlockPalette();
palette.runtimeId('minecraft:cocoa', { age: 2, direction: 1 });
palette.stateOf(1234); // { entry, values }

The Bedrock minecraft:tags component is available on each resolved BlockState as tags and hasTag(name). Permutations resolve first, so a state reads the tags of its active component set. Java datapack memberships are available as javaTags and hasJavaTag(name) on both BlockType and BlockState; the content build maps the Java tag members onto Bedrock block identifiers.

Resolving

resolveBlocks(definitions) turns @jsprismarine/packs definitions into a BlockType per identifier and a BlockState per palette state.

A block takes its states from its own description.states and traits when it declares any, and otherwise from the palette, which is what every vanilla file needs: none of the 98 declares a state, and the archetype supplies them. A trait's enabled_states expand through TRAIT_STATES. The state domains come from the captured palette where vanilla declares them, with trait-only domains supplied by this package: minecraft:sixteen_way_rotation is 0 through 15, and minecraft:multi_block_part is 0 through parts - 1 (parts defaults to 2). minecraft:corner_and_cardinal_direction adds both minecraft:cardinal_direction and minecraft:corner.

Permutations are evaluated per state. Each condition compiles once through @jsprismarine/molang and runs against a scope whose only member is block.blockState, which is the whole of what the docs allow in a condition. The components of every matching permutation apply over the base list in declaration order with the later entry winning, which is Mojang's rule, and each one carries override so HookTable replaces rather than appends. States that match the same permutations share one resolved content type, so a block with no permutations costs one resolve however many states it has.

const resolved = resolveBlocks(definitions.blocks.values());
const stairs = resolved.types.get('minecraft:oak_stairs')!;
stairs.state({ weirdo_direction: 2 }).content.params(destructibleByMining);
stairs.state().content.hooks.dispatch('onPlace', event);

The behavior seam

A behavior package registers one Behavior<BlockHooks> per family and attaches it to the identifiers that family covers, then passes the registry to resolveBlocks:

import { BehaviorRegistry } from '@jsprismarine/content';
import { type BlockHooks, resolveBlocks } from '@jsprismarine/blocks';

const behaviors = new BehaviorRegistry<BlockHooks>();
behaviors.register({
    name: 'jsprismarine:crop',
    hooks: ['onRandomTick'],
    create: ({ identifier }) => ({ onRandomTick: (event) => grow(identifier, event) })
});
behaviors.attach('jsprismarine:crop', (identifier) => behaviorFor(identifier) === 'jsprismarine:crop');

resolveBlocks(definitions.blocks.values(), { behaviors });

The hook names copy Mojang's BlockCustomComponent so a future script host can forward a hook straight to a pack's JavaScript without a translation table:

Hook	Event	Returns
onPlace	BlockPlaceEvent	void
onBreak	BlockBreakEvent	void
onNeighborChanged	BlockNeighborChangedEvent	void
onRandomTick	BlockTickEvent	void
onTick	BlockTickEvent	void
onPlayerInteract	BlockPlayerInteractEvent	boolean | BlockInteractResult | undefined
onStepOn	BlockStepOnEvent	void
onEntityFallOn	BlockEntityFallOnEvent	void
onEntity	BlockEntityEvent	void
onRedstoneUpdate	BlockRedstoneUpdateEvent	void
onBlockStateChange	BlockStateChangeEvent	void

Every event carries block: HookBlock, which is the identifier, the position, the dimension and the state values. onPlayerInteract is the one hook with a return value: true means the handler consumed the interaction, which stops the later handlers under dispatchFirst. A handler whose interaction costs the player the held item answers { consumed: true, consumesHeldItem: true } instead, and the host that dispatched the click takes the item out of the hand, outside creative. The event types are structural and name only what a handler reads, so the server's own Player and Entity classes are assignable to HookActor without this package depending on the server.

The held item and the clicked face

Three events carry the item in the hand, under Mojang's own field name itemStack: BlockPlaceEvent, BlockBreakEvent and BlockPlayerInteractEvent. Each one is HookItem | undefined, and undefined means a bare hand or an action the world performed rather than a player. Without it a block behavior cannot decide honeycomb waxing, axe scraping, silk touch, shears, or which bucket filled a cauldron, because every one of those is a fact about the item and not about the block. BlockBreakEvent.correctTool is set by a host that has item data and tags, and reports whether the held item satisfies the block's requires_correct_tool rule.

HookItem is two members, an identifier and a get(name) component reader:

const waxing = event.itemStack?.identifier === 'minecraft:honeycomb';
const silkTouch = event.itemStack?.get('minecraft:enchantments');

It is a structural interface here rather than a dependency on @jsprismarine/items, which is what keeps the block half and the item half of the content runtime independent. ItemStack satisfies it as written: its identifier getter and its get(name): unknown component reader are the same two declarations, so a server passes a stack straight into a block event with no adapter, and neither package imports the other. hooks.test.ts checks the assignment against a stand-in with those declarations.

BlockPlaceEvent also carries face and faceLocation, the same pair BlockPlayerInteractEvent has and the same pair Mojang's PlayerPlaceBlockBeforeEvent carries. face is the face of the block the new one went against, which is what a pillar's pillar_axis comes from; the placer's look direction is right only for a horizontal placement. faceLocation is a FaceLocation, each component in [0, 1] measured from the face's lower north-west corner, which is what picks a slab's half and a stair's upside_down_bit. FaceLocation is a separate type from BlockPosition because its components are fractions of a block rather than world coordinates.

behaviorFor(identifier, archetype?) gives the family name. An archetype wins when the block's own definition declares one, because Mojang already decided the family there; otherwise the identifier picks a rule from BLOCK_FAMILIES. The two agree by construction: slab_block lands in jsprismarine:slab and stair_block in jsprismarine:stairs. Over the palette the rules produce 48 families, the largest being plain_block 217, inert 202, slab 109, stairs 97, double_slab 93 and copper 84. BLOCK_BEHAVIOR_NAMES has 49 entries because pane matches no vanilla block. vanilla_overlay/report.json has the full tally.

Flattening

flattenBlockStates(resolved) precomputes the columns the tick loop, the lighting engine and the explosion code read, as one typed array per column indexed by the dense runtime id:

Column	Array	Source
solid	Uint8Array	minecraft:collision_box, absent means solid
lightEmission	Uint8Array	minecraft:light_emission
lightFilter	Uint8Array	minecraft:light_dampening
blastResistance	Float32Array	minecraft:destructible_by_explosion
hardness	Float32Array	minecraft:destructible_by_mining
friction	Float32Array	jsprismarine:block_properties, then minecraft:friction
randomTick	Uint8Array	jsprismarine:block_properties, or any behavior implementing onRandomTick

An id with no value falls back to the column's default and then to a reviewed exception; an id with neither fails the build, and so does an exception that matched nothing.

Two values Bedrock's grammar has no number for get a Java-sized one: destructible_by_explosion: false stores 3600000, which is Java's own bedrock, and destructible_by_mining: false stores -1.

The overlay pack

vanilla_overlay/ is a real Bedrock behavior pack with a manifest.json and one blocks/<name>.block.json per palette block. It is generated and committed, so a palette or property-table bump is a reviewable diff rather than a silent change at load.

pnpm --filter @jsprismarine/blocks run generate:overlay

The script refreshes the captured display-name and collision geometry tables, builds the package, and then runs utils/generate-overlay.mjs over dist/. That generator is plain JavaScript on purpose: one that imported src/ would have to spell its specifiers the way node's resolver wants, and nothing under src/ should be shaped by a build script. A dependent package needs no allowImportingTsExtensions to typecheck against this one.

Each file carries the Bedrock-expressible properties as real Bedrock components, filled from bedrockBlockPropertiesOf in @jsprismarine/mapping, plus the captured minecraft:display_name, jsprismarine:behavior, and jsprismarine:block_properties. Display names come from the translation keys in the Bedrock block capture and are generated with pnpm --filter @jsprismarine/blocks run generate:display-names. Container blocks also carry jsprismarine:container_open_sound, configured in src/tables/containerOpenSounds.json. The generator writes Prettier-shaped JSON so the committed pack passes prettier --check with no second pass, and src/overlay.test.ts compares the committed files to a fresh run so the two cannot drift. The overlay preserves Bedrock's captured minecraft:tags for all 96 vanilla wool and concrete slab, double-slab, and stair definitions. The tag table comes from the pinned Bedrock samples and is regenerated with pnpm --filter @jsprismarine/blocks run generate:block-tags.

minecraft:redstone_conductivity is written for the 28 vanilla blocks whose Java registration overrides the full-cube conductor default. The boolean values live in src/tables/vanillaRedstoneConductivity.json; the content adapter passes the resolved component value to redstone calculations. Blocks without an override use the full-cube default.

minecraft:collision_box: false is written for blocks whose captured Bedrock states never have a collision box. This comes from the same Bedrock block geometry capture as bedrockCollisionTopOf, rather than a hand-maintained exception list. Blocks with a fixed partial shape receive the exact captured boxes, converted into Bedrock's component coordinates. For blocks whose collision changes by state, the generator matches each captured runtime hash to the vanilla state palette and emits query.block_state permutations for every non-default shape. The report records both fixed shapes and state-varying permutations. Geometry is regenerated with pnpm --filter @jsprismarine/blocks run generate:geometry.

Four blocks have a Java friction Mojang's component cannot hold, so minecraft:friction is clamped to 0.9 and jsprismarine:block_properties.friction keeps the real value: blue ice 0.989, and ice, packed ice and frosted ice at 0.98. vanilla_overlay/report.json lists them.

The 182 blocks on @jsprismarine/mapping's Bedrock-only list get BEDROCK_ONLY_FALLBACK and source: "fallback", and every one of them appears in vanilla_overlay/exceptions.json with a reason: 164 Education Edition chemistry blocks, 9 deprecated palette entries, 5 world-editing blocks, 2 that are entities in Java Edition, and 2 engine-internal markers. The test asserts the list is exactly those 182 and that no entry falls through to a generic reason.

What is left

• Loot and menu categories. Behavior-pack minecraft:loot components and mapped Java loot tables drive block drops in Prismarine. The vanilla overlay does not declare loot components; creative menu categories come from the item registry.

Classes

• BlockError
• BlockLoadError
• BlockPalette
• BlockStateModel

Interfaces

BedrockCollisionPermutation

Defined in: packages/blocks/src/geometry.ts:51

The collision boxes applied when a vanilla block state condition matches.

Properties

boxes

readonly boxes: readonly BedrockCollisionBox[]

Defined in: packages/blocks/src/geometry.ts:55

The boxes normalized to the block cell. An empty list means no collision.

condition

readonly condition: string

Defined in: packages/blocks/src/geometry.ts:53

A Molang condition using query.block_state.

---

BlockBreakEvent

Defined in: packages/blocks/src/hooks.ts:135

A block was broken.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

brokenBlock

readonly brokenBlock: HookBlock

Defined in: packages/blocks/src/hooks.ts:137

The block as it was before breaking, which the drop rules read.

brokenBy

readonly brokenBy: HookActor | undefined

Defined in: packages/blocks/src/hooks.ts:139

Who broke it, absent for a break the world itself performed.

correctTool?

readonly optional correctTool?: boolean

Defined in: packages/blocks/src/hooks.ts:147

Whether the held item satisfies this block's requires_correct_tool rule, when known.

itemStack

readonly itemStack: HookItem | undefined

Defined in: packages/blocks/src/hooks.ts:145

What the breaker held, which decides silk touch, fortune and whether shears took the leaves. Absent for a bare hand and for a break the world itself performed.

---

BlockDefinitionDocument

Defined in: packages/blocks/src/definition.ts:180

One block definition file, parsed and ready to resolve.

Properties

components

readonly components: readonly ComponentEntry[]

Defined in: packages/blocks/src/definition.ts:187

The base components, in declaration order.

description

readonly description: BlockDescription

Defined in: packages/blocks/src/definition.ts:185

formatVersion

readonly formatVersion: FormatVersion

Defined in: packages/blocks/src/definition.ts:182

The file's own format_version.

permutations

readonly permutations: readonly BlockPermutation[]

Defined in: packages/blocks/src/definition.ts:188

schema

readonly schema: BlockSchema

Defined in: packages/blocks/src/definition.ts:184

The schema format_version dispatch chose for it.

stateModel

readonly stateModel: BlockStateModel

Defined in: packages/blocks/src/definition.ts:190

The states the file declares, combined into the canonical encoding.

---

BlockDescription

Defined in: packages/blocks/src/definition.ts:162

minecraft:block.description, parsed.

Properties

identifier

readonly identifier: string

Defined in: packages/blocks/src/definition.ts:163

internalVanillaData

readonly internalVanillaData: InternalVanillaData | undefined

Defined in: packages/blocks/src/definition.ts:168

menuCategory

readonly menuCategory: MenuCategory | undefined

Defined in: packages/blocks/src/definition.ts:164

states

readonly states: readonly BlockStateDefinition[]

Defined in: packages/blocks/src/definition.ts:166

The states the file declares, in declaration order; empty for a vanilla file.

traits

readonly traits: readonly BlockTrait[]

Defined in: packages/blocks/src/definition.ts:167

---

BlockEntityEvent

Defined in: packages/blocks/src/hooks.ts:192

An entity executed a named event on this block.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

entitySource

readonly entitySource: HookActor

Defined in: packages/blocks/src/hooks.ts:194

The entity that executed the event.

name

readonly name: string

Defined in: packages/blocks/src/hooks.ts:196

The event name the entity executed.

---

BlockEntityFallOnEvent

Defined in: packages/blocks/src/hooks.ts:185

An entity landed on the block after falling at least the component's distance.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

entity

readonly entity: HookActor

Defined in: packages/blocks/src/hooks.ts:186

fallDistance

readonly fallDistance: number

Defined in: packages/blocks/src/hooks.ts:188

How far the entity fell, in blocks.

---

BlockEvent

Defined in: packages/blocks/src/hooks.ts:106

What every block hook receives: the block the hook fired for.

Extended by

• BlockPlaceEvent
• BlockBreakEvent
• BlockNeighborChangedEvent
• BlockTickEvent
• BlockPlayerInteractEvent
• BlockStepOnEvent
• BlockEntityFallOnEvent
• BlockEntityEvent
• BlockRedstoneUpdateEvent
• BlockStateChangeEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

---

BlockFamilyRule

Defined in: packages/blocks/src/families.ts:18

One family and the identifiers it claims. First match in BLOCK_FAMILIES wins.

Properties

behavior

readonly behavior: string

Defined in: packages/blocks/src/families.ts:20

The behavior name, in this project's namespace.

contains?

readonly optional contains?: readonly string[]

Defined in: packages/blocks/src/families.ts:26

Substrings anywhere in the identifier, such as copper.

exact?

readonly optional exact?: readonly string[]

Defined in: packages/blocks/src/families.ts:22

Full identifiers, without the namespace.

prefix?

readonly optional prefix?: readonly string[]

Defined in: packages/blocks/src/families.ts:28

Identifier beginnings, such as element_.

suffix?

readonly optional suffix?: readonly string[]

Defined in: packages/blocks/src/families.ts:24

Identifier endings, such as _stairs.

---

BlockFlags

Defined in: packages/blocks/src/types.ts:23

The load-time flags a block type answers by name.

Properties

randomTicking

randomTicking: boolean

Defined in: packages/blocks/src/types.ts:29

Whether the block's components let it reach onRandomTick.

solid

solid: boolean

Defined in: packages/blocks/src/types.ts:25

Whether anything can stand on the block, read from minecraft:collision_box.

ticking

ticking: boolean

Defined in: packages/blocks/src/types.ts:27

Whether the block's components let it reach onTick.

---

BlockHooks

Defined in: packages/blocks/src/hooks.ts:238

The hook map @jsprismarine/content dispatches for blocks.

A component never implements one of these. Components carry parameters and declare which hooks their parameters can reach; behaviors carry the code. That split is the seam the behavior families are written against.

Properties

onBlockStateChange

onBlockStateChange: (event) => void

Defined in: packages/blocks/src/hooks.ts:266

Runs when one of the block's own state values changes in place.

Parameters

event

BlockStateChangeEvent

Returns

void

onBreak

onBreak: (event) => void

Defined in: packages/blocks/src/hooks.ts:242

Runs after the block is removed, with the broken block still readable.

Parameters

event

BlockBreakEvent

Returns

void

onEntity

onEntity: (event) => void

Defined in: packages/blocks/src/hooks.ts:262

Runs when an entity executes a named event on the block.

Parameters

event

BlockEntityEvent

Returns

void

onEntityFallOn

onEntityFallOn: (event) => void

Defined in: packages/blocks/src/hooks.ts:260

Runs when an entity lands on the block, for a block with minecraft:entity_fall_on.

Parameters

event

BlockEntityFallOnEvent

Returns

void

onNeighborChanged

onNeighborChanged: (event) => void

Defined in: packages/blocks/src/hooks.ts:244

Runs when a neighboring position changes, once per changed face.

Parameters

event

BlockNeighborChangedEvent

Returns

void

onPlace

onPlace: (event) => void

Defined in: packages/blocks/src/hooks.ts:240

Runs after the block is placed and its state is committed.

Parameters

event

BlockPlaceEvent

Returns

void

onPlayerInteract

onPlayerInteract: (event) => boolean | BlockInteractResult | undefined

Defined in: packages/blocks/src/hooks.ts:256

Runs when a player uses the block.

Parameters

event

BlockPlayerInteractEvent

Returns

boolean | BlockInteractResult | undefined

True or a BlockInteractResult when the handler consumed the interaction, which stops later handlers and the default item use; undefined to decline.

onRandomTick

onRandomTick: (event) => void

Defined in: packages/blocks/src/hooks.ts:246

Runs on a random tick, for a block the random tick table includes.

Parameters

event

BlockTickEvent

Returns

void

onRedstoneUpdate

onRedstoneUpdate: (event) => void

Defined in: packages/blocks/src/hooks.ts:264

Runs when the redstone power reaching the block changes.

Parameters

event

BlockRedstoneUpdateEvent

Returns

void

onStepOn

onStepOn: (event) => void

Defined in: packages/blocks/src/hooks.ts:258

Runs when an entity's feet enter the block's position.

Parameters

event

BlockStepOnEvent

Returns

void

onTick

onTick: (event) => void

Defined in: packages/blocks/src/hooks.ts:248

Runs on the interval minecraft:tick declares.

Parameters

event

BlockTickEvent

Returns

void

---

BlockInteractResult

Defined in: packages/blocks/src/hooks.ts:224

The object form of an onPlayerInteract answer, for an interaction that costs the player the held item.

It consumes the click exactly as returning true does, and adds the one thing the boolean cannot say: that vanilla charges this click one of the held item. The handler has no inventory to spend from, so the host that dispatched the click takes the item out of the player's hand, outside creative. The portal family answers with it when a held eye of ender fills an end portal frame.

Properties

consumed

readonly consumed: true

Defined in: packages/blocks/src/hooks.ts:226

The handler consumed the interaction.

consumesHeldItem?

readonly optional consumesHeldItem?: boolean

Defined in: packages/blocks/src/hooks.ts:228

Whether the interaction spends one of the held item.

---

BlockNeighborChangedEvent

Defined in: packages/blocks/src/hooks.ts:151

A block next to this one changed.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

face

readonly face: "down" | "up" | "north" | "south" | "west" | "east"

Defined in: packages/blocks/src/hooks.ts:153

The face the changed neighbor sits on.

neighbor

readonly neighbor: HookBlock

Defined in: packages/blocks/src/hooks.ts:154

---

BlockParseResult

Defined in: packages/blocks/src/definition.ts:194

What parseBlockDefinition returns: the document when it parsed, and the report.

Properties

diagnostics

readonly diagnostics: readonly Diagnostic[]

Defined in: packages/blocks/src/definition.ts:197

document

readonly document: BlockDefinitionDocument | undefined

Defined in: packages/blocks/src/definition.ts:196

The parsed document, or undefined when the file has no usable identifier.

---

BlockParseSource

Defined in: packages/blocks/src/definition.ts:201

Where a definition came from, so a diagnostic can name it.

Properties

pack

readonly pack: string

Defined in: packages/blocks/src/definition.ts:203

The pack the file came from.

path?

readonly optional path?: string

Defined in: packages/blocks/src/definition.ts:205

The pack-relative path of the file.

---

BlockPermutation

Defined in: packages/blocks/src/definition.ts:172

One entry of the permutations array.

Properties

components

readonly components: readonly ComponentEntry[]

Defined in: packages/blocks/src/definition.ts:176

The components it applies over the base set, in declaration order.

condition

readonly condition: string

Defined in: packages/blocks/src/definition.ts:174

The Molang condition, limited to query.block_state by the docs.

---

BlockPlaceEvent

Defined in: packages/blocks/src/hooks.ts:111

A block was placed.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

face

readonly face: "down" | "up" | "north" | "south" | "west" | "east" | undefined

Defined in: packages/blocks/src/hooks.ts:126

The face of the block the new one was placed against, so a pillar takes its axis from the click rather than from where the placer stood. Absent for a placement with no face.

faceLocation

readonly faceLocation: FaceLocation | undefined

Defined in: packages/blocks/src/hooks.ts:131

Where on that face the click landed, which picks a slab's half and a stair's upside_down_bit. Absent when the placement has no face.

itemStack

readonly itemStack: HookItem | undefined

Defined in: packages/blocks/src/hooks.ts:120

The item the placement came out of, absent for a placement the world itself performed.

placedBy

readonly placedBy: HookActor | undefined

Defined in: packages/blocks/src/hooks.ts:115

Who placed it, absent for a placement the world itself performed.

previous

readonly previous: HookBlock | undefined

Defined in: packages/blocks/src/hooks.ts:113

What the position held before, which a replaceable block overwrote.

---

BlockPlacementContext

Defined in: packages/blocks/src/hooks.ts:70

The player and hit details that distinguish an item placement from a world write.

Properties

face?

readonly optional face?: "down" | "up" | "north" | "south" | "west" | "east"

Defined in: packages/blocks/src/hooks.ts:76

The face the player clicked.

faceLocation?

readonly optional faceLocation?: FaceLocation

Defined in: packages/blocks/src/hooks.ts:78

Where on the clicked face the player clicked.

itemStack?

readonly optional itemStack?: HookItem

Defined in: packages/blocks/src/hooks.ts:74

The item the block came from, when the host resolved it.

placedBy

readonly placedBy: HookActor

Defined in: packages/blocks/src/hooks.ts:72

Who placed the block.

---

BlockPlayerInteractEvent

Defined in: packages/blocks/src/hooks.ts:164

A player used the block.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

face

readonly face: "down" | "up" | "north" | "south" | "west" | "east" | undefined

Defined in: packages/blocks/src/hooks.ts:169

The face the player clicked, absent when the interaction has no face.

faceLocation

readonly faceLocation: FaceLocation | undefined

Defined in: packages/blocks/src/hooks.ts:171

Where on the face the click landed.

itemStack

readonly itemStack: HookItem | undefined

Defined in: packages/blocks/src/hooks.ts:176

What the player held, which decides waxing, scraping, filling and lighting. Absent for a bare hand.

player

readonly player: HookActor

Defined in: packages/blocks/src/hooks.ts:165

sneaking?

readonly optional sneaking?: boolean

Defined in: packages/blocks/src/hooks.ts:167

Whether the player was sneaking when the interaction began.

---

BlockPosition

Defined in: packages/blocks/src/hooks.ts:14

A block position in world coordinates, with integer components.

Properties

x

readonly x: number

Defined in: packages/blocks/src/hooks.ts:15

y

readonly y: number

Defined in: packages/blocks/src/hooks.ts:16

z

readonly z: number

Defined in: packages/blocks/src/hooks.ts:17

---

BlockPropertySource

Defined in: packages/blocks/src/overlay.ts:27

Where the generator reads a block's properties from.

The generator takes this rather than importing @jsprismarine/mapping directly so the package script can run under plain node, which cannot load that package's JSON table without an import attribute. The mapping-backed source is JAVA_BLOCK_PROPERTIES, and the overlay test checks that the two agree file for file.

Properties

bedrockOnly

readonly bedrockOnly: ReadonlySet<string>

Defined in: packages/blocks/src/overlay.ts:29

Identifiers no Java block state maps onto, which take the fallback.

Methods

propertiesOf()

propertiesOf(identifier): BedrockBlockProperties | undefined

Defined in: packages/blocks/src/overlay.ts:31

The Java-sourced row for one block, or undefined for a Bedrock-only one.

Parameters

identifier

string

Returns

BedrockBlockProperties | undefined

---

BlockRedstoneUpdateEvent

Defined in: packages/blocks/src/hooks.ts:200

The redstone power reaching the block changed.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

power

readonly power: number

Defined in: packages/blocks/src/hooks.ts:202

The power now reaching the block, 0 to 15.

---

BlockResolveOptions

Defined in: packages/blocks/src/types.ts:161

Options for resolveBlocks.

Properties

behaviors?

optional behaviors?: BehaviorRegistry<BlockHooks>

Defined in: packages/blocks/src/types.ts:165

The behavior families to attach by identifier.

components?

optional components?: ComponentRegistry<BlockHooks>

Defined in: packages/blocks/src/types.ts:163

The components to bind; a fresh registry of the vanilla set by default.

javaTags?

optional javaTags?: (identifier, values) => readonly string[]

Defined in: packages/blocks/src/types.ts:167

Java datapack tags for each resolved Bedrock block identifier and state.

Parameters

identifier

string

values

Readonly<Record<string, BlockStateValue>>

Returns

readonly string[]

molang?

optional molang?: Molang

Defined in: packages/blocks/src/types.ts:169

The engine permutation conditions compile through; a fresh one by default.

statePalette?

optional statePalette?: BlockPalette

Defined in: packages/blocks/src/types.ts:174

Where a block's states come from when its definition declares none, as every vanilla file does. The captured Bedrock palette by default.

strict?

optional strict?: boolean

Defined in: packages/blocks/src/types.ts:176

Fail on any diagnostic instead of reporting and continuing.

---

BlockResolveResult

Defined in: packages/blocks/src/types.ts:150

What resolveBlocks returns.

Properties

diagnostics

readonly diagnostics: readonly Diagnostic[]

Defined in: packages/blocks/src/types.ts:157

palette

readonly palette: BlockPalette

Defined in: packages/blocks/src/types.ts:152

The palette the dense runtime ids index, built from the resolved blocks.

states

readonly states: readonly BlockState[]

Defined in: packages/blocks/src/types.ts:156

Every state, indexed by its dense runtime id.

types

readonly types: ReadonlyMap<string, BlockType>

Defined in: packages/blocks/src/types.ts:154

Identifier to type, in palette order.

---

BlockSchema

Defined in: packages/blocks/src/definition.ts:21

What one schema version of the block grammar accepts.

Properties

forbiddenInDefinition

readonly forbiddenInDefinition: readonly string[]

Defined in: packages/blocks/src/definition.ts:30

Component names this version forbids directly under components.

forbiddenInPermutation

readonly forbiddenInPermutation: readonly string[]

Defined in: packages/blocks/src/definition.ts:32

Component names this version forbids inside a permutation's components.

statesAndPermutations

readonly statesAndPermutations: boolean

Defined in: packages/blocks/src/definition.ts:24

Whether description.states and the permutations array are read.

traits

readonly traits: boolean

Defined in: packages/blocks/src/definition.ts:26

Whether description.traits is read.

version

readonly version: "1.16.100" | "1.19.40" | "1.26.20"

Defined in: packages/blocks/src/definition.ts:22

withoutComponents

readonly withoutComponents: readonly string[]

Defined in: packages/blocks/src/definition.ts:28

Component names this version does not have, reported when a file uses one.

---

BlockState

Defined in: packages/blocks/src/types.ts:53

One palette state of one block: the handle the server holds per placed block.

Properties

content

readonly content: Type<BlockHooks, keyof BlockFlags>

Defined in: packages/blocks/src/types.ts:75

The resolved content type for this state: its bound components, its behaviors and its hook table, with the matching permutations applied over the base components.

index

readonly index: number

Defined in: packages/blocks/src/types.ts:56

The canonical index within the block, from its BlockStateModel.

javaTags

readonly javaTags: readonly string[]

Defined in: packages/blocks/src/types.ts:67

The Java datapack tags attached to this block type.

permutations

readonly permutations: PermutationMask

Defined in: packages/blocks/src/types.ts:61

Which permutations matched this state, in declaration order.

runtimeId

readonly runtimeId: number

Defined in: packages/blocks/src/types.ts:58

The dense id across the whole palette, which indexes a flattened column.

tags

readonly tags: readonly string[]

Defined in: packages/blocks/src/types.ts:63

The Bedrock tags attached to this state after its permutations resolve.

type

readonly type: BlockType

Defined in: packages/blocks/src/types.ts:54

values

readonly values: Readonly<Record<string, BlockStateValue>>

Defined in: packages/blocks/src/types.ts:59

Methods

hasJavaTag()

hasJavaTag(tag): boolean

Defined in: packages/blocks/src/types.ts:69

Whether a Java datapack tag includes this block type.

Parameters

tag

string

Returns

boolean

hasTag()

hasTag(tag): boolean

Defined in: packages/blocks/src/types.ts:65

Whether this state carries one of its Bedrock minecraft:tags.

Parameters

tag

string

Returns

boolean

---

BlockStateChangeEvent

Defined in: packages/blocks/src/hooks.ts:206

One of the block's own state values changed in place.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

newValue

readonly newValue: BlockStateValue

Defined in: packages/blocks/src/hooks.ts:210

previousValue

readonly previousValue: BlockStateValue

Defined in: packages/blocks/src/hooks.ts:209

state

readonly state: string

Defined in: packages/blocks/src/hooks.ts:208

The state that changed.

---

BlockStateDefinition

Defined in: packages/blocks/src/state.ts:10

One state a block carries, with the values the game accepts for it.

Properties

defaultValue

readonly defaultValue: BlockStateValue

Defined in: packages/blocks/src/state.ts:17

The value a freshly placed block starts with; always one of values.

name

readonly name: string

Defined in: packages/blocks/src/state.ts:12

The state name, such as facing_direction or minecraft:cardinal_direction.

type

readonly type: BlockStateType

Defined in: packages/blocks/src/state.ts:13

values

readonly values: readonly BlockStateValue[]

Defined in: packages/blocks/src/state.ts:15

Every accepted value, in the order the encoding counts them.

---

BlockStepOnEvent

Defined in: packages/blocks/src/hooks.ts:180

An entity walked onto the block.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

entity

readonly entity: HookActor

Defined in: packages/blocks/src/hooks.ts:181

---

BlockTickEvent

Defined in: packages/blocks/src/hooks.ts:158

A scheduled or random tick reached the block.

Extends

• BlockEvent

Properties

block

readonly block: HookBlock

Defined in: packages/blocks/src/hooks.ts:107

Inherited from

BlockEvent.block

tick

readonly tick: number

Defined in: packages/blocks/src/hooks.ts:160

The world tick counter when the hook fired.

---

BlockTrait

Defined in: packages/blocks/src/definition.ts:131

One trait a block enables, with the states the trait supplies.

Properties

enabledStates

readonly enabledStates: readonly string[]

Defined in: packages/blocks/src/definition.ts:135

The enabled_states the trait adds to the block.

name

readonly name: string

Defined in: packages/blocks/src/definition.ts:133

The trait name, such as minecraft:placement_direction.

parameters

readonly parameters: Readonly<Record<string, unknown>>

Defined in: packages/blocks/src/definition.ts:137

The trait's remaining parameters, unparsed, such as y_rotation_offset.

---

BlockType

Defined in: packages/blocks/src/types.ts:79

One block definition resolved once per identifier.

Properties

definition

readonly definition: BlockDefinitionDocument

Defined in: packages/blocks/src/types.ts:81

identifier

readonly identifier: string

Defined in: packages/blocks/src/types.ts:80

javaTags

readonly javaTags: readonly string[]

Defined in: packages/blocks/src/types.ts:83

The Java datapack tags attached to this block type.

model

readonly model: BlockStateModel

Defined in: packages/blocks/src/types.ts:87

The states the block carries, which the palette or the definition supplied.

states

readonly states: readonly BlockState[]

Defined in: packages/blocks/src/types.ts:89

Every state of the block, in canonical index order.

Methods

hasJavaTag()

hasJavaTag(tag): boolean

Defined in: packages/blocks/src/types.ts:85

Whether a Java datapack tag includes this block type.

Parameters

tag

string

Returns

boolean

state()

state(values?): BlockState

Defined in: packages/blocks/src/types.ts:95

One state by its values; a state the caller left out takes its default.

Parameters

values?

Readonly<Record<string, BlockStateValue>>

Returns

BlockState

Throws

When a name is not one of the block's states.

---

FaceLocation

Defined in: packages/blocks/src/hooks.ts:35

A point on a block face, each component in [0, 1] and measured from the face's lower north-west corner, which is where Mojang's faceLocation starts counting.

It is a separate type from BlockPosition because its components are fractions of a block rather than world coordinates. A slab reads y to decide which half it takes.

Properties

x

readonly x: number

Defined in: packages/blocks/src/hooks.ts:36

y

readonly y: number

Defined in: packages/blocks/src/hooks.ts:37

z

readonly z: number

Defined in: packages/blocks/src/hooks.ts:38

---

Field

Defined in: packages/blocks/src/schema.ts:116

One field of an object schema: where it is written and what fills it when absent.

Type Parameters

P

P

Properties

fallback?

readonly optional fallback?: P

Defined in: packages/blocks/src/schema.ts:121

The value when the key is absent; a field with none is required.

key

readonly key: string

Defined in: packages/blocks/src/schema.ts:118

The key as the JSON writes it, in snake case.

required?

readonly optional required?: boolean

Defined in: packages/blocks/src/schema.ts:122

schema

readonly schema: Schema<P>

Defined in: packages/blocks/src/schema.ts:119

---

FrictionClamp

Defined in: packages/blocks/src/overlay.ts:129

One block whose Java friction does not fit Mojang's minecraft:friction range.

Properties

clampedTo

readonly clampedTo: number

Defined in: packages/blocks/src/overlay.ts:134

What minecraft:friction was written as.

identifier

readonly identifier: string

Defined in: packages/blocks/src/overlay.ts:130

javaFriction

readonly javaFriction: number

Defined in: packages/blocks/src/overlay.ts:132

The Java value, which jsprismarine:block_properties keeps.

---

HookActor

Defined in: packages/blocks/src/hooks.ts:59

An entity or player as a block hook sees one.

Extended by

• WorldEntity

Properties

identifier

readonly identifier: string

Defined in: packages/blocks/src/hooks.ts:61

The namespaced entity identifier, such as minecraft:player.

pitch?

readonly optional pitch?: number

Defined in: packages/blocks/src/hooks.ts:64

The actor's pitch when the host knows it.

position

readonly position: BlockPosition

Defined in: packages/blocks/src/hooks.ts:62

yaw?

readonly optional yaw?: number

Defined in: packages/blocks/src/hooks.ts:66

The actor's yaw when the host knows it.

---

HookBlock

Defined in: packages/blocks/src/hooks.ts:48

The block a hook fires for: where it is, what it is, and the state values a permutation condition reads.

Properties

dimension

readonly dimension: string

Defined in: packages/blocks/src/hooks.ts:53

The dimension the block is in, such as minecraft:overworld.

identifier

readonly identifier: string

Defined in: packages/blocks/src/hooks.ts:50

The namespaced block identifier, such as minecraft:oak_stairs.

position

readonly position: BlockPosition

Defined in: packages/blocks/src/hooks.ts:51

states

readonly states: Readonly<Record<string, BlockStateValue>>

Defined in: packages/blocks/src/hooks.ts:55

Every state value the block carries, keyed by state name.

---

HookItem

Defined in: packages/blocks/src/hooks.ts:92

The item in the hand that placed, broke or used the block.

Mojang's events carry the whole ItemStack; this names the two things a block behavior reads off one, so honeycomb, an axe, shears, a bucket and a silk touch enchantment are all decidable without this package depending on @jsprismarine/items. That package's ItemStack satisfies this structurally, with the same identifier getter and the same get(name): unknown component reader, so it is assignable here with no adapter and no import in either direction.

Properties

identifier

readonly identifier: string

Defined in: packages/blocks/src/hooks.ts:94

The namespaced item identifier, such as minecraft:honeycomb.

Methods

get()

get(name): unknown

Defined in: packages/blocks/src/hooks.ts:102

One of the item's components, by name.

Parameters

name

string

A component name, such as minecraft:enchantments.

Returns

unknown

The component's parameters, or undefined when the item does not carry it.

---

InternalVanillaData

Defined in: packages/blocks/src/definition.ts:148

The undocumented internal_vanilla_data the 98 vanilla block files carry.

Nothing in MicrosoftDocs/minecraft-creator describes it. The overlay generator reads blockArchetype to name a behavior, because the archetype is the mechanism Mojang itself uses to attach engine code to a data-driven block.

Properties

archetypeParameters

readonly archetypeParameters: Readonly<Record<string, unknown>>

Defined in: packages/blocks/src/definition.ts:156

The archetype's own parameters, such as a stair's base_block.

blockArchetype

readonly blockArchetype: string | undefined

Defined in: packages/blocks/src/definition.ts:154

The single key of block_archetype, such as slab_block, or undefined when absent.

blockId

readonly blockId: number | undefined

Defined in: packages/blocks/src/definition.ts:150

block_id, equal to raw_id in mojang-blocks.json.

material

readonly material: string | undefined

Defined in: packages/blocks/src/definition.ts:152

material: solid, plant or solid_plant in the vanilla files.

raw

readonly raw: Readonly<Record<string, unknown>>

Defined in: packages/blocks/src/definition.ts:158

Every key as the file wrote it, for the fields this interface does not name.

---

LengthLimits

Defined in: packages/blocks/src/schema.ts:63

How many entries an array schema accepts.

Properties

max?

readonly optional max?: number

Defined in: packages/blocks/src/schema.ts:65

min?

readonly optional min?: number

Defined in: packages/blocks/src/schema.ts:64

---

MenuCategory

Defined in: packages/blocks/src/definition.ts:122

Where a block appears in the creative menu.

Properties

category

readonly category: string

Defined in: packages/blocks/src/definition.ts:124

construction, nature, equipment, items or none.

group

readonly group: string | undefined

Defined in: packages/blocks/src/definition.ts:126

The namespaced group key, such as minecraft:itemGroup.name.stairs.

hiddenInCommands

readonly hiddenInCommands: boolean

Defined in: packages/blocks/src/definition.ts:127

---

OverlayException

Defined in: packages/blocks/src/overlay.ts:122

One block that took BEDROCK_ONLY_FALLBACK instead of a Java row.

Properties

behavior

readonly behavior: string

Defined in: packages/blocks/src/overlay.ts:124

identifier

readonly identifier: string

Defined in: packages/blocks/src/overlay.ts:123

reason

readonly reason: string

Defined in: packages/blocks/src/overlay.ts:125

---

OverlayFile

Defined in: packages/blocks/src/overlay.ts:114

One file of the generated overlay pack.

Properties

content

readonly content: string

Defined in: packages/blocks/src/overlay.ts:118

The file's text, newline terminated.

path

readonly path: string

Defined in: packages/blocks/src/overlay.ts:116

The pack-relative path, with / separators.

---

OverlayPack

Defined in: packages/blocks/src/overlay.ts:138

What generateVanillaOverlay produced.

Properties

behaviorCounts

readonly behaviorCounts: Readonly<Record<string, number>>

Defined in: packages/blocks/src/overlay.ts:156

How many blocks each behavior family claimed, highest first.

collisionPermutationBlockCount

readonly collisionPermutationBlockCount: number

Defined in: packages/blocks/src/overlay.ts:148

Blocks whose collision shape changes across their vanilla states.

collisionPermutationCount

readonly collisionPermutationCount: number

Defined in: packages/blocks/src/overlay.ts:150

Collision shape overrides emitted across all state-varying blocks.

collisionShapeCount

readonly collisionShapeCount: number

Defined in: packages/blocks/src/overlay.ts:154

Blocks whose fixed partial collision shape was written as a component.

displayNameCount

readonly displayNameCount: number

Defined in: packages/blocks/src/overlay.ts:152

How many blocks received their captured Bedrock display name.

exceptions

readonly exceptions: readonly OverlayException[]

Defined in: packages/blocks/src/overlay.ts:142

The Bedrock-only blocks, in palette order.

files

readonly files: readonly OverlayFile[]

Defined in: packages/blocks/src/overlay.ts:140

Every file, manifest.json first, then one per block, then the reports.

frictionClamps

readonly frictionClamps: readonly FrictionClamp[]

Defined in: packages/blocks/src/overlay.ts:144

The blocks whose Java friction Mojang's component cannot hold.

nonCollidingBlocks

readonly nonCollidingBlocks: readonly string[]

Defined in: packages/blocks/src/overlay.ts:146

Blocks whose captured Bedrock states never have collision geometry.

---

PaletteEntry

Defined in: packages/blocks/src/state.ts:139

One block in a palette: its identifier, its states and where its dense ids start.

Properties

firstRuntimeId

readonly firstRuntimeId: number

Defined in: packages/blocks/src/state.ts:143

The dense runtime id of the block's state index 0.

identifier

readonly identifier: string

Defined in: packages/blocks/src/state.ts:140

model

readonly model: BlockStateModel

Defined in: packages/blocks/src/state.ts:141

Type Aliases

BedrockCollisionBox

BedrockCollisionBox = readonly [number, number, number, number, number, number]

Defined in: packages/blocks/src/geometry.ts:48

One normalized collision box: minimum X/Y/Z, then maximum X/Y/Z.

---

BlockComponentFactory

BlockComponentFactory<P> = ComponentFactory<BlockHooks, P>

Defined in: packages/blocks/src/components.ts:45

A block component factory, with this package's hook map already applied.

Type Parameters

P

P

---

BlockFace

BlockFace = typeof BLOCK_FACES[number]

Defined in: packages/blocks/src/hooks.ts:24

One of BLOCK_FACES.

---

BlockHookName

BlockHookName = typeof BLOCK_HOOK_NAMES[number]

Defined in: packages/blocks/src/hooks.ts:289

One of BLOCK_HOOK_NAMES.

---

BlockSchemaVersion

BlockSchemaVersion = typeof BLOCK_SCHEMA_VERSIONS[number]

Defined in: packages/blocks/src/definition.ts:18

One of BLOCK_SCHEMA_VERSIONS.

---

BlockStateType

BlockStateType = "bool" | "int" | "string"

Defined in: packages/blocks/src/state.ts:7

How a block state's values are written: a bit, a number or a name.

---

BlockStateValue

BlockStateValue = string | number | boolean

Defined in: packages/blocks/src/hooks.ts:42

A block state value as the palette holds it; booleans travel as 0 and 1 on the wire.

---

BlockTable

BlockTable = FlatTable<typeof COLUMNS>

Defined in: packages/blocks/src/flatten.ts:86

The flattened per-state table: one typed array per column, indexed by runtime id.

---

LiquidReaction

LiquidReaction = "blocking" | "popped" | "broken" | "none"

Defined in: packages/blocks/src/geometry.ts:21

What a liquid reaching a block does, as Bedrock's liquidReactionOnTouch names it.

---

PermutationMask

PermutationMask = readonly number[]

Defined in: packages/blocks/src/permutations.ts:12

Which permutations of a definition match one state, as an index list in declaration order. The order is what decides the winner, so it is also the key the resolver groups states by.

---

Schema

Schema<P> = ComponentSchema<P>

Defined in: packages/blocks/src/schema.ts:15

A parse function for one JSON value, which is what a component schema is.

Type Parameters

P

P

---

ShapeOf

ShapeOf<F> = { readonly [K in keyof F]: F[K] extends Field<infer P> ? P : never }

Defined in: packages/blocks/src/schema.ts:132

The object one set of fields parses into, with each field's own value type.

Type Parameters

F

F

---

Vector3

Vector3 = readonly [number, number, number]

Defined in: packages/blocks/src/schema.ts:163

A three-component vector, which Mojang's schemas write as [x, y, z].

Variables

BEDROCK_FRICTION_CAP

const BEDROCK_FRICTION_CAP: 0.9 = 0.9

Defined in: packages/blocks/src/overlay.ts:41

Mojang's minecraft:friction caps here, so the component is clamped to it.

---

BEDROCK_GEOMETRY_STATE_COUNT

const BEDROCK_GEOMETRY_STATE_COUNT: number = table.stateCount

Defined in: packages/blocks/src/geometry.ts:62

How many palette states the capture covers, which a test pins against the palette.

---

BEDROCK_ONLY_FALLBACK

const BEDROCK_ONLY_FALLBACK: BedrockBlockProperties

Defined in: packages/blocks/src/overlay.ts:52

The properties a Bedrock-only block takes, since no Java block state maps onto it and @jsprismarine/mapping publishes no row for it.

The values are the engine's defaults for a plain full cube that breaks instantly. Every block that takes them is listed in the generated exceptions.json with a reason, so the fallback is reviewed rather than silent.

---

BLOCK_BEHAVIOR_NAMES

const BLOCK_BEHAVIOR_NAMES: readonly string[]

Defined in: packages/blocks/src/families.ts:353

Every behavior name the family rules can produce, plus the default.

---

BLOCK_COMPONENTS

const BLOCK_COMPONENTS: readonly BlockComponentFactory<unknown>[]

Defined in: packages/blocks/src/components.ts:601

Every component this package implements, in the order the registry takes them. The 49 names in Mojang's Components.json, the four property components Mojang renamed at 1.19.40, minecraft:custom_components, and this project's three overlay components.

---

BLOCK_COMPONENT_NAMES

const BLOCK_COMPONENT_NAMES: readonly string[]

Defined in: packages/blocks/src/components.ts:662

Every component name this package implements, in registration order.

---

BLOCK_FACES

const BLOCK_FACES: readonly ["down", "up", "north", "south", "west", "east"]

Defined in: packages/blocks/src/hooks.ts:21

The six faces a placement, interaction or neighbor update can come from.

---

BLOCK_FAMILIES

const BLOCK_FAMILIES: readonly BlockFamilyRule[]

Defined in: packages/blocks/src/families.ts:59

Every family, in match order. The order carries meaning: _fence_gate before _fence, _wall_sign before _wall, redstone_torch before torch, and the inert bucket before the plain-cube default.

---

BLOCK_HOOK_NAMES

const BLOCK_HOOK_NAMES: readonly ["onPlace", "onBreak", "onNeighborChanged", "onRandomTick", "onTick", "onPlayerInteract", "onStepOn", "onEntityFallOn", "onEntity", "onRedstoneUpdate", "onBlockStateChange"]

Defined in: packages/blocks/src/hooks.ts:274

Every hook name, in the order the package documents them. The type test beside this declaration fails when BlockHooks gains a hook the list does not, so the two cannot drift.

---

BLOCK_SCHEMAS

const BLOCK_SCHEMAS: Readonly<Record<BlockSchemaVersion, BlockSchema>>

Defined in: packages/blocks/src/definition.ts:90

Every schema version, keyed by its format_version.

The 1.26.20 entry is read from metadata/json_schemas/server/block/1.26.20/ in Mojang/bedrock-samples v1.26.50.4: Blocks.json and Permutation.json carry the two forbidden sets as propertyNames patterns, and Description.json carries states and traits. The 1.19.40 boundary is the property-component rename recorded in docs/research/bedrock-blocks-items-recipes-biomes-features.md section 1.

---

BLOCK_SCHEMA_VERSIONS

const BLOCK_SCHEMA_VERSIONS: readonly ["1.16.100", "1.19.40", "1.26.20"]

Defined in: packages/blocks/src/definition.ts:15

The schema versions this package knows, oldest first. format_version dispatch picks the newest entry at or below the file's version, which is the rule selectSchemaVersion in @jsprismarine/packs implements.

---

DEFAULT_BLOCK_BEHAVIOR

const DEFAULT_BLOCK_BEHAVIOR: "jsprismarine:plain_block" = 'jsprismarine:plain_block'

Defined in: packages/blocks/src/families.ts:326

The behavior every block with no family rule takes: a full cube with no behavior of its own.

---

DEFAULT_LIGHT_DAMPENING

const DEFAULT_LIGHT_DAMPENING: 15 = 15

Defined in: packages/blocks/src/components.ts:207

The light dampening of a block that omits minecraft:light_dampening.

---

EXPLOSION_PROOF_RESISTANCE

const EXPLOSION_PROOF_RESISTANCE: 3600000 = 3_600_000

Defined in: packages/blocks/src/flatten.ts:22

The blast resistance stored for "minecraft:destructible_by_explosion": false.

Bedrock's grammar has no number for "no explosion breaks this", and Java gives bedrock itself 3600000, so the table stores that rather than an infinity a Float32Array cannot hold.

---

FULL_BLOCK

const FULL_BLOCK: 1 = 1

Defined in: packages/blocks/src/geometry.ts:70

An ordinary cube, and what a block outside the capture is taken to be.

Wrong in the safe direction: an unknown block is a wall rather than a hole, so nothing falls through the world or walks into a block it cannot see.

---

JAVA_BLOCK_PROPERTIES

const JAVA_BLOCK_PROPERTIES: BlockPropertySource

Defined in: packages/blocks/src/javaProperties.ts:15

The Java-sourced property table as the overlay generator reads it: the 1295 rows @jsprismarine/mapping flattened out of the Java 26.3 jar dump, plus the 182 Bedrock-only identifiers it publishes no row for.

The generator takes a block's base row only, with no state values, because one overlay file covers every state of its block. The per-state overrides a lit candle or an extended piston needs come from the behavior family, not from the pack.

---

OVERLAY_FORMAT_VERSION

const OVERLAY_FORMAT_VERSION: "1.26.20" = '1.26.20'

Defined in: packages/blocks/src/overlay.ts:38

The format_version every overlay block file declares.

---

OVERLAY_PACK_NAME

const OVERLAY_PACK_NAME: "jsprismarine_vanilla" = 'jsprismarine_vanilla'

Defined in: packages/blocks/src/overlay.ts:35

The pack identifier the overlay declares, which is also its folder name.

---

PASSABLE

const PASSABLE: 0 = 0

Defined in: packages/blocks/src/geometry.ts:73

A block anything walks straight through.

---

PORTAL_BLOCK_NAMES

const PORTAL_BLOCK_NAMES: object

Defined in: packages/blocks/src/families.ts:41

The blocks the jsprismarine:portal family claims, grouped by the role each plays in a portal, without the namespace.

@jsprismarine/block-behaviors reads the groups to know which block is a nether portal, which is an end portal frame and which fire lights a frame, so the family rule and the geometry rules name the blocks once. The end gateway is here rather than in the inert bucket because it teleports, which is portal work, even though no hook handles it yet.

Type Declaration

endGateway

readonly endGateway: readonly ["end_gateway"]

The End's intradimensional gateway.

endPortal

readonly endPortal: readonly ["end_portal"]

The block the end portal frame ring fills with.

endPortalFrame

readonly endPortalFrame: readonly ["end_portal_frame"]

The ring block an eye of ender goes into.

fire

readonly fire: readonly ["fire", "soul_fire"]

The two fires, either of which lights a nether portal frame.

netherPortal

readonly netherPortal: readonly ["portal"]

The lit nether portal block, minecraft:portal on Bedrock.

---

TRAIT_STATES

const TRAIT_STATES: Readonly<Record<string, Readonly<Record<string, readonly string[]>>>>

Defined in: packages/blocks/src/traits.ts:12

Which states each trait's enabled_states entries add to a block.

The trait names and the enabled_states enums come from metadata/json_schemas/server/block/1.26.20/Traits.json and the four * Enabled State.json files beside it in Mojang/bedrock-samples v1.26.50.4. minecraft:cardinal_connections is the one entry that expands to more than one state.

---

UNBREAKABLE_HARDNESS

const UNBREAKABLE_HARDNESS: -1 = -1

Defined in: packages/blocks/src/flatten.ts:25

The hardness stored for a block no mining breaks, matching Java's own -1.

---

behavior

const behavior: BlockComponentFactory<string>

Defined in: packages/blocks/src/components.ts:590

jsprismarine:behavior, the behavior family the overlay assigns a block.

It is the same idea as minecraft:custom_components and exists beside it so a pack can keep the Mojang key for a script component while the overlay names an engine family.

---

blockEntity

const blockEntity: BlockComponentFactory<ShapeOf<{ container: Field<ShapeOf<{ slotCount: Field<number>; }> | undefined>; dynamicProperties: Field<boolean>; }>>

Defined in: packages/blocks/src/components.ts:416

minecraft:block_entity, the container and dynamic property storage a block keeps.

---

blockLightAbsorption

const blockLightAbsorption: BlockComponentFactory<number>

Defined in: packages/blocks/src/components.ts:560

minecraft:block_light_absorption, the pre-1.19.40 spelling of the light dampening.

---

blockLightEmission

const blockLightEmission: BlockComponentFactory<number>

Defined in: packages/blocks/src/components.ts:557

minecraft:block_light_emission, the pre-1.19.40 light output as a 0 to 1 fraction of 15.

---

blockProperties

const blockProperties: BlockComponentFactory<ShapeOf<{ friction: Field<number>; pushReaction: Field<"push" | "popped" | "push_pull" | "immovable">; randomTick: Field<boolean>; requiresCorrectTool: Field<boolean>; source: Field<"java" | "fallback">; }>>

Defined in: packages/blocks/src/components.ts:572

jsprismarine:block_properties, this project's own component for the per-state facts Bedrock's grammar cannot hold.

The overlay pack writes it from @jsprismarine/mapping's Java-sourced table. Friction is here at full precision because Mojang's minecraft:friction caps at 0.9 and Java's blue ice is 0.989, and random ticking is here because minecraft:random_ticking is an internal component Blocks.json forbids at the top level of a current file.

---

boolean

const boolean: Schema<boolean>

Defined in: packages/blocks/src/schema.ts:22

Accepts true and false.

---

breathability

const breathability: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:413

minecraft:breathability. Internal, and Blocks.json forbids it at the top level of a 1.26.20 file. Mojang's schema declares it as an empty object, so the parameters are whatever the file wrote.

---

chestObstruction

const chestObstruction: BlockComponentFactory<ShapeOf<{ obstructionRule: Field<"never" | "always" | "shape">; }>>

Defined in: packages/blocks/src/components.ts:447

minecraft:chest_obstruction, whether a chest beneath the block can open.

---

collisionBox

const collisionBox: BlockComponentFactory<boolean | ShapeOf<{ origin: Field<Vector3>; size: Field<Vector3>; }> | readonly ShapeOf<{ origin: Field<Vector3>; size: Field<Vector3>; }>[]>

Defined in: packages/blocks/src/components.ts:244

minecraft:collision_box: off, one box, or up to sixteen.

---

connectionRule

const connectionRule: BlockComponentFactory<ShapeOf<{ acceptsConnectionsFrom: Field<"none" | "all" | "only_fences">; enabledDirections: Field<readonly ("north" | "south" | "west" | "east")[]>; }>>

Defined in: packages/blocks/src/components.ts:459

minecraft:connection_rule, which fences, walls, bars and panes connect to the block.

---

containerOpenSound

const containerOpenSound: BlockComponentFactory<string>

Defined in: packages/blocks/src/components.ts:593

The named sound played when the server opens this block's container screen.

---

craftingTable

const craftingTable: BlockComponentFactory<ShapeOf<{ craftingTags: Field<readonly string[]>; tableName: Field<string>; }>>

Defined in: packages/blocks/src/components.ts:259

minecraft:crafting_table, which turns the block into a crafting station.

---

customComponents

const customComponents: BlockComponentFactory<readonly string[]>

Defined in: packages/blocks/src/components.ts:360

minecraft:custom_components, the names a pack binds script components under. The runtime reads them as behavior names, because Mojang marked the script hook deprecated while its version 2 still needs two experimental toggles.

---

destroyTime

const destroyTime: BlockComponentFactory<number>

Defined in: packages/blocks/src/components.ts:551

minecraft:destroy_time, the pre-1.19.40 spelling of the mining time, in seconds.

---

destructibleByExplosion

const destructibleByExplosion: BlockComponentFactory<boolean | ShapeOf<{ explosionResistance: Field<number>; }>>

Defined in: packages/blocks/src/components.ts:191

minecraft:destructible_by_explosion, Detailed Resistance.json.

---

destructibleByMining

const destructibleByMining: BlockComponentFactory<boolean | ShapeOf<{ itemSpecificSpeeds: Field<readonly ShapeOf<{ destroySpeed: Field<number>; item: Field<unknown>; }>[]>; secondsToDestroy: Field<number>; }>>

Defined in: packages/blocks/src/components.ts:170

minecraft:destructible_by_mining, Detailed Mining Speed.json.

---

destructionParticles

const destructionParticles: BlockComponentFactory<ShapeOf<{ particleCount: Field<number>; texture: Field<string>; tintMethod: Field<"none" | "default_foliage" | "birch_foliage" | "evergreen_foliage" | "dry_foliage" | "grass" | "water">; }>>

Defined in: packages/blocks/src/components.ts:428

minecraft:destruction_particles, the texture the break effect uses.

---

displayName

const displayName: BlockComponentFactory<string>

Defined in: packages/blocks/src/components.ts:256

minecraft:display_name, the localization key shown in the inventory.

---

embeddedVisual

const embeddedVisual: BlockComponentFactory<ShapeOf<{ geometry: Field<string | ShapeOf<{ boneVisibility: Field<Readonly<Record<string, unknown>>>; culling: Field<string>; cullingLayer: Field<string>; cullingShape: Field<string>; identifier: Field<string>; nWayVisualRotation: Field<ShapeOf<{ x: Field<...>; y: Field<...>; z: Field<...>; }>>; uvLock: Field<boolean | readonly string[]>; }>>; materialInstances: Field<Readonly<Record<string, string | ShapeOf<{ alphaMaskedTint: Field<boolean>; ambientOcclusion: Field<number>; faceDimming: Field<boolean>; isotropic: Field<boolean>; renderMethod: Field<... | ... | ... | ... | ... | ... | ... | ...>; texture: Field<string>; tintMethod: Field<... | ... | ... | ... | ... | ... | ...>; }>>>>; }>>

Defined in: packages/blocks/src/components.ts:372

minecraft:embedded_visual, the model shown inside a flower pot.

---

entityFallOn

const entityFallOn: BlockComponentFactory<ShapeOf<{ minFallDistance: Field<number>; }>>

Defined in: packages/blocks/src/components.ts:318

minecraft:entity_fall_on, the fall distance that reaches onEntityFallOn.

---

explosionResistance

const explosionResistance: BlockComponentFactory<number>

Defined in: packages/blocks/src/components.ts:554

minecraft:explosion_resistance, the pre-1.19.40 spelling of the blast resistance.

---

flammable

const flammable: BlockComponentFactory<boolean | ShapeOf<{ catchChanceModifier: Field<number>; destroyChanceModifier: Field<number>; lavaFlammable: Field<"never" | "always">; }>>

Defined in: packages/blocks/src/components.ts:213

minecraft:flammable, Detailed Flammable.json.

---

flowerPottable

const flowerPottable: BlockComponentFactory<ShapeOf<{ }>>

Defined in: packages/blocks/src/components.ts:495

minecraft:flower_pottable, which lets the block go in a flower pot.

---

friction

const friction: BlockComponentFactory<number>

Defined in: packages/blocks/src/components.ts:201

minecraft:friction. Mojang's schema caps this at 0.9, which is why the server's own friction table is a separate, Java-sourced column: blue ice is 0.989 and does not fit here.

---

geometryComponent

const geometryComponent: BlockComponentFactory<string | ShapeOf<{ boneVisibility: Field<Readonly<Record<string, unknown>>>; culling: Field<string>; cullingLayer: Field<string>; cullingShape: Field<string>; identifier: Field<string>; nWayVisualRotation: Field<ShapeOf<{ x: Field<string>; y: Field<string>; z: Field<string>; }>>; uvLock: Field<boolean | readonly string[]>; }>>

Defined in: packages/blocks/src/components.ts:238

minecraft:geometry, the model the client draws.

---

instrumentSound

const instrumentSound: BlockComponentFactory<ShapeOf<{ down: Field<"note.harp" | "note.bd" | "note.snare" | "note.hat" | "note.bassattack" | "note.flute" | "note.bell" | "note.guitar" | "note.chime" | "note.xylophone" | "note.iron_xylophone" | "note.cow_bell" | "note.didgeridoo" | "note.bit" | "note.banjo" | "note.pling" | "note.trumpet" | "note.trumpet_exposed" | "note.trumpet_weathered" | "note.trumpet_oxidized" | "note.zombie" | "note.skeleton" | "note.creeper" | "note.enderdragon" | "note.witherskeleton" | "note.piglin" | "note.none" | undefined>; up: Field<"note.harp" | "note.bd" | "note.snare" | "note.hat" | "note.bassattack" | "note.flute" | "note.bell" | "note.guitar" | "note.chime" | "note.xylophone" | "note.iron_xylophone" | "note.cow_bell" | "note.didgeridoo" | "note.bit" | "note.banjo" | "note.pling" | "note.trumpet" | "note.trumpet_exposed" | "note.trumpet_weathered" | "note.trumpet_oxidized" | "note.zombie" | "note.skeleton" | "note.creeper" | "note.enderdragon" | "note.witherskeleton" | "note.piglin" | "note.none" | undefined>; }>>

Defined in: packages/blocks/src/components.ts:438

minecraft:instrument_sound, the note block sound for the face played.

---

itemVisual

const itemVisual: BlockComponentFactory<ShapeOf<{ geometry: Field<string | ShapeOf<{ boneVisibility: Field<Readonly<Record<string, unknown>>>; culling: Field<string>; cullingLayer: Field<string>; cullingShape: Field<string>; identifier: Field<string>; nWayVisualRotation: Field<ShapeOf<{ x: Field<...>; y: Field<...>; z: Field<...>; }>>; uvLock: Field<boolean | readonly string[]>; }>>; materialInstances: Field<Readonly<Record<string, string | ShapeOf<{ alphaMaskedTint: Field<boolean>; ambientOcclusion: Field<number>; faceDimming: Field<boolean>; isotropic: Field<boolean>; renderMethod: Field<... | ... | ... | ... | ... | ... | ... | ...>; texture: Field<string>; tintMethod: Field<... | ... | ... | ... | ... | ... | ...>; }>>>>; }>>

Defined in: packages/blocks/src/components.ts:363

minecraft:item_visual, the model shown in the inventory when it differs.

---

leashable

const leashable: BlockComponentFactory<ShapeOf<{ offset: Field<Vector3>; }>>

Defined in: packages/blocks/src/components.ts:514

minecraft:leashable, where a lead attaches to the block.

---

lightDampening

const lightDampening: BlockComponentFactory<number>

Defined in: packages/blocks/src/components.ts:210

minecraft:light_dampening, how much light the block swallows, 0 to 15.

---

lightEmission

const lightEmission: BlockComponentFactory<number>

Defined in: packages/blocks/src/components.ts:204

minecraft:light_emission, 0 to 15.

---

liquidDetection

const liquidDetection: BlockComponentFactory<ShapeOf<{ detectionRules: Field<readonly ShapeOf<{ canContainLiquid: Field<boolean>; liquidType: Field<"water">; onLiquidTouches: Field<"blocking" | "broken" | "popped" | "no_reaction">; stopsLiquidFlowingFromDirection: Field<readonly ("down" | "up" | "north" | "south" | "west" | "east")[]>; useLiquidClipping: Field<boolean>; }>[]>; }>>

Defined in: packages/blocks/src/components.ts:381

minecraft:liquid_detection, one rule per liquid type.

---

loot

const loot: BlockComponentFactory<string>

Defined in: packages/blocks/src/components.ts:253

minecraft:loot, the pack-relative path of the block's loot table.

---

mapColor

const mapColor: BlockComponentFactory<string | ShapeOf<{ color: Field<string>; tintMethod: Field<"none" | "default_foliage" | "birch_foliage" | "evergreen_foliage" | "dry_foliage" | "grass" | "water">; }>>

Defined in: packages/blocks/src/components.ts:226

minecraft:map_color, a #RRGGBB string or a color with a tint method.

---

materialInstancesComponent

const materialInstancesComponent: BlockComponentFactory<Readonly<Record<string, string | ShapeOf<{ alphaMaskedTint: Field<boolean>; ambientOcclusion: Field<number>; faceDimming: Field<boolean>; isotropic: Field<boolean>; renderMethod: Field<"double_sided" | "blend" | "blend_to_opaque" | "opaque" | "alpha_test_to_opaque" | "alpha_test" | "alpha_test_single_sided" | "alpha_test_single_sided_to_opaque">; texture: Field<string>; tintMethod: Field<"none" | "default_foliage" | "birch_foliage" | "evergreen_foliage" | "dry_foliage" | "grass" | "water">; }>>>>

Defined in: packages/blocks/src/components.ts:241

minecraft:material_instances, the textures per face.

---

movable

const movable: BlockComponentFactory<ShapeOf<{ movementType: Field<"push" | "popped" | "push_pull" | "immovable">; sticky: Field<"none" | "same">; }>>

Defined in: packages/blocks/src/components.ts:472

minecraft:movable, how a piston treats the block.

---

onFallOn

const onFallOn: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:542

minecraft:on_fall_on, the pre-script spelling of onEntityFallOn.

---

onInteract

const onInteract: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:530

minecraft:on_interact, the pre-script spelling of onPlayerInteract.

---

onPlaced

const onPlaced: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:533

minecraft:on_placed, the pre-script spelling of onPlace.

---

onPlayerDestroyed

const onPlayerDestroyed: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:536

minecraft:on_player_destroyed, the pre-script spelling of onBreak.

---

onPlayerPlacing

const onPlayerPlacing: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:539

minecraft:on_player_placing, which ran before a placement was committed.

---

onStepOff

const onStepOff: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:548

minecraft:on_step_off, which has no script replacement in this hook map.

---

onStepOn

const onStepOn: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:545

minecraft:on_step_on, the pre-script spelling of onStepOn.

---

passThrough

const passThrough: Schema<unknown>

Defined in: packages/blocks/src/schema.ts:113

Accepts anything and hands it back unparsed, for a field only the client reads.

---

placementFilter

const placementFilter: BlockComponentFactory<ShapeOf<{ conditions: Field<readonly ShapeOf<{ allowedFaces: Field<readonly ("down" | "up" | "north" | "south" | "west" | "east")[]>; blockFilter: Field<readonly unknown[]>; }>[]>; }>>

Defined in: packages/blocks/src/components.ts:268

minecraft:placement_filter, the faces and neighbors a placement needs.

---

precipitationInteractions

const precipitationInteractions: BlockComponentFactory<ShapeOf<{ precipitationBehavior: Field<"none" | "obstruct_rain" | "obstruct_rain_accumulate_snow" | "snowlogging">; }>>

Defined in: packages/blocks/src/components.ts:481

minecraft:precipitation_interactions, how rain and snow treat the block.

---

queuedTicking

const queuedTicking: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:523

minecraft:queued_ticking. Internal and forbidden at the top level of a 1.26.20 file; it marks the block as reaching onTick in an older file.

---

randomOffset

const randomOffset: BlockComponentFactory<ShapeOf<{ x: Field<ShapeOf<{ range: Field<ShapeOf<{ max: Field<number>; min: Field<number>; }>>; steps: Field<number>; }>>; y: Field<ShapeOf<{ range: Field<ShapeOf<{ max: Field<number>; min: Field<number>; }>>; steps: Field<number>; }>>; z: Field<ShapeOf<{ range: Field<ShapeOf<{ max: Field<number>; min: Field<number>; }>>; steps: Field<number>; }>>; }>>

Defined in: packages/blocks/src/components.ts:501

minecraft:random_offset, the visual jitter applied per position.

---

randomTicking

const randomTicking: BlockComponentFactory<ShapeOf<{ }>>

Defined in: packages/blocks/src/components.ts:315

minecraft:random_ticking. Internal, and Blocks.json forbids it at the top level of a 1.26.20 file, so only an older file reaches this factory. It marks the block as reaching onRandomTick.

---

redstoneConductivity

const redstoneConductivity: BlockComponentFactory<ShapeOf<{ allowsWireToStepDown: Field<boolean>; redstoneConductor: Field<boolean>; }>>

Defined in: packages/blocks/src/components.ts:325

minecraft:redstone_conductivity, whether wire powers through and steps down onto the block.

---

redstoneConsumer

const redstoneConsumer: BlockComponentFactory<ShapeOf<{ minPower: Field<number>; propagatesPower: Field<boolean>; }>>

Defined in: packages/blocks/src/components.ts:334

minecraft:redstone_consumer, which reaches onRedstoneUpdate.

---

redstoneProducer

const redstoneProducer: BlockComponentFactory<ShapeOf<{ connectedFaces: Field<readonly ("down" | "up" | "north" | "south" | "west" | "east")[]>; power: Field<number>; stronglyPoweredFace: Field<"down" | "up" | "north" | "south" | "west" | "east" | undefined>; transformRelative: Field<boolean>; }>>

Defined in: packages/blocks/src/components.ts:344

minecraft:redstone_producer, the power the block emits and where.

---

replaceable

const replaceable: BlockComponentFactory<ShapeOf<{ }>>

Defined in: packages/blocks/src/components.ts:492

minecraft:replaceable, which lets another block be placed in the same position.

---

selectionBox

const selectionBox: BlockComponentFactory<boolean | ShapeOf<{ origin: Field<Vector3>; size: Field<Vector3>; }>>

Defined in: packages/blocks/src/components.ts:250

minecraft:selection_box: off, or one box.

---

sound

const sound: BlockComponentFactory<ShapeOf<{ sound: Field<string>; }>>

Defined in: packages/blocks/src/components.ts:511

minecraft:sound, the sound group the block uses.

---

support

const support: BlockComponentFactory<ShapeOf<{ shape: Field<"fence" | "stair">; }>>

Defined in: packages/blocks/src/components.ts:453

minecraft:support, the shape attached blocks treat the block as.

---

tags

const tags: BlockComponentFactory<readonly string[]>

Defined in: packages/blocks/src/components.ts:425

minecraft:tags, the block tags the engine and recipes filter on.

---

tick

const tick: BlockComponentFactory<ShapeOf<{ intervalRange: Field<readonly number[]>; looping: Field<boolean>; }>>

Defined in: packages/blocks/src/components.ts:301

minecraft:tick. The parameters say when the block ticks; the behavior attached to the block implements onTick.

---

transformation

const transformation: BlockComponentFactory<ShapeOf<{ rotation: Field<Vector3>; rotationPivot: Field<Vector3>; scale: Field<Vector3>; scalePivot: Field<Vector3>; translation: Field<Vector3>; }>>

Defined in: packages/blocks/src/components.ts:286

minecraft:transformation, the visual rotation, scale and translation.

---

unitCube

const unitCube: BlockComponentFactory<unknown>

Defined in: packages/blocks/src/components.ts:498

minecraft:unit_cube, internal, which draws the block as a plain full cube.

---

vector3

const vector3: Schema<Vector3>

Defined in: packages/blocks/src/schema.ts:166

Accepts [x, y, z].

Functions

bedrockBlockDisplayNameOf()

bedrockBlockDisplayNameOf(identifier): string | undefined

Defined in: packages/blocks/src/displayNames.ts:17

The Bedrock localization key for one captured block.

Parameters

identifier

string

The namespaced Bedrock block identifier.

Returns

string | undefined

The translation key, or undefined when the block is not in the capture.

---

bedrockCollisionDefaultBoxesOf()

bedrockCollisionDefaultBoxesOf(identifier): readonly BedrockCollisionBox[] | undefined

Defined in: packages/blocks/src/geometry.ts:141

The captured collision boxes of a varying-shape block's default state.

An empty list means the default state does not collide. A full cube is returned explicitly so a caller can override it when another state is partial or non-colliding.

Parameters

identifier

string

The namespaced Bedrock block identifier.

Returns

readonly BedrockCollisionBox[] | undefined

The default state's exact shape, or undefined when the shape is fixed.

---

bedrockCollisionPermutationsOf()

bedrockCollisionPermutationsOf(identifier): readonly BedrockCollisionPermutation[]

Defined in: packages/blocks/src/geometry.ts:152

The captured collision-box overrides for states whose shape differs from the default.

Each condition selects the state values that share the listed boxes. An empty box list means minecraft:collision_box: false for those states.

Parameters

identifier

string

The namespaced Bedrock block identifier.

Returns

readonly BedrockCollisionPermutation[]

The varying state shapes, or an empty list when the block's shape is fixed or uncaptured.

---

bedrockCollisionTopOf()

bedrockCollisionTopOf(identifier, runtimeId?): number | undefined

Defined in: packages/blocks/src/geometry.ts:99

How high a body standing in this block's cell would be held up, in blocks.

One number per state: the height of the lowest collision surface above the bottom of its own cell. 0 is a block you walk straight through, 1 an ordinary cube, 0.5 a slab or the step of a stair, 1.5 a fence - half a block taller than it looks, which is the entire point of a fence.

The lowest surface rather than the tallest, because the question is what holds a body up and what it has to get its feet over. A stair is a bottom slab with a quarter on top, and 0.5 is the part a mob meets.

The state matters for exactly the blocks you would expect, and the runtime id is how one is named: which half a slab fills, how deep the snow is, whether the gate is open.

Parameters

identifier

string

The namespaced block identifier.

runtimeId?

number

The state's runtime id, when the caller has it.

Returns

number | undefined

The height, or undefined for a block the capture has no row for.

Example

bedrockCollisionTopOf('minecraft:oak_fence'); // 1.5
bedrockCollisionTopOf('minecraft:short_grass'); // 0

---

bedrockHasCollisionOf()

bedrockHasCollisionOf(identifier): boolean | undefined

Defined in: packages/blocks/src/geometry.ts:116

Whether any state of a block has collision geometry in Bedrock's captured block table.

A block with no collision in any state can safely declare minecraft:collision_box: false in the vanilla overlay. States whose collision changes need a permutation and are not represented by this block-level answer.

Parameters

identifier

string

The namespaced block identifier.

Returns

boolean | undefined

Whether a captured state has collision geometry, or undefined when uncaptured.

---

bedrockLiquidReactionOf()

bedrockLiquidReactionOf(identifier): LiquidReaction | undefined

Defined in: packages/blocks/src/geometry.ts:160

What a liquid flowing into this block's cell does to it.

Parameters

identifier

string

The namespaced block identifier.

Returns

LiquidReaction | undefined

The reaction, or undefined for a block the capture has no row for.

---

bedrockStaticCollisionBoxesOf()

bedrockStaticCollisionBoxesOf(identifier): readonly (readonly [number, number, number, number, number, number])[] | undefined

Defined in: packages/blocks/src/geometry.ts:127

The captured collision boxes when every state of a block shares one partial shape.

Full cubes use Bedrock's default component, blocks without collision use false, and blocks whose shape changes by state need a component permutation, so those cases return undefined. Coordinates are normalized to the block cell and ordered min X/Y/Z, then max X/Y/Z.

Parameters

identifier

string

The namespaced Bedrock block identifier.

Returns

readonly (readonly [number, number, number, number, number, number])[] | undefined

The shared partial shape, or undefined when the default, false, or a state permutation applies.

---

behaviorFor()

behaviorFor(identifier, archetype?): string

Defined in: packages/blocks/src/families.ts:342

The behavior name for one block identifier.

Parameters

identifier

string

Namespaced, such as minecraft:oak_stairs.

archetype?

string

The block_archetype the block's own definition declares, which wins over the identifier because Mojang already decided the family there.

Returns

string

---

componentsForPermutation()

componentsForPermutation(document, mask): readonly ComponentEntry[]

Defined in: packages/blocks/src/permutations.ts:73

The component list for one state: the base components, then the components of each matching permutation in declaration order, with the later entry winning for a name that appears more than once.

That is Mojang's rule. A component a permutation sets keeps the position the base list gave it, so hook dispatch order does not change under a permutation, and every entry a permutation contributed carries override so a component that does bind handlers replaces the base ones rather than running after them.

Parameters

document

BlockDefinitionDocument

mask

PermutationMask

Returns

readonly ComponentEntry[]

---

conditionMatches()

conditionMatches(molang, condition, values): boolean

Defined in: packages/blocks/src/permutations.ts:25

Evaluates a block permutation's Molang condition against one state.

The docs limit a condition to query.block_state('name'), so the only scope member a condition needs is block.blockState. A condition that does not parse compiles to a constant 0 in @jsprismarine/molang, which is the engine's own content-error behavior, so it simply does not match.

Parameters

molang

Molang

condition

string

values

Readonly<Record<string, BlockStateValue>>

Every state value of the block, keyed by state name.

Returns

boolean

Whether the condition evaluated to a truthy number.

---

createBlockComponentRegistry()

createBlockComponentRegistry(): ComponentRegistry<BlockHooks>

Defined in: packages/blocks/src/components.ts:670

A registry holding every component in BLOCK_COMPONENTS.

Build one per content load and register a plugin's own components on it before resolving, since a name may only be registered once.

Returns

ComponentRegistry<BlockHooks>

---

decimal()

decimal(min?, max?): Schema<number>

Defined in: packages/blocks/src/schema.ts:27

Accepts a finite number within an inclusive range.

Parameters

min?

number = Number.NEGATIVE_INFINITY

max?

number = Number.POSITIVE_INFINITY

Returns

Schema<number>

---

either()

either<A, B>(first, second): Schema<A | B>

Defined in: packages/blocks/src/schema.ts:103

Tries each schema in order and takes the first that accepts.

Type Parameters

A

A

B

B

Parameters

first

Schema<A>

second

Schema<B>

Returns

Schema<A | B>

---

field()

field<P>(key, schema, fallback): Field<P>

Defined in: packages/blocks/src/schema.ts:126

Declares an optional field and the default Mojang's schema documents for it.

Type Parameters

P

P

Parameters

key

string

schema

Schema<P>

fallback

P

Returns

Field<P>

---

flattenBlockStates()

flattenBlockStates(resolved, exceptions?): BlockTable

Defined in: packages/blocks/src/flatten.ts:101

Precomputes the properties the tick loop, the lighting engine and the explosion code read, as one typed array per column indexed by the dense runtime id.

This is Dragonfly's Finalize idea as @jsprismarine/content's flatten implements it: the hot path reads an array slot instead of asking a type.

Parameters

resolved

BlockResolveResult

exceptions?

readonly FlattenException[] = []

Reviewed rows for an id a column has no value for and no default covers. An exception that matches nothing fails the build.

Returns

BlockTable

Throws

On a value the column kind cannot hold, an id with neither a value nor an exception, or an unused exception.

---

generateVanillaOverlay()

generateVanillaOverlay(properties, identifiers): OverlayPack

Defined in: packages/blocks/src/overlay.ts:238

Builds the jsprismarine_vanilla overlay: a Bedrock behavior pack that declares one block definition for every block in the palette.

The Bedrock-expressible properties become real Bedrock components with the values bedrockBlockPropertiesOf publishes. The rest go in jsprismarine:block_properties, this project's own component, because Bedrock's grammar has no field for them: friction above 0.9, random ticking, the correct-tool requirement, and the piston reaction at Java's precision. The behavior family comes from the identifier, which is the same mechanism as Mojang's block_archetype and produces the same names for the families Mojang already named.

Parameters

properties

BlockPropertySource

Where each block's Java-sourced row comes from.

identifiers

readonly string[]

Every block to declare, such as the identifiers of vanillaBlockPalette().entries. The output order follows this list.

Returns

OverlayPack

Every file to write, plus the reviewed exception list and the friction clamps.

---

integer()

integer(min?, max?): Schema<number>

Defined in: packages/blocks/src/schema.ts:36

Accepts a whole number within an inclusive range.

Parameters

min?

number = Number.NEGATIVE_INFINITY

max?

number = Number.POSITIVE_INFINITY

Returns

Schema<number>

---

isRecord()

isRecord(value): value is Record<string, unknown>

Defined in: packages/blocks/src/schema.ts:18

Whether a value is a plain JSON object rather than an array or null.

Parameters

value

unknown

Returns

value is Record<string, unknown>

---

isWashedAway()

isWashedAway(identifier): boolean

Defined in: packages/blocks/src/geometry.ts:178

Whether a liquid takes this block's place rather than being dammed by it.

True for the 197 blocks a liquid pops, breaks or shares a cell with: every crop, carpet, rail, sapling, torch, coral and flower, the snow layers, and air and the liquids themselves. Vanilla drowns plants rather than damming water behind them, which is what stops a field of wheat holding back a river.

Parameters

identifier

string

The namespaced block identifier.

Returns

boolean

Whether liquid flows into it. False for a block outside the capture.

---

list()

list<P>(item, limits?): Schema<readonly P[]>

Defined in: packages/blocks/src/schema.ts:70

Accepts an array whose every element parses, within an optional length range.

Type Parameters

P

P

Parameters

item

Schema<P>

limits?

LengthLimits = {}

Returns

Schema<readonly P[]>

---

oneOf()

oneOf<V>(values): Schema<V[number]>

Defined in: packages/blocks/src/schema.ts:54

Accepts one of a declared set of names, keeping the literal type.

Type Parameters

V

V extends readonly string[]

Parameters

values

V

Returns

Schema<V[number]>

---

parseBlockDefinition()

parseBlockDefinition(data, source): BlockParseResult

Defined in: packages/blocks/src/definition.ts:290

Parses one Bedrock block definition file.

format_version dispatch runs first: the newest schema at or below the file's version decides whether states, traits and permutations are read and which component names belong to that version. Anything the schema does not accept is dropped and reported rather than thrown, so one bad file cannot stop a pack load.

Parameters

data

unknown

The file's parsed JSON, from the lenient parser or JSON.parse.

source

BlockParseSource

Returns

BlockParseResult

The document, or document: undefined when the file carries no minecraft:block.description.identifier to register it under.

---

permutationsFor()

permutationsFor(document, values, molang, compiledConditions?): PermutationMask

Defined in: packages/blocks/src/permutations.ts:52

Every permutation of a definition that matches one state, in declaration order.

Parameters

document

BlockDefinitionDocument

values

Readonly<Record<string, BlockStateValue>>

molang

Molang

compiledConditions?

readonly CompiledMolang[] = ...

Optional expressions compiled once per definition, in permutation order.

Returns

PermutationMask

---

requiredField()

requiredField<P>(key, schema): Field<P>

Defined in: packages/blocks/src/schema.ts:129

Declares a field the component cannot parse without.

Type Parameters

P

P

Parameters

key

string

schema

Schema<P>

Returns

Field<P>

---

resolveBlocks()

resolveBlocks(definitions, options?): BlockResolveResult

Defined in: packages/blocks/src/types.ts:268

Resolves block definitions into types and per-state handles.

Each definition parses under the schema its format_version selects, takes its states from its own description.states and traits or, when it declares none as every vanilla file does, from the captured palette. Then every state is grouped by which permutations match it, and one content type is resolved per group, so a block with no permutations costs one resolve however many states it has.

Parameters

definitions

Iterable<Definition>

As @jsprismarine/packs produced them; data is the file's parsed JSON.

options?

BlockResolveOptions = {}

Returns

BlockResolveResult

Throws

In strict mode, when any diagnostic is reported.

---

schemaFor()

schemaFor(version): BlockSchema

Defined in: packages/blocks/src/definition.ts:118

Picks the schema a file's format_version reads under.

Parameters

version

FormatVersion

Returns

BlockSchema

---

shape()

shape<F>(fields): Schema<ShapeOf<F>>

Defined in: packages/blocks/src/schema.ts:139

Builds a schema for a JSON object from its fields, renaming each snake-case key to the camel-case name the parameters are read under.

Type Parameters

F

F extends Record<string, Field<unknown>>

Parameters

fields

F

Returns

Schema<ShapeOf<F>>

---

table()

table<P>(value_, maxProperties?): Schema<Readonly<Record<string, P>>>

Defined in: packages/blocks/src/schema.ts:87

Accepts an object whose every value parses, keyed by whatever names it has.

Type Parameters

P

P

Parameters

value_

Schema<P>

maxProperties?

number = Number.POSITIVE_INFINITY

Returns

Schema<Readonly<Record<string, P>>>

---

text()

text(maxLength?): Schema<string>

Defined in: packages/blocks/src/schema.ts:45

Accepts a string no longer than the limit Mojang's schemas put on it.

Parameters

maxLength?

number = 256

Returns

Schema<string>

---

traitStateDomains()

traitStateDomains(palette): ReadonlyMap<string, BlockStateDefinition>

Defined in: packages/blocks/src/traits.ts:62

The value domain of every state a trait can add.

Most trait states also occur in the vanilla palette. The two newer states are kept here because no vanilla block declares them: sixteen-way rotation is 0 through 15, and a multi-block part is 0 through 3.

Parameters

palette

BlockPalette

The palette whose other intrinsic state domains are used.

Returns

ReadonlyMap<string, BlockStateDefinition>

State name to its definition, including trait-only states.

---

vanillaBlockPalette()

vanillaBlockPalette(): BlockPalette

Defined in: packages/blocks/src/state.ts:236

The captured Bedrock palette as a BlockPalette: 1477 blocks over 22079 states, from @jsprismarine/minecraft's generated catalog, which a Bedrock Dedicated Server was asked block by block rather than dumped from a third party.

Built once and reused, because nothing here is mutable.

Returns

BlockPalette