blockbench-types 4.3.0 → 4.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockbench-types",
-  "version": "4.3.0",
+  "version": "4.5.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/codec.d.ts

@@ -1,8 +1,8 @@
 interface CodecOptions {
 	name: string
 	load?(model: any, file: object, add?: boolean): void
-	compile?(): void
-	parse?(): void
+	compile?(options?: object): void
+	parse?(data: any, path: string): void
 	export?(): void
 	/**
 	 * Generate a file name to suggest when exporting
@@ -10,6 +10,7 @@ interface CodecOptions {
 	fileName?(): string
 	startPath?(): string
 	write?(content: any, path: string): void
+	overwrite?(content: any, path: string, callback: ((path) => void)): void
 	afterDownload?(path): void
 	afterSave?(path): void
 
@@ -30,8 +31,8 @@ declare class Codec extends Deletable {
 	constructor(id: string, options: CodecOptions)
 
 	load?(model: any, file: object, add?: boolean): void
-	compile?(): any
-	parse?(model): void
+	compile?(options?: object): any
+	parse?(data: any, path: string): void
 	export?(): void
 	/**
 	 * Generate a file name to suggest when exporting
@@ -39,6 +40,7 @@ declare class Codec extends Deletable {
 	fileName?(): string
 	startPath?(): string
 	write?(content: any, path: string): void
+	overwrite?(content: any, path: string, callback: ((path) => void)): void
 	afterDownload?(path): void
 	afterSave?(path): void
 	on(event_name: string, callback: (data: object) => void): void

package/types/dialog.d.ts

@@ -1,8 +1,9 @@
 interface DialogFormElement {
 	label: string
 	description?: string
-	type: 'text' | 'number' | 'checkbox' | 'select' | 'radio' | 'textarea' | 'vector' | 'color' | 'file' | 'folder' | 'save' | 'info'
+	type: 'text' | 'number' | 'range' | 'checkbox' | 'select' | 'radio' | 'textarea' | 'vector' | 'color' | 'file' | 'folder' | 'save' | 'info'
 	nocolon?: boolean
+	full_width?: boolean
 	readonly?: boolean
 	value?: any
 	placeholder?: string
@@ -54,7 +55,7 @@ interface DialogOptions {
 	/**
 	 * Array of HTML object strings for each line of content in the dialog.
 	 */
-	lines?: (string|HTMLElement)[]
+	lines?: (HTMLElement | {label?: string, widget?: Widget|(() => Widget), nocolon?: boolean} | string)[]
 	/**
 	 * Creates a form in the dialog
 	 */
@@ -86,6 +87,10 @@ interface DialogOptions {
 	 * List of buttons
 	 */
 	buttons?: string[]
+	/**
+	 * Unless set to false, clicking on the darkened area outside of the dialog will cancel the dialog.
+	 */
+	cancel_on_click_outside?: boolean
 }
 
 interface DialogSidebarOptions {

package/types/file_system.d.ts

@@ -25,6 +25,10 @@ declare namespace Blockbench {
      * Reads the content from the specified files. Desktop app only.
      */
     export function read(files: string[], options?: ReadOptions, callback?: (files: FileResult[]) => void): void
+    /**
+     * Reads the content from the specified files. Desktop app only.
+     */
+    export function readFile(files: string[], options?: ReadOptions, callback?: (files: FileResult[]) => void): void
 
 
 

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
@@ -27,6 +49,9 @@ interface FormatOptions {
 	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
@@ -35,14 +60,21 @@ interface FormatOptions {
 	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
+	texture_folder?: boolean
+	image_editor?: 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 +112,21 @@ 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
+	texture_folder: boolean
+	image_editor: boolean
+	edit_mode: boolean
+	paint_mode: boolean
 	display_mode: boolean
 	animation_mode: boolean
-	texture_folder: 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" />
 
 
@@ -38,7 +40,7 @@ type UUID = string
 declare const isApp: boolean
 
 type EventName = 'remove_animation'
-	| 'display_animation_fram'
+	| 'display_animation_frame'
 	| 'before_closing'
 	| 'create_session'
 	| 'join_session'
@@ -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
 	/**
@@ -197,7 +215,7 @@ declare namespace Blockbench {
 	function addListener(event_names: EventName, callback: (data: object) => void): void
 	function on(event_names: EventName, callback: (data: object) => void): void
 
-	function removeEventListener(event_names: EventName): void
+	function removeListener(event_names: EventName): 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;
-
-/**
- * Creates a new context menu
- */
+interface MenuOptions {
+    onOpen?: (position: MouseEvent | HTMLElement, context?: any) => void
+    onClose?: () => void
+    keep_open?: boolean
+    searchable?: boolean
+}
 declare class Menu extends Deletable {
-    constructor(template: MenuItem[])
+    /**
+     * Creates a new context menu
+     */
+    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/undo.d.ts

@@ -40,21 +40,70 @@ type UndoEntry = {
     action: string
     time: number
 }
+interface AmendEditForm {
+    condition?: Condition
+    type?: 'number'
+    label: string
+    interval_type: 'position' | 'rotation'
+    getInterval?: (Event) => number
+    value?: number | string,
+    min?: number,
+    max?: number,
+    step?: number,
+}
 
 declare class UndoSystem {
     constructor();
+    /**
+     * Starts an edit to the current project by saving the state of the provided aspects
+     * @param aspects Aspects to save
+     */
     initEdit(aspects: UndoAspects): any;
+    /**
+     * Finishes an edit by saving the state of the project after it was changed
+     * @param action Description of the edit
+     */
     finishEdit(action: string, aspects?: UndoAspects): {
         before: any;
         post: any;
         action: any;
         time: number;
     };
+    /**
+     * Cancels an event before it was finished and reset the project to the state before
+     */
     cancelEdit(): void;
+    /**
+     * Add keyframes to the current edit that were indirectly removed by moving other keyframes to their position
+     * @param keyframes 
+     */
     addKeyframeCasualties(keyframes: Keyframe[]): void;
+    /**
+     * Undoes the latest edit
+     */
     undo(remote?: boolean): void;
+    /**
+     * Redoes the latest edit
+     */
+    redo(remote?: boolean): void;
+    /**
+     * Redoes the latest edit
+     */
     redo(remote?: boolean): void;
-    remoteEdit(entry: UndoEntry): void;
-    loadSave(save: UndoSave, reference: UndoSave, mode?: string): void;
+    /**
+     * Provides a menu to amend the latest edit with slightly changed values
+     */
+    amendEdit(form: AmendEditForm, callback: (values: {}, form: {}) => void)
+
+    /**
+     * Loads a specific undo save
+     * @param save The undo save to load
+     * @param reference The current undo save for reference
+     * @param mode The load save modes
+     */
+    loadSave(save: UndoSave, reference: UndoSave, mode?: 'session'): void;
 }
+/**
+ * Blockbench's system to register edits to the project and switch between them
+ */
 declare let Undo: UndoSystem;

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
+}