Validation Rules

Minecraft Creator Tools includes a comprehensive validation system that can identify issues, provide warnings, and automatically fix common problems in your add-ons and worlds.

Validation Architecture

The validation system is built around Info Generators that scan projects and produce Info Items:

ProjectInfoSet
  ├── Info Generators (Validators)
  │   ├── Generate Info Items
  │   └── Optional: Provide Updaters
  └── Info Items (Results)
      ├── Errors
      ├── Warnings
      ├── Recommendations
      └── Informational

Reference: app/src/info/ProjectInfoSet.ts:1

Info Generators

Info generators implement the IProjectInfoGenerator interface and scan projects for specific issues.

Generator Types

Project Generators

Scan entire projects (all files)Interface: IProjectInfoGenerator

Item Generators

Scan individual ProjectItemsInterface: IProjectItemInfoGenerator

File Generators

Scan individual filesInterface: IProjectFileInfoGenerator

Built-in Generators

The framework includes many built-in validators:

SchemaItemInfoGenerator

Validates JSON files against their schemas.What it checks:

JSON structure matches schema definitions
Required properties are present
Data types are correct

Example output:

Warning: JSON structure error
(format_version) must be a string

Reference: app/src/info/SchemaItemInfoGenerator.ts:1

ScriptModuleManager

Ensures script modules are up to date.What it checks:

Module versions in manifest.json
Package.json dependencies
Beta API module versions

Can update:

Outdated module versions
Package.json dependencies

Reference: app/src/manager/ScriptModuleManager.ts:1

BaseGameVersionManager

Scans for outdated base game versions.What it checks:

World template base_game_version
Comparison with latest Minecraft release

Can update:

base_game_version to latest

Reference: app/src/manager/BaseGameVersionManager.ts:1

BehaviorPackEntityTypeManager

Validates behavior pack entity type files.What it checks:

Entity format_version is current
Entity structure is valid

Future capabilities:

Smart format version upgrades
Semantic compatibility maintenance

CheckManifestGenerator

Validates manifest.json files.What it checks:

Required manifest fields
Valid UUIDs
Version format
Dependencies

CheckForbiddenFiles

Checks for files that shouldn’t be in add-ons.What it checks:

Build artifacts (node_modules, dist, lib)
Development files (.env, *.mjs)
Configuration files (package-lock.json)

Reference: app/src/info/projectGenerators/CheckForbiddenFiles.ts

Info Items

Validation results are returned as ProjectInfoItem objects:

Item Types

enum InfoItemType {
  error,                    // Must be fixed
  warning,                  // Should be fixed
  recommendation,           // Consider fixing
  info,                     // Informational only
  testCompleteFail,        // Test failed
  testCompleteSuccess,     // Test passed
  internalProcessingError  // Validator error
}

Info Item Structure

interface ProjectInfoItem {
  itemType: InfoItemType;
  generatorId: string;      // Which generator produced this
  topicId: number;          // Specific issue type
  message: string;          // Human-readable message
  projectItem?: ProjectItem; // Related file/item
  data?: string;            // Additional context
  feature?: string;         // Feature identifier
}

Running Validation

Basic Validation

Create a ProjectInfoSet

Choose a validation suite:

import { ProjectInfoSuite } from "./IProjectInfoData";

const infoSet = new ProjectInfoSet(
  project,
  ProjectInfoSuite.defaultInDevelopment
);

Generate validation results

Run the validators:

await infoSet.generateForProject();

Process results

Check for errors and warnings:

const errorCount = infoSet.errorAndFailCount;
const warningCount = infoSet.errorFailWarnCount - errorCount;

for (const item of infoSet.items) {
  if (item.itemType === InfoItemType.error) {
    console.error(item.message);
  }
}

Validation Suites

Different validation suites for different scenarios:

defaultInDevelopment

All validators except cooperative add-on and sharing checks.Use for: Local development

cooperativeAddOn

Validates add-ons for marketplace submission.Use for: Marketplace preparation

sharing

Checks for sharing compatibility.Use for: Community sharing

sharingStrict

Stricter sharing validation.Use for: Wide distribution

Managers: Generators + Updaters

A Manager is an info generator that can also fix issues it finds:

Manager = Info Generator + Updater

Example: ScriptModuleManager

// ScriptModuleManager detects outdated modules
const items = await manager.generate(project, contentIndex);

// Returns info items like:
// "Behavior pack dependency on 1.5.0 at @minecraft/server"
// "Latest version is 1.8.0"

Creating a Custom Manager

import IProjectInfoGenerator from "./IProjectInfoGenerator";
import IProjectUpdater from "../updates/IProjectUpdater";

export default class MyCustomManager 
  implements IProjectInfoGenerator, IProjectUpdater {
  
  id = "MYCUSTOM";
  title = "My Custom Validator";
  
  // Validation logic
  async generate(project: Project, contentIndex: ContentIndex) {
    const items: ProjectInfoItem[] = [];
    
    // Scan project for issues
    const itemsCopy = project.getItemsCopy();
    for (const item of itemsCopy) {
      if (/* issue found */) {
        items.push(new ProjectInfoItem(
          InfoItemType.error,
          this.id,
          100,
          "Issue description",
          item
        ));
      }
    }
    
    return items;
  }
  
  // Update logic
  async update(project: Project, updateIds: string[]) {
    if (!updateIds.includes(this.id)) {
      return new ProjectUpdateResult(UpdateResultType.notApplicable);
    }
    
    // Fix the issues
    // ...
    
    return new ProjectUpdateResult(UpdateResultType.updated);
  }
  
  getTopicData(topicId: number) {
    return { title: "Topic description" };
  }
  
  summarize(info: any, infoSet: ProjectInfoSet) {}
}

