Skip to main content
The Minecraft Creator Tools library provides comprehensive support for loading, parsing, and manipulating Minecraft definition files. Definition files are JSON-based configuration files that define game content like entities, blocks, items, animations, particles, and sounds.

​
What are Definitions?

Definitions are the core content files in Minecraft add-ons that describe:
  • Entity Behaviors: How mobs and entities behave (EntityTypeDefinition)
  • Entity Resources: Visual appearance of entities (EntityTypeResourceDefinition)
  • Block Definitions: Custom block types and their properties (BlockTypeDefinition)
  • Item Definitions: Custom items in both behavior and resource packs (ItemTypeDefinition, ItemTypeResourceDefinition)
  • Animations: Entity animations for both behavior and visuals (AnimationBehaviorDefinition, AnimationResourceDefinition)
  • Particle Effects: Visual effects (ParticleEffectResourceDefinition)
  • Sound Definitions: Audio configuration (SoundDefinitionCatalogDefinition)

​
Definition File Structure

All Minecraft definition files follow a common pattern: 
{
  "format_version": "1.20.0",
  "minecraft:entity": {
    "description": {
      "identifier": "custom:my_entity"
    },
    "components": {},
    "component_groups": {},
    "events": {}
  }
}
The outer wrapper contains:
  • format_version: Version of the definition format
  • Type-specific key (e.g., minecraft:entity, minecraft:block, minecraft:item)
  • Inner structure with description, components, and optional features

​
Common Definition Features

All definition classes in the library implement the IDefinition interface and provide:

​
Loading and Persistence

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

// Load definition from file
const entityDef = await EntityTypeDefinition.ensureOnFile(file);
await entityDef.load();

// Make changes
entityDef.addComponent('minecraft:health', { value: 20 });

// Save changes back to file
entityDef.persist();

​
Component Management

Definitions that support components (entities, blocks, items) provide:
  • getComponent(id): Get a component by ID
  • addComponent(id, data): Add a new component
  • removeComponent(id): Remove a component
  • getComponents(): Get all components
// Get existing component
const health = entityDef.getComponent('minecraft:health');
if (health) {
  const maxValue = health.getProperty('value');
}

// Add new component
entityDef.addComponent('minecraft:scale', { value: 2.0 });

​
Format Version Management

// Check format version
const version = entityDef.getFormatVersion(); // [1, 20, 0]
const isCurrent = await entityDef.getFormatVersionIsCurrent();

// Update format version
entityDef.setBehaviorPackFormatVersion('1.21.0');

​
Event Handling

Definitions emit events when they’re loaded or modified: 
entityDef.onLoaded.subscribe((entity) => {
  console.log('Entity loaded:', entity.id);
});

entityDef.onComponentAdded.subscribe((entity, component) => {
  console.log('Component added:', component.id);
});

​
Working with Project Items

Definitions integrate with the project system to manage relationships between files: 
import { Project, ProjectItem } from 'minecraft-creator-tools';

const project = new Project();
const item = new ProjectItem(project, file);

// Load definition
const entityDef = await EntityTypeDefinition.ensureOnFile(file);

// Discover and link child items (textures, models, animations)
await entityDef.addChildItems(project, item);

​
Definition Types

The library provides definition classes for all major Minecraft content types:
ClassPurposeFile Type
EntityTypeDefinitionEntity behavior pack definitionsentities/*.json
EntityTypeResourceDefinitionEntity resource pack definitionsentity/*.json
BlockTypeDefinitionBlock definitionsblocks/*.json
ItemTypeDefinitionItem behavior definitionsitems/*.json
ItemTypeResourceDefinitionItem resource definitions (legacy)items/*.json
AnimationBehaviorDefinitionAnimation behavior logicanimations/*.json
AnimationResourceDefinitionVisual animationsanimations/*.json
ParticleEffectResourceDefinitionParticle effectsparticles/*.json
SoundDefinitionCatalogDefinitionSound definitions catalogsounds.json

​
Best Practices

​
Always Check Loading State

if (!entityDef.isLoaded) {
  await entityDef.load();
}

​
Use ensureOnFile Pattern

The ensureOnFile static method ensures proper file manager setup: 
// Correct approach
const def = await EntityTypeDefinition.ensureOnFile(file);

// Instead of manually constructing
const def = new EntityTypeDefinition();
def.behaviorPackFile = file;
await def.load();

​
Persist Changes

Always call persist() after making modifications: 
entityDef.addComponent('minecraft:health', { value: 20 });
entityDef.persist(); // Writes changes to file

​
Handle Undefined Values

Definition properties may be undefined if not loaded: 
const id = entityDef.id; // May be undefined
if (id) {
  console.log('Entity ID:', id);
}

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us