@minecraft/creator-tools/lib/minecraft/ContentGenerator.d.ts

Minecraft Creator Tools command line and libraries.

/**
 * ContentGenerator - Generates native Minecraft Bedrock content from meta-schema definitions.
 *
 * This module converts simplified IMinecraftContentDefinition objects into the full
 * set of Minecraft files (behavior pack JSONs, resource pack JSONs, textures, etc.).
 *
 * Key responsibilities:
 * 1. Expand traits into native components
 * 2. Generate placeholder textures using IMcpTexturedRectangle
 * 3. Create proper file structure with format_version
 * 4. Handle cross-references between files
 * 5. Generate loot tables from drops definitions
 *
 * @see IContentMetaSchema.ts for type definitions
 * @see ContentMetaSchemaZod.ts for validation schemas
 */
import { IMinecraftContentDefinition } from "./IContentMetaSchema";
/**
 * Result of content generation - all files to be created.
 */
export interface IGeneratedContent {
    /** Manifest for behavior pack */
    behaviorPackManifest?: IGeneratedFile;
    /** Manifest for resource pack */
    resourcePackManifest?: IGeneratedFile;
    /** Entity behavior files (behavior_packs/entities/) */
    entityBehaviors: IGeneratedFile[];
    /** Entity resource files (resource_packs/entity/) */
    entityResources: IGeneratedFile[];
    /** Block behavior files */
    blockBehaviors: IGeneratedFile[];
    /** Block resource files */
    blockResources: IGeneratedFile[];
    /** Item behavior files */
    itemBehaviors: IGeneratedFile[];
    /** Item resource files */
    itemResources: IGeneratedFile[];
    /** Structure files (.mcstructure) */
    structures: IGeneratedFile[];
    /** Feature files */
    features: IGeneratedFile[];
    /** Feature rule files */
    featureRules: IGeneratedFile[];
    /** Loot table files */
    lootTables: IGeneratedFile[];
    /** Recipe files */
    recipes: IGeneratedFile[];
    /** Spawn rule files */
    spawnRules: IGeneratedFile[];
    /** Texture files (as base64 PNG) */
    textures: IGeneratedFile[];
    /** Geometry files */
    geometries: IGeneratedFile[];
    /** Render controller files */
    renderControllers: IGeneratedFile[];
    /** Sound definition files */
    sounds: IGeneratedFile[];
    /** terrain_texture.json entries */
    terrainTextures?: IGeneratedFile;
    /** item_texture.json entries */
    itemTextures?: IGeneratedFile;
    /** blocks.json resource pack catalog (singleton, should be merged across calls) */
    blocksCatalog?: IGeneratedFile;
    /** sound_definitions.json (singleton, should be merged across calls) */
    soundDefinitions?: IGeneratedFile;
    /** music_definitions.json (singleton, should be merged across calls) */
    musicDefinitions?: IGeneratedFile;
    /** Summary of what was generated */
    summary: IGenerationSummary;
}
/**
 * A single generated file.
 */
export interface IGeneratedFile {
    /** Relative path within the pack (e.g., "entities/orc.json") */
    path: string;
    /** Content - JSON object, string for text, or Uint8Array for binary */
    content: object | string | Uint8Array;
    /** Content type */
    type: "json" | "png" | "mcstructure" | "text";
    /** Which pack this belongs to */
    pack: "behavior" | "resource" | "world" | "none";
}
/**
 * Summary of generation results.
 */
export interface IGenerationSummary {
    namespace: string;
    entityCount: number;
    blockCount: number;
    itemCount: number;
    structureCount: number;
    featureCount: number;
    lootTableCount: number;
    recipeCount: number;
    spawnRuleCount: number;
    textureCount: number;
    warnings: string[];
    errors: string[];
}
/**
 * Generates native Minecraft content from meta-schema definitions.
 */
