@minecraft/creator-tools
Version:
Minecraft Creator Tools command line and libraries.
135 lines (134 loc) • 4.87 kB
TypeScript
/**
* ==========================================================================================
* VOXEL SHAPE DEFINITION
* ==========================================================================================
*
* OVERVIEW:
* ---------
* VoxelShapeDefinition manages custom voxel shape files for Minecraft Bedrock Edition.
* Voxel shapes define custom collision/selection boxes for blocks using the
* minecraft:voxel_shape format introduced in format_version 1.21.110.
*
* FILE STRUCTURE:
* ---------------
* Voxel shape files reside in <behavior pack>/shapes/ and have this structure:
* {
* "format_version": "1.21.110",
* "minecraft:voxel_shape": {
* "description": {
* "identifier": "custom:slab_bottom"
* },
* "shape": {
* "boxes": [
* { "min": [0.0, 0.0, 0.0], "max": [16.0, 8.0, 16.0] }
* ]
* }
* }
* }
*
* COORDINATE SYSTEM:
* ------------------
* - Coordinates are in "sub-block" units where 16 = 1 block
* - Origin (0,0,0) is the bottom-southwest corner of the block
* - Max (16,16,16) is the top-northeast corner of the block
* - Values can range from -30 to 30 (extending beyond the block)
*
* CONVERTING TO GEOMETRY:
* -----------------------
* To convert a voxel shape to model geometry for preview:
* - Divide coordinates by 16 to get block units (0-1 range for standard block)
* - Each box becomes a cube in the geometry
* - Note: Geometry uses different coordinate origins than voxel shapes
*
* ==========================================================================================
*/
import IFile from "../storage/IFile";
import IVoxelShapeFile, { IVoxelShapeBox } from "./IVoxelShapeFile";
import { IEventHandler } from "ste-events";
export default class VoxelShapeDefinition {
private _file?;
private _id?;
private _isLoaded;
private _loadedWithComments;
private _data?;
private _onLoaded;
get data(): IVoxelShapeFile | undefined;
get isLoaded(): boolean;
get file(): IFile | undefined;
set file(newFile: IFile | undefined);
get onLoaded(): import("ste-events").IEvent<VoxelShapeDefinition, VoxelShapeDefinition>;
get id(): string | undefined;
set id(newId: string | undefined);
get formatVersion(): string | undefined;
get boxes(): IVoxelShapeBox[];
static ensureOnFile(file: IFile, loadHandler?: IEventHandler<VoxelShapeDefinition, VoxelShapeDefinition>): Promise<VoxelShapeDefinition>;
persist(): void;
save(): Promise<void>;
/**
* Loads the definition from the file.
* @param preserveComments If true, uses comment-preserving JSON parsing for edit/save cycles.
* If false (default), uses efficient standard JSON parsing.
* Can be called again with true to "upgrade" a read-only load to read/write.
*/
load(preserveComments?: boolean): Promise<void>;
/**
* Adds a new box to the voxel shape.
*/
addBox(min: number[], max: number[]): void;
/**
* Removes a box at the specified index.
*/
removeBox(index: number): boolean;
/**
* Updates a box at the specified index.
*/
updateBox(index: number, min: number[], max: number[]): boolean;
/**
* Initializes an empty voxel shape data structure.
*/
private _initializeData;
/**
* Gets the normalized coordinates for a box (0-1 range for standard block).
*/
static getNormalizedBox(box: IVoxelShapeBox): {
min: number[];
max: number[];
};
/**
* Color palette for box visualization.
* Each box gets a distinct color for easy identification.
*/
static readonly BOX_COLORS: Array<{
r: number;
g: number;
b: number;
}>;
/**
* Converts the voxel shape to a model geometry definition object.
* Each box gets a different UV region for distinct coloring.
* Texture atlas is 128x16 with 8 colored slots.
*/
toGeometryJson(): object;
/**
* Generates a texture atlas for the voxel shape preview.
* Creates a 128x16 image with 8 colored slots (16x16 each).
* Each slot has a number overlay (1-8) for identification.
* Returns raw RGBA pixel data that can be encoded to PNG.
*/
generatePreviewTexturePixels(): {
pixels: Uint8Array;
width: number;
height: number;
};
/**
* Static version of generatePreviewTexturePixels for use without an instance.
* Creates a 128x16 image with 8 colored slots (16x16 each).
* Each slot has a number overlay (1-8) for identification.
* @param boxCount Number of boxes (only used for future extensions)
*/
static generatePreviewTexturePixelsStatic(_boxCount?: number): {
pixels: Uint8Array;
width: number;
height: number;
};
}