Skip to main content
Entity definitions control mob and entity behavior (EntityTypeDefinition) and appearance (EntityTypeResourceDefinition) in Minecraft add-ons.

​
EntityTypeDefinition

EntityTypeDefinition manages entity behavior pack files (BP/entities/*.json), including components, component groups, and events.

​
Class Signature

class EntityTypeDefinition implements IManagedComponentSetItem, IDefinition {
  // Properties
  readonly id: string;
  readonly shortId?: string;
  readonly isLoaded: boolean;
  readonly behaviorPackFile?: IFile;
  readonly data?: IEntityTypeBehaviorPack;
  readonly componentGroups: { [name: string]: ManagedComponentGroup };
  readonly formatVersion?: string;
  
  // Component management
  getComponent(id: string): IManagedComponent | undefined;
  addComponent(id: string, componentOrData: any): ManagedComponent;
  removeComponent(id: string): void;
  getComponents(): IManagedComponent[];
  getAllComponents(): IManagedComponent[];
  
  // Component groups
  getComponentGroup(name: string): ManagedComponentGroup | undefined;
  getComponentGroups(): ManagedComponentGroup[];
  addComponentGroup(id?: string, data?: any): ManagedComponentGroup;
  
  // Events
  getEvent(name: string): IEventActionSet | IEventAction | undefined;
  getEvents(): IEventWrapper[];
  addEvent(eventName?: string): void;
  
  // Properties
  get properties(): any;
  addProperty(name: string, type: EntityPropertyType): void;
  removeProperty(name: string): void;
  
  // Loading and persistence
  static async ensureOnFile(file: IFile, handler?): Promise<EntityTypeDefinition>;
  async load(): Promise<void>;
  persist(): boolean;
  
  // Utilities
  getFormatVersion(): number[] | undefined;
  async getFormatVersionIsCurrent(): Promise<boolean>;
  setBehaviorPackFormatVersion(version: string): void;
}

​
Loading Entity Definitions

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

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

// Access entity data
console.log('Entity ID:', entityDef.id);
console.log('Format version:', entityDef.formatVersion);

// Get entity description
if (entityDef.data?.description) {
  console.log('Runtime identifier:', entityDef.data.description.runtime_identifier);
  console.log('Is spawnable:', entityDef.data.description.is_spawnable);
}

​
Working with Components

Components define entity behavior and attributes: 
// Get a component
const health = entityDef.getComponent('minecraft:health');
if (health) {
  const maxHealth = health.getProperty('value');
  console.log('Max health:', maxHealth);
}

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

// Add multiple components
entityDef.addComponent('minecraft:physics', {});
entityDef.addComponent('minecraft:pushable', {
  is_pushable: true,
  is_pushable_by_piston: true
});

// Remove a component
entityDef.removeComponent('minecraft:scale');

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

​
Component Groups

Component groups allow dynamic entity state changes: 
// Get component group
const babyGroup = entityDef.getComponentGroup('minecraft:baby');
if (babyGroup) {
  const scaleComp = babyGroup.getComponent('minecraft:scale');
}

// Add component group
const angryGroup = entityDef.addComponentGroup('custom:angry');
angryGroup.addComponent('minecraft:angry', { duration: 10 });

// Get all component groups
const groups = entityDef.getComponentGroups();
for (const group of groups) {
  console.log('Group:', group.id);
}

​
Events

Events trigger component group changes: 
// Get event
const spawnEvent = entityDef.getEvent('minecraft:entity_spawned');

// Add new event
entityDef.addEvent('custom:become_angry');

// Get all events
const events = entityDef.getEvents();
for (const evt of events) {
  console.log('Event:', evt.id);
}

​
Properties

Entity properties define custom state variables: 
import { EntityPropertyType } from 'minecraft-creator-tools';

// Add boolean property
entityDef.addProperty('custom:is_active', EntityPropertyType.boolean);

// Add integer property
entityDef.addProperty('custom:level', EntityPropertyType.int);

// Add enum property
entityDef.addProperty('custom:state', EntityPropertyType.enum);

// Remove property
entityDef.removeProperty('custom:is_active');

// Get all properties
const properties = entityDef.properties;

​
Entity JSON Structure

{
  "format_version": "1.20.0",
  "minecraft:entity": {
    "description": {
      "identifier": "custom:my_mob",
      "is_spawnable": true,
      "is_summonable": true,
      "runtime_identifier": "minecraft:zombie"
    },
    "components": {
      "minecraft:health": {
        "value": 20,
        "max": 20
      },
      "minecraft:movement": {
        "value": 0.25
      }
    },
    "component_groups": {
      "custom:angry": {
        "minecraft:angry": {
          "duration": 10
        }
      }
    },
    "events": {
      "custom:become_angry": {
        "add": {
          "component_groups": ["custom:angry"]
        }
      }
    }
  }
}

​
EntityTypeResourceDefinition

EntityTypeResourceDefinition manages entity resource pack files (RP/entity/*.json), defining visual appearance including textures, geometry, and animations.

​
Class Signature

class EntityTypeResourceDefinition {
  // Properties
  readonly id?: string;
  readonly isLoaded: boolean;
  readonly file?: IFile;
  readonly data?: IEntityTypeResourceDescription;
  readonly formatVersion?: string;
  
  // Textures
  readonly textures?: { [key: string]: string };
  readonly texturesIdList?: string[];
  getCanonicalizedTexturesList(): string[] | undefined;
  
  // Geometry
  readonly geometry?: { [key: string]: string };
  readonly geometryList?: string[];
  
  // Animations
  readonly animationIdList?: string[];
  readonly animationList?: string[];
  ensureAnimationAndGetShortName(fullName: string): string | undefined;
  ensureAnimationAndScript(fullName: string): void;
  
  // Animation Controllers
  readonly animationControllerIdList?: string[];
  readonly animationControllerList?: string[];
  
  // Render Controllers
  readonly renderControllerIdList?: string[];
  
  // Loading and persistence
  static async ensureOnFile(file: IFile, handler?): Promise<EntityTypeResourceDefinition>;
  async load(): Promise<void>;
  persist(): boolean;
  
  // Utilities
  getFormatVersion(): number[];
  getIsVersion1_8_0OrLower(): boolean;
  getIsVersion1_10_0OrHigher(): boolean;
}

​
Loading Entity Resources

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

const entityRes = await EntityTypeResourceDefinition.ensureOnFile(file);

console.log('Entity ID:', entityRes.id);
console.log('Format version:', entityRes.formatVersion);

​
Working with Textures

// Get texture definitions
const textures = entityRes.textures;
if (textures) {
  console.log('Default texture:', textures.default);
}

// Get texture IDs
const textureIds = entityRes.texturesIdList; // ['default', 'angry', etc.]

// Get canonicalized paths
const texturePaths = entityRes.getCanonicalizedTexturesList();
// Returns: ['textures/entity/my_mob']

​
Working with Geometry

// Get geometry definitions
const geometry = entityRes.geometry;
if (geometry) {
  console.log('Default geometry:', geometry.default);
}

// Get all geometry IDs
const geoList = entityRes.geometryList;
// Returns: ['geometry.my_mob', 'geometry.my_mob.baby']

​
Working with Animations

// Get animation list
const animations = entityRes.animationList;
// Returns: ['animation.my_mob.walk', 'animation.my_mob.attack']

// Get animation IDs (short names)
const animIds = entityRes.animationIdList;
// Returns: ['walk', 'attack']

// Add animation reference
const shortName = entityRes.ensureAnimationAndGetShortName(
  'animation.my_mob.fly'
);
// Adds to animations dictionary, returns 'fly'

// Add animation with script
entityRes.ensureAnimationAndScript('animation.my_mob.swim');
// Adds animation and adds to scripts.animate array

​
Working with Animation Controllers

// Get animation controller list
const controllers = entityRes.animationControllerList;
// Returns: ['controller.animation.my_mob.movement']

// Get controller IDs
const controllerIds = entityRes.animationControllerIdList;
// Returns: ['movement']

​
Entity Resource JSON Structure

{
  "format_version": "1.10.0",
  "minecraft:client_entity": {
    "description": {
      "identifier": "custom:my_mob",
      "materials": {
        "default": "entity"
      },
      "textures": {
        "default": "textures/entity/my_mob"
      },
      "geometry": {
        "default": "geometry.my_mob"
      },
      "animations": {
        "walk": "animation.my_mob.walk",
        "attack": "animation.my_mob.attack"
      },
      "animation_controllers": {
        "movement": "controller.animation.my_mob.movement"
      },
      "render_controllers": [
        "controller.render.my_mob"
      ],
      "scripts": {
        "animate": [
          "walk",
          "attack",
          { "movement": "query.is_moving" }
        ]
      }
    }
  }
}

​
Component Categories

Entity components are categorized by their function: 
import { EntityTypeComponentCategory } from 'minecraft-creator-tools';

const category = EntityTypeDefinition.getComponentCategory('minecraft:health');
// Returns: EntityTypeComponentCategory.complex

const behaviorCategory = EntityTypeDefinition.getComponentCategory(
  'minecraft:behavior.float'
);
// Returns: EntityTypeComponentCategory.behavior
Categories:
  • EntityTypeComponentCategory.attribute - Simple attribute components
  • EntityTypeComponentCategory.complex - Complex components with properties
  • EntityTypeComponentCategory.behavior - AI behavior components
  • EntityTypeComponentCategory.trigger - Event trigger components

​
Complete Example

import { 
  EntityTypeDefinition, 
  EntityTypeResourceDefinition,
  EntityPropertyType 
} from 'minecraft-creator-tools';

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

// Configure entity
entityDef.id = 'custom:fire_dragon';
entityDef.setBehaviorPackFormatVersion('1.20.0');

// Add components
entityDef.addComponent('minecraft:health', { value: 100, max: 100 });
entityDef.addComponent('minecraft:movement', { value: 0.3 });
entityDef.addComponent('minecraft:fire_immune', {});

// Add property
entityDef.addProperty('custom:rage_level', EntityPropertyType.int);

// Add component group
const enragedGroup = entityDef.addComponentGroup('custom:enraged');
enragedGroup.addComponent('minecraft:scale', { value: 1.5 });
enragedGroup.addComponent('minecraft:movement', { value: 0.5 });

// Add event
entityDef.addEvent('custom:become_enraged');

// Save behavior definition
entityDef.persist();

// Load resource definition
const entityRes = await EntityTypeResourceDefinition.ensureOnFile(resourceFile);

// Configure visuals
entityRes.ensureData();
if (entityRes.data) {
  entityRes.data.identifier = 'custom:fire_dragon';
  
  // Add texture
  if (!entityRes.data.textures) {
    entityRes.data.textures = {};
  }
  entityRes.data.textures.default = 'textures/entity/fire_dragon';
  
  // Add geometry
  if (!entityRes.data.geometry) {
    entityRes.data.geometry = {};
  }
  entityRes.data.geometry.default = 'geometry.fire_dragon';
  
  // Add animation
  entityRes.ensureAnimationAndScript('animation.fire_dragon.fly');
}

// Save resource definition
entityRes.persist();

console.log('Entity created successfully!');

Build docs developers (and LLMs) love

Get started for freeTalk to us