Skip to main content
Info generators are the core of the Minecraft Creator Tools validation system. They analyze projects, files, and items to generate validation results.

​
Generator Types

There are three types of info generators, each operating at different scopes:

​
IProjectInfoGenerator

Project-level generators analyze the entire project structure. 
interface IProjectInfoGenerator extends IProjectInfoGeneratorBase {
  generate(
    project: Project,
    contentIndex: ContentIndex
  ): Promise<ProjectInfoItem[]>;
}
Parameters:
  • project - The project to analyze
  • contentIndex - Tracks content usage across the project
Returns: Array of validation items (errors, warnings, recommendations) Example use cases:
  • Checking manifest consistency
  • Validating pack dependencies
  • Analyzing project structure
  • Checking for duplicate vanilla content

​
IProjectItemInfoGenerator

Item-level generators analyze individual ProjectItem objects (entities, blocks, items, etc.). 
interface IProjectItemInfoGenerator extends IProjectInfoGeneratorBase {
  generate(
    projectItem: ProjectItem,
    contentIndex: ContentIndex,
    options?: IGeneratorOptions
  ): Promise<ProjectInfoItem[]>;
}
Parameters:
  • projectItem - The item to analyze (entity, block, item, etc.)
  • contentIndex - Tracks content usage
  • options - Optional generator behavior configuration
Options: 
interface IGeneratorOptions {
  /**
   * When true, generators may perform aggressive memory cleanup operations
   * after processing (e.g., clearing LevelDB data, chunk caches).
   * Appropriate for CLI validation, but should be false when data may be
   * needed by other components (e.g., world map rendering).
   */
  performAggressiveCleanup?: boolean;
}
Example use cases:
  • Validating JSON schema
  • Checking component usage
  • Analyzing entity behavior
  • Validating scripts

​
IProjectFileInfoGenerator

File-level generators analyze individual files directly. 
interface IProjectFileInfoGenerator extends IProjectInfoGeneratorBase {
  generate(
    project: Project,
    projectFile: IFile,
    contentIndex: ContentIndex
  ): Promise<ProjectInfoItem[]>;
}
Parameters:
  • project - The project context
  • projectFile - The file to analyze
  • contentIndex - Tracks content usage
Example use cases:
  • Checking file encoding (BOM detection)
  • Validating file paths
  • Checking file sizes
  • Analyzing image files

​
Base Interface

All generators extend IProjectInfoGeneratorBase: 
interface IProjectInfoGeneratorBase {
  id: string;
  title: string;
  canAlwaysProcess?: boolean;

  getTopicData(topicId: number): IProjectInfoTopicData | undefined;
  summarize(summaryDataObject: object, infoSet: ProjectInfoSet): void;
}
Properties:
  • id - Unique identifier for the generator (e.g., “JSONTAGS”, “STRICT”)
  • title - Human-readable name (e.g., “JSON Tags”, “Strict Mode”)
  • canAlwaysProcess - If true, generator runs even when no applicable items found
Methods:
  • getTopicData() - Returns metadata for a specific validation topic
  • summarize() - Aggregates validation results for reporting

​
Topic Data

interface IProjectInfoTopicData {
  title: string;
  updaters?: IProjectUpdaterReference[];
}

interface IProjectUpdaterReference {
  updaterId: string;
  updaterIndex: number;
  action: string;
}
Topic data connects validation issues to available fixes (updaters).

​
Creating Validation Items

Generators return ProjectInfoItem objects representing validation results: 
const item = new ProjectInfoItem(
  InfoItemType.error,           // Type of item
  "MYGEN",                      // Generator ID
  100,                          // Topic/test index
  "Invalid component usage",    // Message
  projectItem,                  // Optional: related project item
  "minecraft:behavior.float",   // Optional: additional data
  "entity_id",                  // Optional: item identifier
  "{\"component\": ...}",       // Optional: relevant content
  "BP/entities/custom.json"    // Optional: project path
);

​
Info Item Types

enum InfoItemType {
  testCompleteFail = 0,              // Test completed with failures
  testCompleteSuccess = 1,           // Test completed successfully
  info = 2,                          // Informational message
  error = 3,                         // Error that must be fixed
  warning = 4,                       // Warning that should be addressed
  internalProcessingError = 5,       // Internal generator error
  recommendation = 6,                // Suggested improvement
  featureAggregate = 7,              // Feature usage statistics
  testCompleteNoApplicableItemsFound = 8  // Test had nothing to validate
}

​
Example Generator Implementation

export default class CustomValidator implements IProjectInfoGenerator {
  id = "CUSTOM";
  title = "Custom Validation";
  canAlwaysProcess = true;

  getTopicData(topicId: number) {
    switch (topicId) {
      case 100:
        return { title: "Component Check" };
      case 101:
        return { title: "Behavior Check" };
      default:
        return undefined;
    }
  }

  async generate(
    project: Project,
    contentIndex: ContentIndex
  ): Promise<ProjectInfoItem[]> {
    const items: ProjectInfoItem[] = [];

    // Validate something
    const hasError = await this.checkSomething(project);

    if (hasError) {
      items.push(
        new ProjectInfoItem(
          InfoItemType.error,
          this.id,
          100,
          "Custom validation failed"
        )
      );
    } else {
      items.push(
        new ProjectInfoItem(
          InfoItemType.testCompleteSuccess,
          this.id,
          100,
          "Custom validation passed"
        )
      );
    }

    return items;
  }

  summarize(info: any, infoSet: ProjectInfoSet) {
    // Aggregate results for reporting
    const items = infoSet.getItems(this.id, 100);
    info.customCheckCount = items.length;
  }

  private async checkSomething(project: Project): Promise<boolean> {
    // Your validation logic here
    return false;
  }
}

​
Registering Generators

Add your generator to the registration list in GeneratorRegistrations.ts: 
static projectGenerators = [
  new ItemCountsInfoGenerator(),
  new PackSizeInfoGenerator(),
  new CustomValidator(),  // Your generator
  // ...
];

​
Feature Tracking

Generators can track feature usage statistics using the feature system: 
const item = new ProjectInfoItem(
  InfoItemType.featureAggregate,
  "MYGEN",
  200,
  "Feature usage"
);

// Increment a counter
item.incrementFeature("customComponent", "count", 1);

// Track numeric ranges (min/max/average)
item.spectrumFeature("componentComplexity", 42);

// Track boolean features
item.incrementFeature("hasCustomBehavior");

​
Best Practices

  1. Use specific topic IDs: Define clear enums for topic indexes
  2. Provide clear messages: Help users understand what’s wrong
  3. Include context: Add relevant file paths and content snippets
  4. Handle errors gracefully: Catch exceptions to avoid breaking other generators
  5. Track features: Use the feature system for analytics
  6. Add test summaries: Include success/fail items to indicate test completion
  7. Consider performance: Large projects may have thousands of files
  8. Use ContentIndex: Track content references for cross-file validation

Build docs developers (and LLMs) love

Get started for freeTalk to us