export declare class ContentGenerator {
    private _definition;
    private _options;
    private _namespace;
    private _warnings;
    private _errors;
    /**
     * Sanitizes an ID for safe use in file paths.
     * Strips path separators and traversal sequences to prevent directory escape.
     */
    private static _sanitizeIdForPath;
    constructor(definition: IMinecraftContentDefinition);
    /**
     * Validates trait combinations for entities, blocks, and items.
     * Checks for conflicting traits and adds warnings to the result.
     *
     * @param result - The generation result to add warnings to
     */
    private _validateTraitCombinations;
    /**
     * Validates entity trait combinations for conflicts.
     */
    private _validateEntityTraits;
    /**
     * Validates block trait combinations for conflicts.
     */
    private _validateBlockTraits;
    /**
     * Validates item trait combinations for conflicts.
     */
    private _validateItemTraits;
    /**
     * Checks for common entity trait conflicts that may not be defined in trait data.
     */
    private _checkKnownEntityConflicts;
    /**
     * Checks for common block trait conflicts.
     */
    private _checkKnownBlockConflicts;
    /**
     * Checks for common item trait conflicts.
     */
    private _checkKnownItemConflicts;
    /**
     * Generate all content from the definition.
     */
    generate(): Promise<IGeneratedContent>;
    private _generateBehaviorManifest;
    private _generateResourceManifest;
    private _generateEntity;
    /**
     * Maps a content meta-schema bodyType to a model template type.
     */
    private _bodyTypeToTemplateType;
    /**
     * Maps an appearance.textureStyle value to the corresponding TexturedRectangleType
     * used in model-design textures. Falls back to the template's existing background type
     * (or 'stipple_noise') when no textureStyle is specified.
     */
    private _textureStyleToType;
    /**
     * Creates a recolored copy of a model design template using the user's primary/secondary colors.
     * Each named texture in the template gets a distinct color derived from the user's choices,
     * producing visually distinct faces that make it obvious how to customize the mob.
     */
    private _recolorModelDesign;
    /**
     * Generates entity geometry and texture using the model design pipeline.
     * Uses model templates with per-face textured rectangles for high-quality output.
     * Returns null if template loading fails, in which case the caller should use legacy generation.
     */
    private _generateEntityFromModelDesign;
    private _generateEntityResource;
    /**
     * Generate a render controller for an entity.
     * This creates a simple render controller that references the entity's geometry and texture.
     */
    private _generateEntityRenderController;
    /**
     * Generate a simple geometry for an entity based on its bodyType.
     * Returns a Minecraft geometry JSON structure.
     */
    private _generateEntityGeometry;
    /**
     * Get bone structure for different body types.
     */
    private _getGeometryBonesForBodyType;
    /**
     * Generate an entity placeholder texture PNG with distinct colors per body part.
     * Creates a 64x64 texture where each UV region (head, body, arms, legs) gets a
     * unique color derived from the entity's primary/secondary colors, with subtle
     * noise for visual interest.
     * Returns Uint8Array PNG data.
     */
    private _generateEntityTexturePlaceholder;
    /**
     * Render an ITextureSpec to PNG bytes.
     *
     * Precedence:
     *   1. If `spec` is a string or `spec.file` is set, the caller should use that file reference
     *      directly — this helper returns `undefined` so no placeholder PNG is emitted.
     *   2. If `spec.generate` and/or `spec.pixelArt` is set, build the PNG procedurally.
     *      - `generate` controls the background (use type: "none" for a transparent background).
     *      - `pixelArt` layers are drawn on top.
     *      - `spec.effects` are applied last.
     *   3. Returns `undefined` if the spec has nothing renderable.
     */
    private _renderTextureSpecToPng;
    /**
     * Pick the most representative face from an IBlockTexture to drive the single-PNG
     * placeholder we currently emit per block. Preference order: all, side, up, north,
     * south, east, west, down.
     */
    private _pickBlockFaceTexture;
    private _generateBlock;
    /**
     * Generate a placeholder texture for a block.
     *
     * Precedence:
     *   1. `block.texture` (ITextureSpec) — rendered via _renderTextureSpecToPng.
     *   2. `block.mapColor` — checkerboard fallback.
     *
     * Returns undefined if block.texture is a string/file reference (no placeholder needed).
     */
    private _generateBlockTexturePlaceholder;
    /**
     * Darken a hex color by a percentage.
     */
    private _darkenColor;
    private _generateItem;
    /**
     * Generate a placeholder texture for an item.
     *
     * Precedence:
     *   1. `item.icon` (ITextureSpec) — rendered via _renderTextureSpecToPng. If it's a
     *      string/file reference, no placeholder is emitted (caller should skip).
     *   2. `item.traits` — shaped template (sword/pickaxe/etc.) recolored with item.color.
     *   3. Fallback — checkerboard with item.color.
     */
    private _generateItemTexturePlaceholder;
    /**
     * Generate terrain_texture.json content for all blocks.
     */
    private _generateTerrainTextures;
    /**
     * Generate item_texture.json content for all items.
     */
    private _generateItemTextures;
    /**
     * Generate blocks.json catalog for the resource pack.
     * This maps block identifiers to their texture and sound references.
     */
    private _generateBlocksCatalog;
    private _generateLootTable;
    private _generateLootTableFromDrops;
    private _buildLootFunctions;
    private _buildLootCondition;
    private _generateRecipe;
    private _generateSpawnRule;
    private _generateSpawnRuleFromConfig;
    private _buildSpawnConditions;
    private _generateFeature;
    private _generateFeatureFromSpread;
    private _buildHeightPlacement;
    private _generateStructure;
    private _generateUuid;
}
/**
 * Generate Minecraft content from a meta-schema definition.
 */
export declare function generateContent(definition: IMinecraftContentDefinition): Promise<IGeneratedContent>;