Definitions Overview

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:

Class	Purpose	File Type
EntityTypeDefinition	Entity behavior pack definitions	`entities/*.json`
EntityTypeResourceDefinition	Entity resource pack definitions	`entity/*.json`
BlockTypeDefinition	Block definitions	`blocks/*.json`
ItemTypeDefinition	Item behavior definitions	`items/*.json`
ItemTypeResourceDefinition	Item resource definitions (legacy)	`items/*.json`
AnimationBehaviorDefinition	Animation behavior logic	`animations/*.json`
AnimationResourceDefinition	Visual animations	`animations/*.json`
ParticleEffectResourceDefinition	Particle effects	`particles/*.json`
SoundDefinitionCatalogDefinition	Sound definitions catalog	`sounds.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

Entity Definitions - Learn about entity behavior and resource definitions
Block Definitions - Working with custom blocks
Item Definitions - Creating custom items
Animation Definitions - Managing animations
Particle Definitions - Configuring particle effects
Sound Definitions - Managing sound files

Core

Minecraft Definitions

World & Data

Storage

Validation

What are Definitions?

Definition File Structure

Common Definition Features

Loading and Persistence

Component Management

Format Version Management

Event Handling

Working with Project Items

Definition Types

Best Practices

Always Check Loading State

Use ensureOnFile Pattern

Persist Changes

Handle Undefined Values

Next Steps

Build docs developers (and LLMs) love

Core

Minecraft Definitions

World & Data

Storage

Validation

Documentation Index

​What are Definitions?

​Definition File Structure

​Common Definition Features

​Loading and Persistence

​Component Management

​Format Version Management

​Event Handling

​Working with Project Items

​Definition Types

​Best Practices

​Always Check Loading State

​Use ensureOnFile Pattern

​Persist Changes

​Handle Undefined Values

​Next Steps

Build docs developers (and LLMs) love

What are Definitions?

Definition File Structure

Common Definition Features

Loading and Persistence

Component Management

Format Version Management

Event Handling

Working with Project Items

Definition Types

Best Practices

Always Check Loading State

Use ensureOnFile Pattern

Persist Changes

Handle Undefined Values

Next Steps