Automated Updates

The ProjectUpdateRunner orchestrates automated fixes:

import ProjectUpdateRunner from "../updates/ProjectUpdateRunner";

const runner = new ProjectUpdateRunner(project);

// Update specific components
await runner.updateProject(["SCRIPTMODULE", "BASEGAMEVER"]);

// Or update everything
await runner.updateProject();

Update Flow

Detection

Info generators identify issues

User Decision

User chooses which updates to apply

Application

Updaters modify project files

Verification

Re-run validation to confirm fixes

Practical Examples

Example 1: Validate Before Export

async function validateAndExport(project: Project) {
  // Run validation
  const infoSet = new ProjectInfoSet(
    project,
    ProjectInfoSuite.cooperativeAddOn
  );
  await infoSet.generateForProject();
  
  // Check for blocking errors
  if (infoSet.errorAndFailCount > 0) {
    console.error(`Found ${infoSet.errorAndFailCount} errors`);
    
    for (const item of infoSet.items) {
      if (item.itemType === InfoItemType.error) {
        console.error(`  ${item.message}`);
        if (item.projectItem) {
          console.error(`    in ${item.projectItem.storagePath}`);
        }
      }
    }
    
    return false;
  }
  
  // Export if validation passed
  await ProjectExporter.generateMCAddonAsZip(carto, project, true);
  return true;
}

Example 2: Auto-fix Common Issues

async function autoFixProject(project: Project) {
  const runner = new ProjectUpdateRunner(project);
  
  // Update outdated modules
  const result = await runner.updateProject(["SCRIPTMODULE"]);
  
  if (result.resultType === UpdateResultType.updated) {
    console.log("Updated script modules to latest versions");
    await project.save();
  }
}

Example 3: Custom Validation Report

async function generateReport(project: Project) {
  const infoSet = new ProjectInfoSet(
    project,
    ProjectInfoSuite.defaultInDevelopment
  );
  await infoSet.generateForProject();
  
  // Group by type
  const byType = {
    errors: [] as ProjectInfoItem[],
    warnings: [] as ProjectInfoItem[],
    info: [] as ProjectInfoItem[]
  };
  
  for (const item of infoSet.items) {
    if (item.itemType === InfoItemType.error) {
      byType.errors.push(item);
    } else if (item.itemType === InfoItemType.warning) {
      byType.warnings.push(item);
    } else {
      byType.info.push(item);
    }
  }
  
  // Generate CSV report
  const csv = [ProjectInfoSet.CommonCsvHeader];
  for (const item of infoSet.items) {
    csv.push(item.toCsvString());
  }
  
  return csv.join('\n');
}

Best Practices

Run validation frequently

Validate during development to catch issues early.

Use appropriate suites

Choose the right validation suite for your use case.

Handle errors gracefully

Always check for validation errors before operations.

Keep modules updated

Use managers to keep dependencies current.

Troubleshooting

Validation takes too long

Some validators are expensive. Consider:

Using specific validation suites instead of all
Excluding certain tests with _excludeTests
Running validation in background workers

False positives

If a validator reports incorrect issues:

Check that project files are loaded (await item.loadContent())
Ensure schemas are up to date
Review the specific generator implementation

Updates fail to apply

If automated updates don’t work:

Check file permissions
Ensure project is saved after updates
Verify the updater supports your file structure

Project Structure - Understanding the project model
Testing Locally - Testing with local servers
Packaging Add-ons - Export validation

Get Started

CLI Commands

Guides

Configuration

Validation Architecture

Info Generators

Generator Types

Project Generators

Item Generators

File Generators

Built-in Generators

Info Items

Item Types

Info Item Structure

Running Validation

Basic Validation

Validation Suites

defaultInDevelopment

cooperativeAddOn

sharing

sharingStrict

Managers: Generators + Updaters

Example: ScriptModuleManager

Creating a Custom Manager

Automated Updates

Update Flow

Practical Examples

Example 1: Validate Before Export

Example 2: Auto-fix Common Issues

Example 3: Custom Validation Report

Best Practices

Run validation frequently

Use appropriate suites

Handle errors gracefully

Keep modules updated

Troubleshooting

Build docs developers (and LLMs) love

Get Started

CLI Commands

Guides

Configuration

​Validation Architecture

​Info Generators

​Generator Types

Project Generators

Item Generators

File Generators

​Built-in Generators

​Info Items

​Item Types

​Info Item Structure

​Running Validation

​Basic Validation

​Validation Suites

defaultInDevelopment

cooperativeAddOn

sharing

sharingStrict

​Managers: Generators + Updaters

​Example: ScriptModuleManager

​Creating a Custom Manager

​Automated Updates

​Update Flow

​Practical Examples

​Example 1: Validate Before Export

​Example 2: Auto-fix Common Issues

​Example 3: Custom Validation Report

​Best Practices

Run validation frequently

Use appropriate suites

Handle errors gracefully

Keep modules updated

​Troubleshooting

​Related Resources

Build docs developers (and LLMs) love

Validation Architecture

Info Generators

Generator Types

Built-in Generators

Info Items

Item Types

Info Item Structure

Running Validation

Basic Validation

Validation Suites

Managers: Generators + Updaters

Example: ScriptModuleManager

Creating a Custom Manager

Automated Updates

Update Flow

Practical Examples

Example 1: Validate Before Export

Example 2: Auto-fix Common Issues

Example 3: Custom Validation Report

Best Practices

Troubleshooting

Related Resources