Addons

Basalt reads custom items and entities written in the vanilla behaviour-pack format. You do not need to convert anything: drop the pack’s files into a folder under plugins/ and restart.

Addons and plugins share the plugins/ folder, and one folder can be both: JSON content for the items and mobs, and a scripts/ folder for the logic.

Install an addon

Give the addon a folder of its own inside plugins/:

plugins/
  my-addon/
    items/              custom items, in any subfolder
    entities/           custom entities
    loot_tables/        loot tables the entities use
    resource_pack/      textures and models, sent to players

If you have a complete behaviour pack and resource pack, you can keep the behaviour pack together instead:

plugins/
  my-addon/
    behavior_pack/
      items/
      entities/
      loot_tables/
    resource_pack/

Then restart Basalt. Addon content is read once at startup; /reload does not pick up new items or entities.

When content loads, the log says how much:

Addons Registered: 3 items, 1 entities, 2 loot tables

Rules

• Every item and entity needs an identifier with your own namespace, such as myaddon:ruby. The minecraft: namespace is reserved.
• An identifier can be used once. A second file with the same identifier is skipped.
• Files may contain // and /* */ comments, as vanilla allows.
• A file that cannot be read, or breaks one of these rules, is skipped with a warning that names it. The rest still load.
• Addon folders load in name order.

Textures and models

The client needs a resource pack to draw custom content. Put it in the addon’s resource_pack/ folder and Basalt sends it to players as they join. See Resource packs.

Custom items

Custom items appear in the creative inventory when they have a menu_category, work with /give, and are suggested in command auto-complete unless hidden.

{
  "format_version": "1.21.0",
  "minecraft:item": {
    "description": {
      "identifier": "myaddon:ruby_apple",
      "menu_category": { "category": "items" }
    },
    "components": {
      "minecraft:icon": "ruby_apple",
      "minecraft:display_name": { "value": "Ruby Apple" },
      "minecraft:max_stack_size": 16,
      "minecraft:food": { "nutrition": 6, "saturation_modifier": "good", "can_always_eat": true },
      "minecraft:use_modifiers": { "use_duration": 1.6 }
    }
  }
}

Supported item components:

Component	What Basalt does with it
description.menu_category	category (construction, nature, equipment, items, none), group and is_hidden_in_commands. An item whose group matches a vanilla creative group joins it; otherwise it gets a group of its own after vanilla’s.
minecraft:max_stack_size	The stack size, enforced by Basalt. Wearable items always stack to 1.
minecraft:icon	The texture, as a name or textures.default.
minecraft:display_name	The name shown.
minecraft:durability	max_durability. The item wears by 1 per hit and per block broken that took time, and breaks at zero.
minecraft:damage	Added to melee damage, like a vanilla weapon.
minecraft:food	nutrition, saturation_modifier (a number or vanilla’s names), can_always_eat, using_converts_to.
minecraft:use_modifiers	use_duration (how long eating takes) and movement_modifier.
minecraft:cooldown	category and duration. Uses are refused until the cooldown ends.
minecraft:wearable	slot and protection. In an armour slot it counts as armour.
minecraft:allow_off_hand	Lets the item go in the off hand.
minecraft:fire_resistant	A dropped item survives fire and lava.
minecraft:custom_components	Using the item runs the onUse handler a plugin registered under each listed id. Plugins register them with event.itemComponentRegistry.registerCustomComponent in a world.beforeEvents.worldLoad handler.
minecraft:use_animation, minecraft:hand_equipped, minecraft:glint, minecraft:foil, minecraft:enchantable, minecraft:tags, minecraft:rarity, minecraft:hover_text_color, minecraft:liquid_clipped, minecraft:swing_duration, minecraft:stacked_by_data, minecraft:should_despawn	Passed to the client, which handles the look and feel.

Custom entities

Custom entities run on the same mob engine as Basalt’s vanilla mobs: they walk, sense, fight, take damage, drop loot and are saved with their chunk.

Spawn one with /summon <identifier> if its definition sets is_summonable, or from a plugin with dimension.spawnEntity. An entity with is_spawnable gets a spawn egg.

Supported components:

Component	Effect
minecraft:health	Health (max, otherwise value).
minecraft:collision_box	Width and height.
minecraft:movement	Movement speed.
minecraft:attack	Melee damage. A range hits for its middle value.
minecraft:loot	The loot table rolled on death.
minecraft:type_family	Families, available to plugins.
minecraft:physics	has_gravity.
minecraft:scale, minecraft:knockback_resistance, minecraft:fire_immune	Size, resistance to knockback, and immunity to fire.
minecraft:ageable	Babies grow up after duration.
minecraft:burns_in_daylight	Burns in sunlight.
minecraft:damage_sensor	Turning fall damage off.
minecraft:experience_reward	The on_death expression, evaluated on death.
minecraft:behavior.random_stroll	Wandering, at its speed. Without it the mob stays put.
minecraft:behavior.look_at_player	Accepted. Every mob looks around as vanilla mobs do.
minecraft:behavior.panic	Runs when hurt, at its speed.
minecraft:behavior.melee_attack, minecraft:behavior.melee_box_attack	Fights in melee, at its speed.
minecraft:behavior.nearest_attackable_target	Hunts players within within_radius when its filters name players.
minecraft:behavior.hurt_by_target	Turns on whoever hurt it, if its entity_types allow them.
minecraft:behavior.tempt	Follows a player holding one of its items.
minecraft:behavior.random_swim, minecraft:behavior.random_fly, minecraft:behavior.random_hover	Wandering in water, in the air, or hovering.
minecraft:behavior.leap_at_target	Leaps at its target.
minecraft:behavior.flee_sun, minecraft:behavior.restrict_sun	Looks for shade in daylight.

Component groups and events

component_groups and events work as they do in vanilla. An event can add and remove component groups, set entity properties, play a sound, and choose between a sequence or a randomize, each guarded by filters in vanilla’s test / subject / operator / value form. Events fire from minecraft:entity_spawned, timers, sensors, on_death and similar triggers.

When a mob’s groups change, its components are worked out again, so health, speed and behaviours can change while it is alive.

Molang

Molang is evaluated wherever vanilla expects a number, such as experience rewards, chances and property defaults. Numbers, 'text', query.* and math.* calls, arithmetic, comparisons and a ? b : c are supported.

variable.*, temp.* and context.* read as 0, and Molang in string or animation contexts is not evaluated.

Loot tables

Put loot tables under loot_tables/ and refer to them from minecraft:loot by their path in the pack, for example loot_tables/entities/golem.json.

Part	Supported
Pools	rolls as a number or a range
Entries	Weighted item, empty and loot_table
Functions	set_count, set_data, set_data_from_color_index, furnace_smelt, looting_enchant, set_name, set_lore, enchant_randomly, enchant_with_levels, specific_enchants
Conditions	killed_by_player, random_chance, random_chance_with_looting, random_difficulty_chance, on_fire

Not supported

• Custom blocks, recipes, biomes and features.
• Spawn rules. Custom mobs do not spawn naturally; summon them or spawn them from a plugin.
• Item components that need behaviour beyond the table above: digger, shooter, throwable, projectile, block_placer, repairable, fuel, record and storage_item.
• Entity components beyond the table above: rideable, breedable and tameable behaviours, and other goals. A mob with a melee attack but no target goal does not fight back when hit.
• Other loot functions, such as enchant_random_gear, set_potion and set_banner_details.
• Scripts inside a pack placed in resource_packs/. Scripts run only from a plugin folder in plugins/. See Your first plugin.

If an addon is removed, mobs of its types that were saved in the world are not loaded.