Skip to main content
Item definitions control custom item behavior (ItemTypeDefinition) and appearance (ItemTypeResourceDefinition) in Minecraft add-ons.

​
ItemTypeDefinition

ItemTypeDefinition manages item behavior pack files (BP/items/*.json), including components and events for item functionality.

​
Class Signature

class ItemTypeDefinition implements IManagedComponentSetItem, IDefinition {
  // Properties
  readonly id: string;
  readonly shortId?: string;
  readonly isLoaded: boolean;
  readonly behaviorPackFile?: IFile;
  readonly data?: IItemTypeBehaviorPack;
  readonly formatVersion?: string;
  
  // Component management
  getComponent(id: string): IManagedComponent | undefined;
  addComponent(id: string, componentOrData: any): ManagedComponent;
  removeComponent(id: string): void;
  ensureComponent(id: string, defaultData?: any): IManagedComponent;
  getComponents(): IManagedComponent[];
  getAllComponents(): IManagedComponent[];
  
  // Custom components
  getCustomComponentIds(): string[];
  async addCustomComponent(item: ProjectItem, name: string): Promise<void>;
  
  // Loading and persistence
  static async ensureOnFile(file: IFile, handler?): Promise<ItemTypeDefinition>;
  async load(): Promise<void>;
  persist(): boolean;
  
  // Utilities
  getFormatVersion(): number[] | undefined;
  async getFormatVersionIsCurrent(): Promise<boolean>;
  setFormatVersion(version: string): void;
  setBehaviorPackFormatVersion(version: string): void;
  static isVisualComponent(value: string): boolean;
}

​
Loading Item Definitions

import { ItemTypeDefinition } from 'minecraft-creator-tools';

// Load from file
const itemDef = await ItemTypeDefinition.ensureOnFile(file);

// Access item data
console.log('Item ID:', itemDef.id);
console.log('Format version:', itemDef.formatVersion);
console.log('Is loaded:', itemDef.isLoaded);

​
Working with Components

// Add components
itemDef.addComponent('minecraft:max_stack_size', {
  value: 64
});

itemDef.addComponent('minecraft:icon', {
  texture: 'my_item'
});

itemDef.addComponent('minecraft:display_name', {
  value: 'My Custom Item'
});

itemDef.addComponent('minecraft:durability', {
  max_durability: 100
});

// Get a component
const stackSize = itemDef.getComponent('minecraft:max_stack_size');
if (stackSize) {
  const max = stackSize.getProperty('value');
  console.log('Max stack size:', max);
}

// Ensure component exists
const glint = itemDef.ensureComponent('minecraft:glint', {
  value: true
});

// Remove component
itemDef.removeComponent('minecraft:glint');

// Get all components
const components = itemDef.getComponents();
for (const comp of components) {
  console.log('Component:', comp.id);
}

​
Custom Components

Items support custom components for advanced functionality: 
// Get custom component IDs
const customComps = itemDef.getCustomComponentIds();
console.log('Custom components:', customComps);
// Returns: ['custom:on_use', 'custom:on_hit']

// Add custom component with generated TypeScript
await itemDef.addCustomComponent(projectItem, 'custom:on_consume');
// Creates TypeScript file and registers component

​
Visual Components

Check if a component is visual-only: 
const isVisual = ItemTypeDefinition.isVisualComponent('minecraft:icon');
console.log('Is visual:', isVisual); // true

const isNotVisual = ItemTypeDefinition.isVisualComponent('minecraft:food');
console.log('Is visual:', isNotVisual); // false

// Visual components:
// - minecraft:icon
// - minecraft:display_name
// - minecraft:glint
// - minecraft:hover_text_color

​
Format Version Management

// Get format version
const version = itemDef.getFormatVersion();
console.log('Version:', version); // [1, 20, 0]

// Check if current
const isCurrent = await itemDef.getFormatVersionIsCurrent();

// Update format version
itemDef.setFormatVersion('1.21.0');
// or
itemDef.setBehaviorPackFormatVersion('1.21.0');

​
Item JSON Structure

{
  "format_version": "1.20.0",
  "minecraft:item": {
    "description": {
      "identifier": "custom:my_item"
    },
    "components": {
      "minecraft:icon": {
        "texture": "my_item"
      },
      "minecraft:display_name": {
        "value": "My Custom Item"
      },
      "minecraft:max_stack_size": {
        "value": 64
      },
      "minecraft:durability": {
        "max_durability": 100
      },
      "minecraft:damage": {
        "value": 5
      },
      "minecraft:hand_equipped": true,
      "minecraft:food": {
        "nutrition": 4,
        "saturation_modifier": 0.6,
        "can_always_eat": false
      }
    }
  }
}

​
ItemTypeResourceDefinition

ItemTypeResourceDefinition manages legacy resource pack item definitions (format version 1.10.0 and earlier). For modern items, visual properties are defined in the behavior pack.

​
Class Signature

class ItemTypeResourceDefinition implements IManagedComponentSetItem, IDefinition {
  // Properties
  readonly id: string;
  readonly shortId?: string;
  readonly isLoaded: boolean;
  readonly behaviorPackFile?: IFile;
  readonly data?: IItemTypeResourcePack;
  wrapper: IItemTypeWrapper | null;
  
  // Component management
  getComponent(id: string): IManagedComponent | undefined;
  addComponent(id: string, componentOrData: any): ManagedComponent;
  removeComponent(id: string): void;
  getComponents(): IManagedComponent[];
  getAllComponents(): IManagedComponent[];
  
  // Loading and persistence
  static async ensureOnFile(file: IFile, handler?): Promise<ItemTypeResourceDefinition>;
  async load(): Promise<void>;
  persist(): boolean;
  
  // Utilities
  getFormatVersion(): number[] | undefined;
  async getFormatVersionIsCurrent(): Promise<boolean>;
  setResourcePackFormatVersion(version: string): void;
}

​
Using Legacy Item Resources

import { ItemTypeResourceDefinition } from 'minecraft-creator-tools';

// Load legacy resource definition
const itemRes = await ItemTypeResourceDefinition.ensureOnFile(file);

console.log('Item ID:', itemRes.id);
console.log('Format version:', itemRes.getFormatVersion());

// Add visual components (legacy format)
itemRes.addComponent('minecraft:icon', {
  texture: 'my_item'
});

itemRes.addComponent('minecraft:render_offsets', {
  main_hand: {
    first_person: {
      scale: [0.5, 0.5, 0.5]
    }
  }
});

// Save
itemRes.persist();

​
Legacy vs Modern Format

Legacy Format (1.10.0 and earlier) 
{
  "format_version": "1.10.0",
  "minecraft:item": {
    "description": {
      "identifier": "custom:my_item"
    },
    "components": {
      "minecraft:icon": {
        "texture": "my_item"
      },
      "minecraft:render_offsets": "tools"
    }
  }
}
Modern Format (1.16.100+) 
{
  "format_version": "1.20.0",
  "minecraft:item": {
    "description": {
      "identifier": "custom:my_item"
    },
    "components": {
      "minecraft:icon": {
        "texture": "my_item"
      },
      "minecraft:display_name": {
        "value": "My Item"
      },
      "minecraft:max_stack_size": {
        "value": 64
      }
    }
  }
}
In modern format, all item properties (visual and functional) are defined in the behavior pack.

​
Common Item Components

​
Display Properties

// Icon texture
itemDef.addComponent('minecraft:icon', {
  texture: 'item_texture_name'
});

// Display name
itemDef.addComponent('minecraft:display_name', {
  value: 'Custom Item Name'
});

// Enchantment glint
itemDef.addComponent('minecraft:glint', {
  value: true
});

// Hover text color
itemDef.addComponent('minecraft:hover_text_color', {
  value: 'gold'
});

​
Functionality Components

// Stack size
itemDef.addComponent('minecraft:max_stack_size', {
  value: 16
});

// Durability
itemDef.addComponent('minecraft:durability', {
  max_durability: 250
});

// Damage
itemDef.addComponent('minecraft:damage', {
  value: 8
});

// Hand equipped
itemDef.addComponent('minecraft:hand_equipped', true);

// Foil (enchanted effect)
itemDef.addComponent('minecraft:foil', false);

​
Food Component

itemDef.addComponent('minecraft:food', {
  nutrition: 6,
  saturation_modifier: 0.8,
  can_always_eat: false,
  effects: [
    {
      name: 'regeneration',
      chance: 1.0,
      duration: 10,
      amplifier: 1
    }
  ]
});

​
Tool Components

// Digger (mining tool)
itemDef.addComponent('minecraft:digger', {
  use_efficiency: true,
  destroy_speeds: [
    {
      block: 'minecraft:dirt',
      speed: 6
    },
    {
      block: {
        tags: 'query.any_tag("stone", "metal")'
      },
      speed: 8
    }
  ]
});

// Weapon
itemDef.addComponent('minecraft:weapon', {
  on_hurt_entity: {
    event: 'custom:on_hit',
    target: 'holder'
  }
});

​
Projectile Component

itemDef.addComponent('minecraft:projectile', {
  projectile_entity: 'minecraft:arrow',
  minimum_critical_power: 1.25
});

itemDef.addComponent('minecraft:throwable', {
  do_swing_animation: true,
  max_draw_duration: 0.0,
  scale_power_by_draw_duration: false
});

​
Complete Example

import { ItemTypeDefinition } from 'minecraft-creator-tools';

// Load item definition
const itemDef = await ItemTypeDefinition.ensureOnFile(file);

// Set up item
itemDef.id = 'custom:energy_sword';
itemDef.setFormatVersion('1.21.0');

// Visual properties
itemDef.addComponent('minecraft:icon', {
  texture: 'energy_sword'
});

itemDef.addComponent('minecraft:display_name', {
  value: 'Energy Sword'
});

itemDef.addComponent('minecraft:glint', {
  value: true
});

// Functional properties
itemDef.addComponent('minecraft:max_stack_size', {
  value: 1
});

itemDef.addComponent('minecraft:durability', {
  max_durability: 500
});

itemDef.addComponent('minecraft:damage', {
  value: 12
});

itemDef.addComponent('minecraft:hand_equipped', true);

// Weapon behavior
itemDef.addComponent('minecraft:weapon', {
  on_hurt_entity: {
    event: 'custom:energy_discharge',
    target: 'holder'
  }
});

// Custom component for special effects
await itemDef.addCustomComponent(projectItem, 'custom:energy_system');

// Save
itemDef.persist();

console.log('Energy sword created successfully!');

​
Item Component Types

Common item component categories: Display Components
  • minecraft:icon - Item texture
  • minecraft:display_name - Display name
  • minecraft:glint - Enchantment glint effect
  • minecraft:hover_text_color - Tooltip color
Stack & Durability
  • minecraft:max_stack_size - Maximum stack size
  • minecraft:durability - Item durability
  • minecraft:repairable - Repair materials
Combat
  • minecraft:damage - Attack damage
  • minecraft:weapon - Weapon behavior
  • minecraft:projectile - Projectile behavior
  • minecraft:throwable - Throwable behavior
Tools
  • minecraft:digger - Mining/digging tool
  • minecraft:enchantable - Enchantment compatibility
Consumables
  • minecraft:food - Food properties
  • minecraft:use_duration - Use time
  • minecraft:use_animation - Use animation
Advanced
  • minecraft:custom_components - Custom script components
  • minecraft:cooldown - Use cooldown
  • minecraft:wearable - Equipment slot

Build docs developers (and LLMs) love

Get started for freeTalk to us