Minecraft Creator Tools

The @minecraft/server module provides the core API for manipulating a Minecraft world. It contains types and methods for interacting with fundamental world elements, including:

• Entities: Managing and interacting with living or non-living objects in the world.
• Blocks: Manipulating the physical composition of the world.
• Dimensions: Accessing and managing different world spaces (e.g., Overworld, Nether, End).
• World State: Accessing various properties and states of the active Minecraft world.

For complete API references and detailed documentation, refer to the official Microsoft Learn documentation.

The Minecraft Creator Tools view is integrated into the VS Code Explorer. It provides a dedicated interface to:

• Surface your current add-on projects.
• View validation results.
• Access quick actions for common authoring tasks.

The @minecraft/server-ui module provides types and interfaces for creating simple, dialog-based user interfaces within Minecraft. It is primarily used to present options, questions, or input forms to players through three main types of data forms:

1. ActionFormData: Used to present a list of buttons with captions and images. This is ideal for presenting a set of selectable options to a player.
2. MessageFormData: Used for simple two-button message experiences. This is best suited for binary questions like Yes/No or OK/Cancel.
3. ModalFormData: Used for flexible, questionnaire-style interfaces. This allows you to present a list of various controls to collect specific input from a player.

World data handling is built on NBT (Named Binary Tag) parsing, which is required to read level.dat. NBT is a hierarchical tree structure for typed data.

Key components:

• NBT Parsing: Implemented in NbtBinary.ts and NbtBinaryTag.ts.
• MCStructure: Small world snapshots also use NBT parsing.
• Level DB: The project uses script-based parsing for Level DB files (based on the level DB spec) to load LevelKeyValue pairs.
• WorldLevelChunk: The primary focal point for understanding and unifying world data, as most LevelKeyValue pairs are tied to specific chunks or subchunks.

The creator_tools_ingame behavior pack includes a development-only feature for rapid iteration and debugging. It uses the script_eval capability to allow JavaScript evaluation at runtime within the Minecraft server scripting context.

Key Details:

• Command: mct:eval allows you to inspect world state, test API calls, and evaluate expressions without reloading packs.
• Permissions: The command is restricted to CommandPermissionLevel.GameDirectors (operators only).
• Security: Code executes within the existing server script sandbox. It does not provide privilege escalation beyond what the behavior pack already possesses.
• Warning: This is a developer/debug feature and must not be included in production content intended for end users.

The Minecraft Add-On project is organized into the following directories:

• scripts/: Contains the TypeScript source code for in-game Creator Tools logic.
• behavior_packs/: Contains behavior pack resources and JSON definitions.
• resource_packs/: Contains resource pack assets.

The project uses two primary global abstractions to manage state and platform differences:

Carto

Carto is the main global object. It is designed to be platform-agnostic and manages:

• User Preferences: Persisted via the ICartoData interface.
• Storage: Access to IStorage objects for prefsStorage, projectsStorage, deployment storage (Minecraft target folder), and worlds storage (minecraftWorlds folder).
• Gallery: The loadGallery function loads the IGallery of starter projects and project items.

CartoApp

CartoApp represents the application itself and abstracts platform-specific logic using thunk functions. You can determine the current environment using:

• CartoApp.hostType
• Derived methods like .isWeb or .isNodeJs.

The project uses an asynchronous file system abstraction located in app/src/storage. Folders and files should be loaded asynchronously before use. Files and folders include a .manager property for extended logic.

Available IStorage implementations:

• BrowserStorage: Wraps localForage for browser-based key-value storage.
• HttpStorage: Read-only storage for files hosted on the web.
• NodeStorage: Implements storage using the NodeJS fs API.
• GitHubStorage: Provides read-only access to GitHub repositories via OctoKit and raw HTTP.

You can interact with Minecraft Creator Tools directly within the Copilot Chat view using the @minecraft chat participant. This allows you to perform project-specific tasks using slash commands:

• @minecraft /validate: Validates your Minecraft project for errors, warnings, and recommendations.
• @minecraft /create: Generates new Minecraft content such as entities, blocks, items, recipes, and loot tables.
• @minecraft /explain: Provides an explanation of the currently open Minecraft file.
• @minecraft /fix: Identifies and attempts to fix issues within your Minecraft content.

Use the following npm scripts to manage your project deployment:

• Deploy to local Minecraft: Use this to push changes to your local Minecraft installation for testing.

  npm run local-deploy

- **Create an addon file**: Use this to package the project into a `.mcaddon` file for sharing.
  ```powershell
npm run mcaddon