Useful Links and Reference Patterns

Every add-on starts with two manifest files: one in the Behavior Pack and one in the Resource Pack. By default, these two packs are completely unaware of each other. A player can apply the Behavior Pack to a world and forget the Resource Pack, resulting in invisible entities or checkerboard blocks. To prevent this, you create a hard link between the packs using the dependencies array inside the manifest.

A dependency link requires the exact header UUID and version array of the target pack. Notice that you link to the header UUID, never the module UUID. When a Behavior Pack lists a Resource Pack UUID in its dependencies, Minecraft will automatically activate the Resource Pack whenever the Behavior Pack is added to a world, provided both packs are installed in the client cache.

Inside the exact same manifest, the dependencies array serves a second linking purpose: connecting your code to native Script API modules. Unlike pack-to-pack links which use a UUID key, script module links use the module_name key alongside a specific semantic version string.

{
  "format_version": 2,
  "header": {
    "name": "pack.name",
    "description": "pack.description",
    "uuid": "8a5b1e90-3c42-4f1a-9b11-029384756abc",
    "version": [1, 0, 0],
    "min_engine_version": [1, 20, 80]
  },
  "modules": [
    {
      "type": "data",
      "uuid": "1c2d3e4f-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
      "version": [1, 0, 0]
    },
    {
      "type": "script",
      "language": "javascript",
      "uuid": "9f8e7d6c-5b4a-3f2e-1d0c-9b8a7f6e5d4c",
      "entry": "scripts/main.js",
      "version": [1, 0, 0]
    }
  ],
  "dependencies": [
    {
      "uuid": "f0e1d2c3-b4a5-6978-8071-625344352617",
      "version": [1, 0, 0]
    },
    {
      "module_name": "@minecraft/server",
      "version": "1.10.0"
    }
  ]
}

Once the packs are linked at the manifest level, individual assets must be linked across the Behavior Pack and Resource Pack divide. Minecraft does not use file paths or folder structures to match a server-side behavior definition to its client-side visuals. You can name your files whatever you like and nest them in sub-folders. The engine joins them solely through the description.identifier string.

This identifier must follow the namespace:name format, using lowercase letters, numbers, and underscores. The namespace is your custom project prefix, and it cannot be minecraft unless you are intentionally overriding a vanilla actor or block. When the server spawns an entity with a specific identifier, it broadcasts that exact string to the client. The client then searches its loaded Resource Packs for a client_entity file declaring the exact same description.identifier.

If there is a single character mismatch between the Behavior Pack identifier and the Resource Pack identifier, the link breaks. The entity will still exist in the world, take damage, and run its AI goals, but it will be completely invisible and silent because the client has no visual definition attached to that string.

After the client locates the correct client_entity file via its identifier, a second layer of linking takes over: shortnames. A client entity file acts as a switchboard. It pulls together geometries, textures, materials, animations, and animation controllers—all of which live in separate files with long, cumbersome identifiers—and assigns each one a local alias called a shortname.

When you define a texture in RP/entity/my_mob.entity.json, you map a shortname key (like "default") to the actual file path (like "textures/entity/my_mob"). When you define a geometry, you map a shortname key (like "default") to the full geometry identifier found inside the model file (like "geometry.custom.my_mob").

The render_controllers and scripts sections at the bottom of the client entity file never touch file paths or full geometry identifiers. They only read the shortnames you established higher up in the same file, or inside an external render controller file. This indirection allows a single render controller to work across dozens of different mobs, provided all of those mobs use the same shortnames (such as "default") for their base assets.

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "craft:copper_golem",
      "materials": {
        "default": "entity_alphatest"
      },
      "textures": {
        "default": "textures/entity/copper_golem/normal",
        "oxidized": "textures/entity/copper_golem/oxidized"
      },
      "geometry": {
        "default": "geometry.craft.copper_golem"
      },
      "animations": {
        "walk": "animation.craft.copper_golem.walk",
        "look": "animation.common.look_at_target"
      },
      "scripts": {
        "animate": [
          "look",
          {
            "walk": "query.modified_move_speed > 0.1"
          }
        ]
      },
      "render_controllers": [
        "controller.render.default"
      ]
    }
  }
}

Unlike entities, which reference texture file paths directly inside their client definition files, blocks and items rely on intermediate texture atlas files. This is a common stumbling block for developers moving from entity creation to block creation. You cannot write a raw texture path inside a behavior block's minecraft:material_instances component or an item's minecraft:icon component.

Instead, you must register a texture shortname inside RP/textures/terrain_texture.json for blocks, or RP/textures/item_texture.json for items. Inside these atlas files, you define a custom string key under the texture_data object and point its textures property to the actual image path relative to the Resource Pack root, omitting the .png extension.

