blockbench-types 4.6.1 → 4.9.0

package/types/textures.d.ts

@@ -38,14 +38,109 @@ interface TextureEditOptions {
     no_undo_finish?: boolean
 }
 
+/**
+ * A texture combines the functionality of material, texture, and image, in one. Textures can be linked to files on the local hard drive, or hold the information in RAM.
+ */
 declare class Texture {
     constructor(data: TextureData, uuid?: string);
     readonly frameCount: number | undefined;
     readonly display_height: number;
     readonly ratio: number;
 
+    path: string
+    name: string
+    /** Relative path to the file's directory, used by some formats such as Java Block/Item*/
+    folder: string
+    namespace: string
+    /** Texture ID or key, used by some formats. By default this is a number that increases with every texture that is added */
+    id: string
+    /** Whether the texture is used for the models particle system. Used by some formats such as Java Block/Item */
+    particle: boolean
+    render_mode: 'default' | 'emissive' | 'additive' | 'layered' | string
+    render_sides: 'auto' | 'front' | 'double' | string
+
+    /** Texture animation frame time */
+    frame_time: number
+    frame_order_type: 'custom' | 'loop' | 'backwards' | 'back_and_forth'
+    /** Custom frame order */
+    frame_order: string
+    /** Interpolate between frames */
+    frame_interpolate: boolean
+
+    /** HTML-style source of the texture's displayed data. Can be a path (desktop app only), or a base64 data URL */
+    source: string
+    selected: boolean
+    show_icon: boolean
+    error: number
+    /** Whether the texture is visible. Used for layered textures mode */
+    visible: boolean
+
+    width: number
+    height: number
+    uv_width: number
+    uv_height: number
+    currentFrame: number
+    saved: boolean
+    /**
+     * Whether the latest version of the texture is currently loaded from and linked to a file on disk, or held in memory as bitmap data
+     * @deprecated Use texture.internal instead
+    */
+    mode: 'link' | 'bitmap'
+    /**
+     * If true, the texture is loaded internally. If false, the texture is loaded directly from a file
+     */
+    internal: boolean
+    uuid: UUID
+    
+    /**
+     * Texture selection in paint mode
+     */
+    selection: IntMatrix
+    layers: TextureLayer[]
+    layers_enabled: boolean
+    /**
+     * The UUID of the project to sync the texture to
+     */
+    sync_to_project: UUID | ''
+
+    /**
+     * The texture's associated canvas. Since 4.9, this is the main source of truth for textures in internal mode.
+     */
+    canvas: HTMLCanvasElement
+    /**
+     * The 2D context of the texture's associated canvas.
+     */
+    ctx: CanvasRenderingContext2D
+    /**
+     * Texture image element
+     */
+    img: HTMLImageElement
+
     getErrorMessage(): string;
     extend(data: TextureData): this;
+
+    /**
+     * Get the UV width of the texture if the format uses per texture UV size, otherwise get the project texture width
+     */
+    getUVWidth(): number
+    /**
+     * Get the UV height of the texture if the format uses per texture UV size, otherwise get the project texture height
+     */
+    getUVHeight(): number
+    getUndoCopy(bitmap?: boolean): object
+    getSaveCopy(bitmap?: boolean): object
+    /**
+     * Start listening for changes to the linked file. Desktop only
+     */
+    startWatcher()
+    /**
+     * Stop listening for changes to the linked file. Desktop only
+     */
+    stopWatcher()
+    /**
+     * Generate the Java Block/Item folder property from the file path
+     */
+    generateFolder()
     /**
      * Loads the texture from it's current source
      * @param cb Callback function
@@ -114,9 +209,13 @@ declare class Texture {
     scrollTo(): void;
     save(as: any): this;
     /**
-     * Returns the content of the texture as a base64 encoded string
+     * Returns the content of the texture as PNG as a base64 encoded string
      */
     getBase64(): string;
+    /**
+     * Returns the content of the texture as PNG as a base64 encoded data URL
+     */
+    getDataURL(): string;
     /**
      * Wrapper to do edits to the texture. 
      * @param callback 
@@ -124,6 +223,54 @@ declare class Texture {
      */
     edit(callback: (instance: HTMLCanvasElement | object) => void | HTMLCanvasElement, options: TextureEditOptions): void;
     menu: Menu
+    /**
+     * Get the selected layer. If no layer is selected, returns the bottom layer
+     */
+    getActiveLayer(): TextureLayer
+    activateLayers(undo?: boolean): void
+    /**
+     * Turns the texture selection into a layer
+     * @param undo Whether to create an undo entry
+     * @param clone When true, the selection is copied into the new layer and also left on the original layer
+     */
+    selectionToLayer(undo?: boolean, clone?: boolean): void
+    javaTextureLink(): string
+
+    getMCMetaContent(): {
+        animation?: {
+            frametime: number
+            width?: number
+            height?: number
+            interpolate?: boolean
+            frames?: number[]
+        }
+    }
+    getAnimationFrameIndices(): number[]
+
+    exportEmissionMap(): void
+
+    convertToInternal(data_url?: string): this
+    /**
+     * Redraws the texture content from the layers
+     * @param update_data_url If true, the texture source gets updated as well. This is slower, but is necessary at the end of an edit. During an edit, to preview changes, this can be false
+     */
+    updateLayerChanges(update_data_url?: boolean): void
+    /**
+     * Update everything after a content edit to the texture or one of the layers. Updates the material, the layers, marks the texture as unsaved, syncs changes to other projects
+     */
+    updateChangesAfterEdit(): void
+    /**
+     * Update the attached img element with the content from the texture's canvas
+     */
+    updateImageFromCanvas(): void
+    /**
+     * If layers are enabled, returns the active layer, otherwise returns the texture. Either way, the 'canvas', 'ctx', and 'offset' properties can be used from the returned object
+     */
+    getActiveCanvas(): Texture | TextureLayer
+    /**
+     * When editing the same texture in different tabs (via Edit In Blockbench option), sync changes that were made to the texture to other projects
+     */
+    syncToOtherProject(): this
 
     static all: Texture[]
     static getDefault(): Texture
@@ -142,6 +289,104 @@ declare function loadTextureDraggable(): void;
  */
 declare function unselectTextures(): void;
 
+/**
+ * An Int Matrix holds an int (unsigned 8 bit) for each pixel in a matrix, via array. The override property can be used to set an override value for the entire area. This is used for texture selections.
+ */
+declare class IntMatrix {
+	constructor(width: number, height: number)
+    width: number
+    height: number
+    array: null | Int8Array
+    /**
+     * The override can be set to true to indicate that the whole texture is selected, or false, which indicates that nothing is selected. Null indicates a custom selection
+     */
+    override: boolean | null
+    /**
+     * True if there is a custom selection
+     */
+	readonly is_custom: boolean
+	/**
+	 * The array does not exist by default to save memory, this activates it.
+	 */
+	activate(): void
+	/**
+	 * Get the value at the specified pixel
+	 * @param {*} x X coordinate
+	 * @param {*} y Y coordinate
+	 * @returns The value of the targeted pixel
+	 */
+	get(x, y): number | boolean
+	/**
+	 * Test whether painting is allowed at a specific pixel
+	 * @param {*} x X coordinate
+	 * @param {*} y Y coordinate
+	 * @returns Boolean or value of the pixel
+	 */
+	allow(x, y): number | boolean
+	/**
+	 * Get the value at the specified pixel directly without override and bounds check
+	 * @param {*} x X coordinate
+	 * @param {*} y Y coordinate
+	 * @returns 
+	 */
+	getDirect(x: number, y: number): number
+    /**
+     * Return the smallest possible rectangle that contains all of the selection
+     * @param respect_empty If true, if there is no selection, the bounding box will still cover the entire area
+     */
+	getBoundingRect(respect_empty): Rectangle
+    /**
+     * Checks whether a selection is present and contains selected pixels
+     */
+	hasSelection(): boolean
+	/**
+	 * Set the value at a specified pixel
+	 * @param {*} x X coordinate
+	 * @param {*} y Y coordinate
+	 * @param {number} value 
+	 */
+	set(x: number, y: number, value: number)
+	/**
+	 * If there was a selection, whether override or not, clear it
+	 */
+	clear(): void
+	/**
+	 * Change override mode
+	 * @param {true|false|null} value 
+	 * @returns 
+	 */
+	setOverride(value: boolean | null): void
+	/**
+	 * Change the size of the matrix. Unless using overrides, the selection gets lost.
+	 * @param {number} width 
+	 * @param {number} height 
+	 * @returns {boolean} Whether the size had to be changed
+	 */
+	changeSize(width: number, height: number): void
+    /**
+     * Run a method on each pixel, whether selected or not
+     * @param callback Function to run per pixel
+     */
+	forEachPixel(callback: ((x: number, y: number, value: number, index: number) => void))
+    /**
+     * Shift custom selections by a specified offset
+     * @param offset_x 
+     * @param offset_y 
+     */
+	translate(offset_x: number, offset_y: number): void
+    /**
+     * Return the selection simplified into non-overlapping boxes. Boxes are [x, y, width, height].
+     */
+	toBoxes(): [number, number, number, number][]
+    /**
+     * Mask the provided canvas using the selection
+     * @param ctx Canvas 2D context
+     * @param offset Position offset of the canvas, e. g. when using a layer
+     */
+	maskCanvas(ctx: CanvasRenderingContext2D, offset: ArrayVector2): void
+}
+
+
 /**
  * Handles playback of animated textures
  */

package/types/timeline.d.ts

@@ -1,6 +1,6 @@
 declare namespace Timeline {
     const animators: GeneralAnimator[]
-    const selected: Keyframe[]
+    const selected: _Keyframe[]
     const playing_sounds: any[]
     let playback_speed: number
     /**
@@ -58,7 +58,7 @@ declare namespace Timeline {
      */
     function pause(): void
 
-    let keyframes: Keyframe[]
+    let keyframes: _Keyframe[]
     let menu: Menu
     function showMenu(event: Event): void
 

package/types/undo.d.ts

@@ -20,9 +20,9 @@ interface UndoAspects {
     selected_texture?: boolean
     settings?: {}
     uv_mode?: boolean
-    animations?: Animation[]
+    animations?: _Animation[]
     animation_controllers?: AnimationController[]
-    keyframes?: Keyframe[]
+    keyframes?: _Keyframe[]
     display_slots?: string[]
     exploded_view?: boolean
 }
@@ -55,11 +55,11 @@ type UndoEntry = {
 }
 interface AmendEditForm {
     condition?: ConditionResolvable
-    type?: 'number'
+    type?: 'number' | 'checkbox'
     label: string
     interval_type: 'position' | 'rotation'
     getInterval?: (Event) => number
-    value?: number | string,
+    value?: number | string | 'boolean',
     min?: number,
     max?: number,
     step?: number,
@@ -85,7 +85,7 @@ declare class UndoSystem {
      * Add keyframes to the current edit that were indirectly removed by moving other keyframes to their position
      * @param keyframes 
      */
-    addKeyframeCasualties(keyframes: Keyframe[]): void;
+    addKeyframeCasualties(keyframes: _Keyframe[]): void;
     /**
      * Undoes the latest edit
      */

package/types/util.d.ts

@@ -54,6 +54,9 @@ declare function getAxisLetter(axisNumber: number): string
 declare function getAxisNumber(axisLetter: string): number
 
 
+/**
+ * Reusable data types that can be used by anything, but should not be used to store data between function calls. Can be used to save memory on frequent function calls.
+ */
 declare namespace Reusable {
 	const vec1: THREE.Vector3
 	const vec2: THREE.Vector3
@@ -68,3 +71,32 @@ declare namespace Reusable {
 	const euler1: THREE.Euler
 	const euler2: THREE.Euler
 }
+
+/**
+ * Merge the value under a certain key from one object into another
+ */
+declare namespace Merge {
+	function number(target: object, source: object, key: string|number): void
+	function string(target: object, source: object, key: string|number, validate?: ((value) => boolean)): void
+	function molang(target: object, source: object, key: string|number): void
+	function boolean(target: object, source: object, key: string|number, validate?: ((value) => boolean)): void
+	function arrayVector(target: object, source: object, key: string|number, validate?: ((value) => boolean)): void
+	function arrayVector2(target: object, source: object, key: string|number, validate?: ((value) => boolean)): void
+}
+
+declare class Rectangle {
+	constructor(start_x: number, start_y: number, width: number, height: number)
+    start_x: number
+    start_y: number
+    width: number
+    height: number
+	readonly start: ArrayVector2
+	readonly w: number
+	readonly h: number
+	end_x: number
+	end_y: number
+	readonly area: number
+	fromCoords(x1: number, y1: number, x2: number, y2: number): void
+	fromUnorderedCoords(x1: number, y1: number, x2: number, y2: number): void
+	expandTo(x: number, y: number): void
+}

package/types/validator.d.ts

@@ -1,3 +1,6 @@
+/**
+ * The validator in Blockbench provides feedback about the model and can detect issues in real time, based on a list of checks that can be added. This is a good way to ensure model files are valid, and to teach users about best practices.
+ */
 declare namespace Validator {
     const checks: ValidatorCheck[]
 
@@ -42,6 +45,38 @@ interface WarningOrError {
 		click(): void
 	}[]
 }
+
+/**
+ * A check for the validator. A check can be triggered by certain things, and updates the list of warnings and errors that can be displayed in the status bar.
+
+
+### Example:
+
+```javascript
+	new ValidatorCheck('special_cube_name_rule', {
+		update_triggers: ['update_selection'],
+		run() {
+			Cube.all.forEach(cube => {
+				if (cube.name == 'sphere') {
+					this.warn({
+						message: `The cube "${cube.name}" has an invalid names. Cubes may not be called "sphere".`,
+						buttons: [
+							{
+								name: 'Select Cube',
+								icon: 'fa-cube',
+								click() {
+									Validator.dialog.hide();
+									cube.select();
+								}
+							}
+						]
+					})
+				}
+			})
+		}
+	})
+```
+ */
 declare class ValidatorCheck extends Deletable {
 	constructor(id: string, options: ValidatorCheckOptions)