ProjectItem - Minecraft Creator Tools

Overview

The ProjectItem class represents a single file or folder within a Minecraft project. It provides methods for loading, saving, and managing file content, as well as tracking relationships between items.

Constructor

Creates a new ProjectItem instance.

parent

Project

required

Parent project

incomingData

IProjectItemData

Existing item data to initialize from

import { ProjectItem } from '@minecraft/creator-tools';

const item = new ProjectItem(project, itemData);

Properties

project

Project

The parent project containing this item

itemType

ProjectItemType

Type of the item (e.g., entityTypeBehavior, blockTypeDefinition)

name

string

Display name of the item

projectPath

string | null | undefined

Path relative to the project root

storageType

ProjectItemStorageType

Storage type (singleFile or folder)

defaultFile

IFile | null

The primary file for this item (for singleFile storage)

primaryFile

IFile | null

The most important file for this item (considers variants)

defaultFolder

IFolder | null

The folder for this item (for folder storage)

isContentLoaded

boolean

Whether the item’s content has been loaded

needsSave

boolean

Whether the item has unsaved changes

parentItems

ProjectItemRelationship[] | undefined

Items that reference this item

childItems

ProjectItemRelationship[] | undefined

Items referenced by this item

errorStatus

ProjectItemErrorStatus | undefined

Error status if the item failed to load

errorMessage

string | undefined

Error message if the item failed to load

editPreference

ProjectItemEditPreference

Edit preference for this specific item

Methods

loadContent

Loads the item’s content from storage.

return

Promise<boolean>

True if successful

await item.loadContent();

saveContent

Saves the item’s content to storage.

await item.saveContent();

ensureStorage

Ensures the item’s storage (file or folder) is initialized.

await item.ensureStorage();

ensureFileStorage

Ensures the item’s file storage is initialized (for singleFile items).

return

Promise<IFile | null>

The initialized file

const file = await item.ensureFileStorage();

loadFolder

Loads the item’s folder and contents (for folder items).

return

Promise<IFolder | undefined>

The loaded folder

const folder = await item.loadFolder();

getStringContent

Gets the item’s content as a string.

return

Promise<string | undefined>

The content as a string, or undefined if not text

const content = await item.getStringContent();

getJsonObject

Parses the item’s content as JSON.

return

Promise<object | undefined>

The parsed JSON object

const json = await item.getJsonObject();
if (json) {
  console.log(json);
}

getContentAsJson

Gets the item’s content as a parsed JSON object.

return

Promise<any | null>

The parsed JSON

const data = await item.getContentAsJson();

rename

Renames the item’s file.

newFileBaseName

string

required

New base name (without extension)

await item.rename('new_name');

deleteItem

Deletes the item and its file from the project.

await item.deleteItem();

getManager

Gets the manager object for this item (e.g., EntityTypeDefinition).

return

Promise<any | undefined>

The manager object

const manager = await item.getManager();

prepareToSave

Prepares the item for saving (runs auto-generation, etc.).

await item.prepareToSave();

hasTag

Checks if the item has a specific tag.

name

string

required

Tag name to check

return

boolean

True if the tag exists

if (item.hasTag('autogenerated')) {
  console.log('This file is auto-generated');
}

ensureTag

Adds a tag to the item if it doesn’t already exist.

name

string

required

Tag name to add

item.ensureTag('custom');

addChildItem

Adds a child item relationship (this item references another).

childItem

ProjectItem

required

The child item

item.addChildItem(textureItem);

addParentItem

Adds a parent item relationship (another item references this one).

parentItem

ProjectItem

required

The parent item

item.addParentItem(entityItem);

ensureDependencies

Calculates and updates the item’s dependencies.

await item.ensureDependencies();

getPack

Gets the pack (behavior or resource pack) containing this item.

return

Promise<Pack | undefined>

The containing pack

const pack = await item.getPack();
if (pack) {
  console.log(`Item is in pack: ${pack.name}`);
}

getPackRelativePath

Gets the path relative to the containing pack.

return

Promise<string | undefined>

Pack-relative path

const packPath = await item.getPackRelativePath();
// e.g., "entities/pig.json"

invalidateContentProcessedState

Marks the item’s content as needing reprocessing.

item.invalidateContentProcessedState();

Variants

getVariant

Gets a specific variant of the item (for multi-version files).

variantName

string

required

Variant label (e.g., “1.20.0”, “preview”)

return

ProjectItemVariant | undefined

The variant, or undefined if not found

const variant = item.getVariant('1.20.0');

ensureVariant

Gets or creates a variant.

label

string

required

Variant label

return

ProjectItemVariant

The variant

const variant = item.ensureVariant('preview');

getVariantList

Gets all variants for this item.

return

ProjectItemVariant[]

Array of variants

const variants = item.getVariantList();
for (const variant of variants) {
  console.log(variant.label);
}

