blockbench-types 4.3.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockbench-types",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Blockbench typescript types",
   "main": "",
   "types": "types/index.d.ts",
@@ -19,6 +19,7 @@
   "homepage": "https://github.com/JannisX11/blockbench-types#readme",
   "dependencies": {
     "@types/jquery": "^3.5.4",
+    "@types/tinycolor2": "^1.4.3",
     "three": "^0.129.0",
     "vue": "^2.6.14",
     "wintersky": "^1.1.0"

package/types/action.d.ts

@@ -54,20 +54,128 @@ interface ActionOptions extends BarItemOptions {
 }
 declare class Action extends BarItem {
     constructor(id: string, options: ActionOptions);
+    /**
+     * Trigger to run or select the action. This is the equivalent of clicking or using a keybind to trigger it. Also checks if the condition is met.
+     */
     trigger(event: Event): boolean;
     updateKeybindingLabel(): this;
-    setIcon(icon: string): void;
+    /** Change the icon of the action */
+    setIcon(icon: IconString): void;
     toggleLinkedSetting(change: any): void;
     nodes: HTMLElement[]
+    /**
+     * Provide a menu that belongs to the action, and gets displayed as a small arrow next to it in toolbars.
+     */
+    side_menu?: Menu
+}
+
+type RGBAColor = {r: number, g: number, b: number, a: number}
+type ViewMode = 'textured' | 'solid' | 'wireframe' | 'uv' | 'normal'
+type PaintContext = {
+    /**
+     * Brush color, set by the Blockbench color panel
+    */
+    color: string,
+    /**
+     * Opacity, as set by the Opacity slider
+     */
+    opacity: number,
+    /**
+     * 2D Canvas context of the texture that is being edited
+     */
+    ctx: CanvasRenderingContext2D,
+    /**X Coordinate of the position of the brush stroke */
+    x: number,
+    /**Y Coordinate of the position of the brush stroke */
+    y: number,
+    /**
+     * Brush size, as set by the Brush Size slider
+     */
+    size: number,
+    /**
+     * Brush softness, as set by the Brush Softness slider
+     */
+    softness: number,
+    /**
+     * Blockbench texture that is being edited
+     */
+    texture: Texture,
+    /**
+     * Javascript pointer event that the brush stroke originated from
+     */
+    event: PointerEvent
 }
+interface BrushOptions {
+    /**
+     * Enable the input for blend modes when this tool is selected
+     */
+    blend_modes: boolean
+    /**
+     * Enable the input for shapes when this tool is selected
+     */
+    shapes: boolean
+    /**
+     * Enable the input for brush size when this tool is selected
+     */
+    size: boolean
+    /**
+     * Enable the input for softness when this tool is selected
+     */
+    softness: boolean
+    /**
+     * Enable the input for opacity when this tool is selected
+     */
+    opacity: boolean
+    /**
+     * When the brush size is an even number, offset the snapping by half a pixel so that even size brush strokes can be correctly centered
+     */
+    offset_even_radius: boolean
+    /**
+     * Set whether the brush coordinates get floored to snap to the nearest pixel.
+     */
+    floor_coordinates: boolean | (() => boolean)
+    /**
+     * Function that runs per pixel when the brush is used. Mutually exclusive with draw().
+     * @param pixel_x Local X coordinate relative to the brush center
+     * @param pixel_y Local Y coordinate relative to the brush center
+     * @param pixel_color Current color of the pixel on the texture
+     * @param local_opacity Local opacity of the current pixel on the brush, between 0 and 1. Opacity falls of to the sides of the brush if the brush is set to smooth. Opacity from the Opacity slider is not factored in yet.
+     * @param PaintContext Additional context to the paint stroke
+     */
+    changePixel(pixel_x: number, pixel_y, pixel_color: RGBAColor, local_opacity: number, PaintContext: PaintContext): RGBAColor
+    /**
+     * Function that runs when a new brush stroke starts. Return false to cancel the brush stroke
+     * @param context 
+     */
+    onStrokeStart(context: {texture: Texture, x: number, y: number, uv?: object, event: PointerEvent, raycast_data: RaycastResult}): boolean
+    /**
+     * Function that runs when a new brush stroke starts. Return false to cancel the brush stroke
+     * @param context 
+     */
+    onStrokeMove(context: {texture: Texture, x: number, y: number, uv?: object, event: PointerEvent, raycast_data: RaycastResult}): boolean
+    /**
+     * Function that runs when a new brush stroke starts.
+     * @param context 
+     */
+    onStrokeEnd(context: {texture: Texture, x: number, y: number, uv?: object, raycast_data: RaycastResult})
+    /**
+     * Alternative way to create a custom brush, mutually exclusive with the changePixel() function. Draw runs once every time the brush starts or moves, and also along the bath on lines.
+     * @param context 
+     */
+    draw(context: {ctx: CanvasRenderingContext2D, x: number, y: number, size: number, softness: number, texture: Texture, event: PointerEvent})
 
+}
 interface ToolOptions extends ActionOptions {
     selectFace?: boolean
+    selectElements?: boolean
     transformerMode?: 'translate' | ''
     animation_channel?: string
     toolbar?: string
     alt_tool?: string
     modes?: string[]
+    allowed_view_modes?: ViewMode
+    paintTool?: boolean
+    brush?: BrushOptions
 }
 declare class Tool extends Action {
     constructor(id: string, options: ToolOptions);

package/types/format.d.ts

@@ -9,6 +9,28 @@ interface FormatPage {
 	} | string)[]
 	button_text?: string
 }
