Project - Minecraft Creator Tools

Overview

The Project class represents a complete Minecraft add-on or world project. It manages project items (files), packs, metadata, and provides methods for building, validating, and deploying projects.

Constructor

Creates a new Project instance.

creatorTools

CreatorTools

required

Parent CreatorTools instance

name

string

required

Project name

preferencesFile

IFile | null

required

File for storing project preferences

sanitizeName

boolean

Whether to sanitize the project name

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

const project = new Project(
  creatorTools,
  'My Add-on',
  prefsFile,
  true
);

Properties

name

string

The project’s name

title

string

Display title for the project (defaults to name if not set)

description

string

Project description

creator

string | undefined

Creator/author name

shortName

string | undefined

Short identifier for the project

effectiveShortName

string

Computed short name from creator and project name

focus

ProjectFocus

Project focus type (general, world, gameplay, etc.)

items

ProjectItem[]

Array of all files and folders in the project

packs

Pack[]

Array of behavior and resource packs

projectFolder

IFolder | null

Root folder containing project files

defaultBehaviorPackFolder

IFolder | null

Default behavior pack folder

defaultResourcePackFolder

IFolder | null

Default resource pack folder

preferredScriptLanguage

ProjectScriptLanguage

Preferred language for scripts (TypeScript or JavaScript)

defaultNamespace

string | undefined

Default namespace for project identifiers

effectiveDefaultNamespace

string

Computed default namespace (uses shortName if not set)

versionMajor

number | undefined

Major version number

versionMinor

number | undefined

Minor version number

versionPatch

number | undefined

Patch version number

versionAsString

string

Version as a formatted string (e.g., “1.0.0”)

defaultBehaviorPackUniqueId

string

UUID for the default behavior pack

defaultResourcePackUniqueId

string

UUID for the default resource pack

editPreference

ProjectEditPreference

Edit preference for this project (raw, summarized, or editors)

showHiddenItems

boolean

Whether to show hidden files

Methods

ensureProjectFolder

Ensures the project folder exists and is loaded.

return

Promise<IFolder>

The project’s root folder

const folder = await project.ensureProjectFolder();

ensureInflated

Ensures all project data structures are loaded and ready.

await project.ensureInflated();

inferProjectItemsFromFiles

Scans the project folder and creates ProjectItems for all files.

force

boolean

Force re-scan even if already scanned

processingCallback

(area: string) => void

Callback for progress updates

await project.inferProjectItemsFromFiles(false, (area) => {
  console.log(`Processing: ${area}`);
});

save

Saves the project preferences and metadata.

await project.save();

getItemsByType

Gets all project items of a specific type.

itemType

ProjectItemType

required

The type of items to retrieve

return

ProjectItem[]

Array of matching items

const entities = project.getItemsByType(
  ProjectItemType.entityTypeBehavior
);

getItemByProjectPath

Finds a project item by its path.

projectPath

string

required

Path relative to project root

return

ProjectItem | undefined

The matching item, or undefined if not found

const item = project.getItemByProjectPath(
  '/behavior_packs/my_pack/manifest.json'
);

ensureItemByProjectPath

Gets or creates a project item at the specified path.

projectPath

string

required

Path relative to project root

storageType

ProjectItemStorageType

required

Storage type (singleFile or folder)

name

string

required

Item name

itemType

ProjectItemType

required

Type of item

return

ProjectItem

The found or created item

const manifest = project.ensureItemByProjectPath(
  '/behavior_packs/my_pack/manifest.json',
  ProjectItemStorageType.singleFile,
  'manifest.json',
  ProjectItemType.behaviorPackManifestJson
);

removeItem

Removes a project item from the project.

item

ProjectItem

required

The item to remove

project.removeItem(oldItem);

ensureDefaultBehaviorPackFolder

Ensures a default behavior pack folder exists.

return

Promise<IFolder>

The behavior pack folder

const bpFolder = await project.ensureDefaultBehaviorPackFolder();

ensureDefaultResourcePackFolder

Ensures a default resource pack folder exists.

return

Promise<IFolder>

The resource pack folder

const rpFolder = await project.ensureDefaultResourcePackFolder();

ensureBehaviorPackScriptsFolder

Ensures a scripts folder exists in the behavior pack.

return

Promise<IFolder>

The scripts folder

const scriptsFolder = await project.ensureBehaviorPackScriptsFolder();

updateContentsModified

Updates the last modified timestamp for the project.