Events

onPropertyChanged

Fired when a property changes.

item.onPropertyChanged.subscribe((itm, propertyName) => {
  console.log(`Property changed: ${propertyName}`);
});

onLoaded

Fired when the item finishes loading.

item.onLoaded.subscribe((itm) => {
  console.log('Item loaded');
});

onFileRetrieved

Fired when the item’s file is retrieved.

item.onFileRetrieved.subscribe((itm, file) => {
  console.log(`File retrieved: ${file.name}`);
});

onFolderRetrieved

Fired when the item’s folder is retrieved.

item.onFolderRetrieved.subscribe((itm, folder) => {
  console.log(`Folder retrieved: ${folder.name}`);
});

Types

ProjectItemType

enum ProjectItemType {
  unknown = 0,
  entityTypeBehavior = 1,
  entityTypeResource = 2,
  blockTypeDefinition = 3,
  itemTypeDefinition = 4,
  behaviorPackManifestJson = 10,
  resourcePackManifestJson = 11,
  js = 20,
  ts = 21,
  json = 30,
  // ... many more types
}

ProjectItemStorageType

enum ProjectItemStorageType {
  singleFile = 0,
  folder = 1
}

ProjectItemEditPreference

enum ProjectItemEditPreference {
  projectDefault = 0,
  forceRaw = 1,
  summarized = 2
}

ProjectItemCreationType

enum ProjectItemCreationType {
  normal = 0,
  generated = 1,
  inferred = 2
}

Usage Examples

Working with Entity Files

// Get entity behavior items
const entities = project.getItemsByType(
  ProjectItemType.entityTypeBehavior
);

for (const entity of entities) {
  await entity.loadContent();
  const json = await entity.getJsonObject();
  
  if (json) {
    console.log(`Entity: ${entity.name}`);
  }
}

Creating and Saving a New File

const item = project.ensureItemByProjectPath(
  '/behavior_packs/my_pack/entities/custom.json',
  ProjectItemStorageType.singleFile,
  'custom.json',
  ProjectItemType.entityTypeBehavior
);

await item.ensureFileStorage();

if (item.defaultFile) {
  item.defaultFile.setContent(JSON.stringify({
    "format_version": "1.20.0",
    "minecraft:entity": {
      "description": {
        "identifier": "custom:entity"
      }
    }
  }, null, 2));
  
  await item.saveContent();
}

Tracking Dependencies

await item.ensureDependencies();

if (item.childItems) {
  console.log('This item uses:');
  for (const rel of item.childItems) {
    console.log(`  - ${rel.childItem.name}`);
  }
}

if (item.parentItems) {
  console.log('This item is used by:');
  for (const rel of item.parentItems) {
    console.log(`  - ${rel.parentItem.name}`);
  }
}

Core

Minecraft Definitions

World & Data

Storage

Validation

​Overview

​Constructor

​Properties

​project

​itemType

​name

​projectPath

​storageType

​defaultFile

​primaryFile

​defaultFolder

​isContentLoaded

​needsSave

​tags

​parentItems

​childItems

​errorStatus

​errorMessage

​editPreference

​Methods

​loadContent

​saveContent

​ensureStorage

​ensureFileStorage

​loadFolder

​getStringContent

​getJsonObject

​getContentAsJson

​rename

​deleteItem

​getManager

​prepareToSave

​hasTag

​ensureTag

​addChildItem

​addParentItem

​ensureDependencies

​getPack

​getPackRelativePath

​invalidateContentProcessedState

​Variants

​getVariant

​ensureVariant

​getVariantList

​Events

​onPropertyChanged

​onLoaded

​onFileRetrieved

​onFolderRetrieved

​Types

​ProjectItemType

​ProjectItemStorageType

​ProjectItemEditPreference

​ProjectItemCreationType

​Usage Examples

​Working with Entity Files

​Creating and Saving a New File

​Tracking Dependencies

​See Also

Build docs developers (and LLMs) love

Overview

Constructor

Properties

project

itemType

name

projectPath

storageType

defaultFile

primaryFile

defaultFolder

isContentLoaded

needsSave

tags

parentItems

childItems

errorStatus

errorMessage

editPreference

Methods

loadContent

saveContent

ensureStorage

ensureFileStorage

loadFolder

getStringContent

getJsonObject

getContentAsJson

rename

deleteItem

getManager

prepareToSave

hasTag

ensureTag

addChildItem

addParentItem

ensureDependencies

getPack

getPackRelativePath

invalidateContentProcessedState

Variants

getVariant

ensureVariant

getVariantList

Events

onPropertyChanged

onLoaded

onFileRetrieved

onFolderRetrieved

Types

ProjectItemType

ProjectItemStorageType

ProjectItemEditPreference

ProjectItemCreationType

Usage Examples

Working with Entity Files

Creating and Saving a New File

Tracking Dependencies

See Also