+interface CubeSizeLimiter {
+	/**
+	 * Test whether the cube with the optionally provided values violates the size restrictions
+	 */
+	test: (cube: Cube, values?: {from: ArrayVector3, to: ArrayVector3, inflate: number}) => boolean
+	/**
+	 * Move the cube back into the restructions
+	 */
+	move: (cube: Cube, values?: {from: ArrayVector3, to: ArrayVector3, inflate: number}) => void
+	/**
+	 * Clamp the cube to fit into the restrictions. When an axis and direction is provided, clamp the element on that side to prevent wandering.
+	 */
+	clamp: (cube: Cube, values?: {from: ArrayVector3, to: ArrayVector3, inflate: number}, axis?: number, direction?: boolean | null) => void
+	/**
+	 * Set to true to tell Blockbench to check and adjust the cube limit after rotating a cube
+	 */
+	rotation_affected?: boolean,
+	/**
+	 * Optionally set the coordinate limits of cubes in local space
+	 */
+	coordinate_limits?: [number, number]
+}
 
 interface FormatOptions {
 	id: string
@@ -24,25 +46,34 @@ interface FormatOptions {
 	onFormatPage?(): void
 	onStart?(): void
 
-	box_uv?: boolean
-	optional_box_uv?: boolean
-	single_texture?: boolean
-	animated_textures?: boolean
-	bone_rig?: boolean
-	centered_grid?: boolean
-	rotate_cubes?: boolean
-	integer_size?: boolean
-	meshes?: boolean
-	texture_meshes?: boolean
-	locators?: boolean
-	canvas_limit?: boolean
-	rotation_limit?: boolean
-	uv_rotation?: boolean
+	box_uv: boolean
+	optional_box_uv: boolean
+	single_texture: boolean
+	model_identifier: boolean
+	parent_model_id: boolean
+	vertex_color_ambient_occlusion: boolean
+	animated_textures: boolean
+	bone_rig: boolean
+	centered_grid: boolean
+	rotate_cubes: boolean
+	integer_size: boolean
+	meshes: boolean
+	texture_meshes: boolean
+	locators: boolean
+	rotation_limit: boolean
+	uv_rotation: boolean
+	java_face_properties: boolean
+	select_texture_for_particles: boolean
+	bone_binding_expression: boolean
+	animation_files: boolean
+	texture_folder: boolean
+	edit_mode?: boolean
+	paint_mode?: boolean
 	display_mode?: boolean
 	animation_mode?: boolean
-	animation_files?: boolean
 	pose_mode?: boolean
-	texture_folder?: boolean
+
+	cube_size_limiter?: CubeSizeLimiter
 
 	codec?: Codec
 	onActivation?(): void
@@ -80,18 +111,20 @@ declare class ModelFormat extends Deletable {
 	meshes: boolean
 	texture_meshes: boolean
 	locators: boolean
-	canvas_limit: boolean
 	rotation_limit: boolean
 	uv_rotation: boolean
 	java_face_properties: boolean
 	select_texture_for_particles: boolean
 	bone_binding_expression: boolean
 	animation_files: boolean
-	pose_mode: boolean
-	display_mode: boolean
-	animation_mode: boolean
 	texture_folder: boolean
+	edit_mode?: boolean
+	paint_mode?: boolean
+	display_mode?: boolean
+	animation_mode?: boolean
+	pose_mode?: boolean
 
+	cube_size_limiter?: CubeSizeLimiter
 	/**
 	 * Selects the format
 	 */

package/types/index.d.ts

@@ -1,8 +1,10 @@
 /// <reference types="vue" />
 /// <reference types="three" />
+/// <reference types="@types/tinycolor2" />
 /// <reference types="@types/jquery" />
 /// <reference types="wintersky" />
 
+/// <reference types="./textures" />
 /// <reference types="./action" />
 /// <reference types="./animation" />
 /// <reference types="./canvas" />
@@ -21,9 +23,9 @@
 /// <reference types="./preview" />
 /// <reference types="./project" />
 /// <reference types="./settings" />
-/// <reference types="./textures" />
 /// <reference types="./timeline" />
 /// <reference types="./undo" />
+/// <reference types="./validator" />
 /// <reference types="./util" />
 
 
@@ -79,16 +81,26 @@ type EventName = 'remove_animation'
 	| 'change_active_panel'
 	| 'resize_window'
 	| 'press_key'
+	| 'select_format'
 	| 'convert_format'
+	| 'construct_format'
+	| 'delete_format'
 	| 'select_project'
 	| 'unselect_project'
 	| 'setup_project'
 	| 'update_project_resolution'
-	| 'update_project_settings'
 	| 'merge_project'
 	| 'update_view'
 	| 'update_camera_position'
 	| 'render_frame'
+	| 'construct_model_loader'
+	| 'delete_model_loader'
+	| 'update_recent_project_data'
+	| 'update_recent_project_thumbnail'
+	| 'load_from_recent_project_data'
+	| 'edit_animation_properties'
+	| 'select_preview_scene'
+	| 'unselect_preview_scene'
 
 type IconString = string;
 
@@ -107,6 +119,12 @@ interface MessageBoxOptions {
 	message?: string
 	icon?: string
 	width: number
+	/**
+	 * Display a list of actions to do in the dialog. When clicked, the message box closes with the string ID of the command as first argument.
+	 */
+	commands?: {
+		[id: string]: string | {text: string}
+	}
 }
 
 declare namespace Blockbench {
@@ -167,7 +185,7 @@ declare namespace Blockbench {
 	/**
 	 * Opens a message box
 	 */
-	function showMessageBox(options: MessageBoxOptions, callback: (buttonID: number) => void): void
+	function showMessageBox(options: MessageBoxOptions, callback: (buttonID: number | string) => void): void
 
 	function textPrompt(title: string, value: string, callback: (value: string) => void): void
 	/**

package/types/menu.d.ts

@@ -13,15 +13,21 @@ interface CustomMenuItem {
      */
     searchable?: boolean
     children?: MenuItem[] | (() => MenuItem[])
-    click?: (context?: any, event: Event)
+    click?: (context?: any, event?: Event) => void
 }
 type MenuItem = CustomMenuItem | Action | BarSelect | string;
-
+interface MenuOptions {
+    onOpen?: (position: MouseEvent | HTMLElement, context?: any) => void
+    onClose?: () => void
+    keep_open?: boolean
+    searchable?: boolean
+}
 /**
  * Creates a new context menu
  */
 declare class Menu extends Deletable {
-    constructor(template: MenuItem[])
+    constructor(id: string, template: MenuItem[] | ((context?: any) => MenuItem[]), options?: MenuOptions)
+    constructor(template: MenuItem[] | ((context?: any) => MenuItem[]), options?: MenuOptions)
 
     /**
      * Opens the menu somewhere

package/types/preview.d.ts

@@ -13,7 +13,17 @@ interface PreviewOptions {
     antialias?: boolean
 }
 
-class Preview extends Deletable {
+type RaycastResult = {
+    type: 'keyframe' | 'vertex' | 'cube'
+    event: Event
+    cube?: Cube
+    intersects?: object[]
+    face?: string
+    vertex: any
+    keyframe: Keyframe
+}
+
+declare class Preview extends Deletable {
     constructor(options: PreviewOptions)
 
     id: string
@@ -45,15 +55,7 @@ class Preview extends Deletable {
     }
     raycaster: THREE.Raycaster
 
-    raycast(event: MouseEvent): false | {
-        type: 'keyframe' | 'vertex' | 'cube'
-        event: Event
-        cube?: Cube
-        intersects?: object[]
-        face?: string
-        vertex: any
-        keyframe: Keyframe
-    }
+    raycast(event: MouseEvent): false | RaycastResult
     render(): void
     setProjectionMode(orthographic: boolean): this
     setFOV(fov: number): void

package/types/validator.d.ts

@@ -0,0 +1,60 @@
+declare namespace Validator {
+    const checks: ValidatorCheck[]
+
+	const warnings: []
+	const errors: []
+	/**
+	 * Run the validator
+	 * @param trigger ID of the Blockbench event that triggered the call
+	 */
+	function validate(trigger?: EventName): void
+	/**
+	 * Opens the Validator dialog
+	 */
+	function openDialog(): void
+
+	/**
+	 * Cached trigger IDs
+	 */
+    const triggers: EventName[]
+	/**
+	 * Update the cached triggers list
+	 */
+	function updateCashedTriggers(): void
+}
+
+interface ValidatorCheckOptions {
+	/**
+	 * Function that runs when the validator check runs
+	 */
+	run(): void
+	/**
+	 * Names of events that automatically trigger this check
+	 */
+	update_triggers?: EventName[]
+	condition?: Condition
+}
+interface WarningOrError {
+	message: string
+	buttons?: {
+		name: string
+		icon: IconString
+		click(): void
+	}[]
+}
+declare class ValidatorCheck extends Deletable {
+	constructor(id: string, options: ValidatorCheckOptions)
+
+	/**
+	 * Manually run this check
+	 */
+	update(): void
+	/**
+	 * Throw a warning. This is intended to be used inside the run() method
+	 */
+	warn(...warnings: WarningOrError[]): void
+	/**
+	 * Throw an error. This is intended to be used inside the run() method
+	 */
+	fail(...warnings: WarningOrError[]): void
+}