project.updateContentsModified();

hasScript

Checks if the project contains any script files.

return

Promise<boolean>

True if scripts are present

const hasScripts = await project.hasScript();

getBehaviorPackCount

Gets the number of behavior packs in the project.

return

number

Number of behavior packs

const bpCount = project.getBehaviorPackCount();

getResourcePackCount

Gets the number of resource packs in the project.

return

number

Number of resource packs

const rpCount = project.getResourcePackCount();

ensureInfoSetGenerated

Generates project information and validation data.

return

Promise<ProjectInfoSet>

The generated info set

const infoSet = await project.ensureInfoSetGenerated();

applyUpdate

Applies a project update/migration.

update

IProjectUpdater

required

The update to apply

return

Promise<ProjectUpdateResult>

Result of the update

const result = await project.applyUpdate(updater);

Events

onPropertyChanged

Fired when a project property changes.

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

onLoaded

Fired when the project finishes loading.

project.onLoaded.subscribe((proj) => {
  console.log('Project loaded');
});

onSaved

Fired when the project is saved.

project.onSaved.subscribe((proj) => {
  console.log('Project saved');
});

onItemAdded

Fired when a new item is added to the project.

project.onItemAdded.subscribe((proj, item) => {
  console.log(`Item added: ${item.name}`);
});

onItemRemoved

Fired when an item is removed from the project.

project.onItemRemoved.subscribe((proj, item) => {
  console.log(`Item removed: ${item.name}`);
});

onItemChanged

Fired when a project item changes.

project.onItemChanged.subscribe((proj, item) => {
  console.log(`Item changed: ${item.name}`);
});

Types

ProjectFocus

enum ProjectFocus {
  general = 0,
  world = 1,
  gameplay = 2,
  editor = 3
}

ProjectScriptLanguage

enum ProjectScriptLanguage {
  javaScript = 0,
  typeScript = 1
}

ProjectEditPreference

enum ProjectEditPreference {
  default = 0,
  summarized = 1,
  raw = 2,
  editors = 3
}

Core

Minecraft Definitions

World & Data

Storage

Validation

​Overview

​Constructor

​Properties

​name

​title

​description

​creator

​shortName

​effectiveShortName

​focus

​items

​packs

​projectFolder

​defaultBehaviorPackFolder

​defaultResourcePackFolder

​preferredScriptLanguage

​defaultNamespace

​effectiveDefaultNamespace

​versionMajor

​versionMinor

​versionPatch

​versionAsString

​defaultBehaviorPackUniqueId

​defaultResourcePackUniqueId

​editPreference

​showHiddenItems

​Methods

​ensureProjectFolder

​ensureInflated

​inferProjectItemsFromFiles

​save

​getItemsByType

​getItemByProjectPath

​ensureItemByProjectPath

​removeItem

​ensureDefaultBehaviorPackFolder

​ensureDefaultResourcePackFolder

​ensureBehaviorPackScriptsFolder

​updateContentsModified

​hasScript

​getBehaviorPackCount

​getResourcePackCount

​ensureInfoSetGenerated

​applyUpdate

​Events

​onPropertyChanged

​onLoaded

​onSaved

​onItemAdded

​onItemRemoved

​onItemChanged

​Types

​ProjectFocus

​ProjectScriptLanguage

​ProjectEditPreference

​See Also

Build docs developers (and LLMs) love

Overview

Constructor

Properties

name

title

description

creator

shortName

effectiveShortName

focus

items

packs

projectFolder

defaultBehaviorPackFolder

defaultResourcePackFolder

preferredScriptLanguage

defaultNamespace

effectiveDefaultNamespace

versionMajor

versionMinor

versionPatch

versionAsString

defaultBehaviorPackUniqueId

defaultResourcePackUniqueId

editPreference

showHiddenItems

Methods

ensureProjectFolder

ensureInflated

inferProjectItemsFromFiles

save

getItemsByType

getItemByProjectPath

ensureItemByProjectPath

removeItem

ensureDefaultBehaviorPackFolder

ensureDefaultResourcePackFolder

ensureBehaviorPackScriptsFolder

updateContentsModified

hasScript

getBehaviorPackCount

getResourcePackCount

ensureInfoSetGenerated

applyUpdate

Events

onPropertyChanged

onLoaded

onSaved

onItemAdded

onItemRemoved

onItemChanged

Types

ProjectFocus

ProjectScriptLanguage

ProjectEditPreference

See Also