Interface BlockCustomComponent

Example: registerBlockComponent_v1.ts

import { system } from "@minecraft/server";

// Use world.beforeEvents.worldInitialize.subscribe if you're using @minecraft/server v1
system.beforeEvents.startup.subscribe((initEvent) => {
   initEvent.blockComponentRegistry.registerCustomComponent("custom:block", {
       beforeOnPlayerPlace: (event) => {
           const { player, block, face, permutationToPlace, dimension } = event;
           event.cancel = true; // include this if canceling block placement
           // Your code here
       },
       onEntityFallOn: (event) => {
           const { entity, block, fallDistance, dimension } = event;
           // Your code here
       },
       onPlace: (event) => {
           const { block, dimension, previousBlock } = event;
           // Your code here
       },
       onPlayerBreak: (event) => {
           const { player, block, dimension, brokenBlockPermutation } = event;
           // Your code here
       },
       onPlayerInteract: (event) => {
           const { player, block, dimension, face, faceLocation } = event;
           // Your code here
       },
       onRandomTick: (event) => {
           const { block, dimension } = event;
           // Your code here
       },
       onStepOff: (event) => {
           const { entity, block, dimension } = event;
           // Your code here
       },
       onStepOn: (event) => {
           const { entity, block, dimension } = event;
           // Your code here
       },
       onTick: (event) => {
           const { block, dimension } = event;
           // Your code here
       },
   });
});
Copy

Example: registerBlockComponent_v2.ts

import {
   system,
   BlockComponentPlayerPlaceBeforeEvent,
   BlockComponentEntityFallOnEvent,
   BlockComponentOnPlaceEvent,
   BlockComponentPlayerBreakEvent,
   BlockComponentPlayerInteractEvent,
   BlockComponentRandomTickEvent,
   BlockComponentStepOffEvent,
   BlockComponentStepOnEvent,
   BlockComponentTickEvent,
   CustomComponentParameters,
} from "@minecraft/server";

system.beforeEvents.startup.subscribe((startupEvent) => {
   startupEvent.blockComponentRegistry.registerCustomComponent("custom:block", {
       beforeOnPlayerPlace: (event: BlockComponentPlayerPlaceBeforeEvent, params: CustomComponentParameters) => {
           const { player, block, face, permutationToPlace, dimension } = event;
           event.cancel = true; // include this if canceling block placement
           // Your code here
       },
       onEntityFallOn: (event: BlockComponentEntityFallOnEvent, params: CustomComponentParameters) => {
           const { entity, block, fallDistance, dimension } = event;
           // Your code here
       },
       onPlace: (event: BlockComponentOnPlaceEvent, params: CustomComponentParameters) => {
           const { block, dimension, previousBlock } = event;
           // Your code here
       },
       onPlayerBreak: (event: BlockComponentPlayerBreakEvent, params: CustomComponentParameters) => {
           const { player, block, dimension, brokenBlockPermutation } = event;
           // Your code here
       },
       onPlayerInteract: (event: BlockComponentPlayerInteractEvent, params: CustomComponentParameters) => {
           const { player, block, dimension, face, faceLocation } = event;
           // Your code here
       },
       onRandomTick: (event: BlockComponentRandomTickEvent, params: CustomComponentParameters) => {
           const { block, dimension } = event;
           // Your code here
       },
       onStepOff: (event: BlockComponentStepOffEvent, params: CustomComponentParameters) => {
           const { entity, block, dimension } = event;
           // Your code here
       },
       onStepOn: (event: BlockComponentStepOnEvent, params: CustomComponentParameters) => {
           const { entity, block, dimension } = event;
           // Your code here
       },
       onTick: (event: BlockComponentTickEvent, params: CustomComponentParameters) => {
           const { block, dimension } = event;
           // Your code here
       },
   });
});
Copy

Custom Components V1

Custom Components V1 is the original implementation of custom components in Minecraft. It allows you to define custom behaviors and properties for blocks, items, and entities using JSON components.

For script implementation, check out registerBlockComponent_v1.ts

JSON Example:

{
    "components": {
        "minecraft:custom_components": [
            "my_custom_component:name"
        ]
    }
}
Copy

Custom Components V2

Custom Components V2 is a new experiment which must be enabled along with the "Beta APIs" experiment to use the new features for custom components. With the experiment enabled:

• minecraft:custom_components is deprecated in favor of flattened custom components
• Custom components now support parameters

Flattening

In the previous version of custom components, components had to be listed inside the minecraft:custom_components component. This is no longer required and the minecraft:custom_components component is deprecated. Instead, you can write your custom components similar to any other Minecraft component. For example:

{
    "components": {
        "minecraft:loot": "...",
        "minecraft:collision_box": {
            "enabled": true
        },
        "my_custom_component:name": {},
        "my_custom_component:another_component": {}
    }
}
Copy

Parameters

Along with flattening a custom component in JSON, you also can provide parameters to the component. The script bindings for custom components have been upgraded to support a second parameter, CustomComponentParameters, which grants access to the JSON parameter list for your component. The following example shows how to use custom component parameters in script:

{
    "components": {
        "some_component:name": {
            "first": "hello",
            "second": 4,
            "third": [
                "test",
                "example"
            ]
        }
    }
}
Copy

type SomeComponentParams = {
    first?: string;
    second?: number;
    third?: string[];
};

system.beforeEvents.startup.subscribe(init => {
    init.blockComponentRegistry.registerCustomComponent('some_component:name', {
        onStepOn: (e : BlockComponentStepOnEvent, p : CustomComponentParameters) : {
            let params = p.params as SomeComponentParams;
            ...
        }
    });
});
Copy