Once the atlas entry exists, you use that custom string key inside your Behavior Pack block or item file. This extra linking step exists so the game engine can stitch all block and item textures into massive single texture sheets in memory during startup, optimizing rendering performance.

{
  "resource_pack_name": "craft_notes_rp",
  "texture_name": "atlas.terrain",
  "padding": 8,
  "num_mip_levels": 4,
  "texture_data": {
    "craft_ basalt_bricks": {
      "textures": "textures/blocks/basalt_bricks"
    },
    "craft_basalt_pillar_top": {
      "textures": "textures/blocks/basalt_pillar_top"
    }
  }
}

Geometry linking works identically for both entities and custom blocks. Inside any file in the RP/models/entity/ or RP/models/blocks/ folders, the model's true name is defined in its description.identifier string, which must begin with the prefix geometry. followed by your custom name. The actual filename of the .geo.json file is completely ignored by the game engine.

For blocks using the modern Behavior Pack components, you link directly to this geometry identifier inside the minecraft:geometry component without needing a client entity switchboard. However, a secondary link happens inside the model itself: bone visibility and material mapping.

In a block model, the names of the cubes or groups do not control textures; instead, each cube specifies a material instance name in its face definitions (or inherits one). In your BP/blocks/ file, the keys inside minecraft:material_instances must match the material names exported by the geometry, or use the wildcard * to catch all unassigned faces. For entities, bone names act as the link target for animations. If an animation file tries to rotate a bone named head, and the geometry file calls that bone Head with a capital H, the animation link fails.

{
  "format_version": "1.20.80",
  "minecraft:block": {
    "description": {
      "identifier": "craft:basalt_pillar"
    },
    "components": {
      "minecraft:geometry": "geometry.craft.pillar",
      "minecraft:material_instances": {
        "*": {
          "texture": "craft_ basalt_bricks",
          "render_method": "opaque"
        },
        "ends": {
          "texture": "craft_basalt_pillar_top",
          "render_method": "opaque"
        }
      },
      "minecraft:destructible_by_mining": {
        "seconds_to_destroy": 2.0
      }
    }
  }
}

In modern Bedrock development, the old Holiday Creator Features event chains have been replaced by a direct link between JSON definitions and TypeScript/JavaScript execution: Custom Components. This link bridges static data files in BP/blocks/ or BP/items/ with live code running in BP/scripts/.

To establish this link, your script must listen to the worldInitialize (or startup in newer betas) before-event and register a custom component using a namespaced string identifier. You provide an object containing lifecycle callbacks like onPlayerInteract, onTick, or onStepOn.

Once registered in script, that exact namespaced string is placed inside the minecraft:custom_components array of a block or item JSON file. When the world loads, the engine validates that every string listed in the JSON array has a corresponding registration in the script bundle. If the script fails to register the name during initialization, the block or item will throw a content log error and lose its custom functionality.

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

world.beforeEvents.worldInitialize.subscribe((eventData) => {
  eventData.blockComponentRegistry.registerCustomComponent(
    "craft:pillar_interact",
    {
      onPlayerInteract(e) {
        const { block, player } = e;
        if (!player) return;
        player.sendMessage(`Touched pillar at ${block.location.x}, ${block.location.y}, ${block.location.z}`);
      }
    }
  );
});

The final link in any polished add-on is connecting internal identifiers to human-readable text in RP/texts/en_US.lang. Without this link, players will see raw translation keys like tile.craft:basalt_pillar.name or item.craft:copper_wrench.name in their inventory.

Unlike JSON files, .lang files use a strict key=value format per line with no spaces around the equals sign. The engine generates the expected key automatically from your Behavior Pack identifier based on the asset type. Knowing the exact prefix and suffix pattern the engine expects for each asset type is essential, as the game does not warn you when a translation key is missing—it simply prints the raw key to the screen.

pack.name=Craft Notes Add-On
pack.description=Reference patterns for linking pack assets.

entity.craft:copper_golem.name=Copper Golem
item.spawn_egg.entity.craft:copper_golem.name=Spawn Copper Golem
tile.craft:basalt_pillar.name=Basalt Pillar
item.craft:copper_wrench=Copper Wrench

Applies to Minecraft Bedrock 1.20.80 and newer. Manifest linking, client entities, texture atlases, and .lang patterns are stable back to 1.16.0. Block and item Custom Components are stable in 1.21.0+ and do not require any experimental toggles when using current format versions.

Read out of the game itself, so the ids match the version you are building for.