@drincs/pixi-vn
Version:
Pixi'VN is a npm package that provides various features for creating visual novels.
402 lines (399 loc) • 15 kB
text/typescript
import * as pixi_js from 'pixi.js';
import { Container, ApplicationOptions } from 'pixi.js';
import { Devtools } from '@pixi/devtools';
import CanvasBaseItem from '../classes/canvas/CanvasBaseItem.cjs';
import TickerBase from '../classes/ticker/TickerBase.cjs';
import { PauseType } from '../types/PauseType.cjs';
import { RepeatType } from '../types/RepeatType.cjs';
import CanvasBaseItemMemory from '../interface/canvas/memory/CanvasBaseItemMemory.cjs';
import ExportedCanvas from '../interface/export/ExportedCanvas.cjs';
import PauseTickerType from '../types/PauseTickerType.cjs';
import Ticker from '../interface/Ticker.cjs';
import TickerArgs from '../interface/TickerArgs.cjs';
import TickerHistory from '../interface/TickerHistory.cjs';
import TickersSequence from '../interface/TickersSequence.cjs';
import '../types/TickerIdType.cjs';
import '../interface/canvas/memory/ContainerMemory.cjs';
import '../types/ContainerChild.cjs';
/**
* This class is responsible for managing the canvas, the tickers, the events, and the window size and the children of the window.
*/
declare class CanvasManager {
/**
* The PIXI Application instance.
* It not recommended to use this property directly.
*/
get app(): pixi_js.Application<pixi_js.Renderer>;
get gameLayer(): Container<pixi_js.ContainerChild>;
/**
* If the manager is initialized.
*/
get isInitialized(): boolean;
/**
* This is the div that have same size of the canvas.
* This is useful to put interface elements.
* You can use React or other framework to put elements in this div.
*/
get htmlLayout(): HTMLElement | undefined;
set htmlLayout(value: HTMLElement);
get canvasWidth(): number;
get canvasHeight(): number;
set canvasWidth(value: number);
set canvasHeight(value: number);
get screen(): pixi_js.Rectangle;
/**
* Initialize the PixiJS Application and the interface div.
* This method should be called before any other method.
* @param element The html element where I will put the canvas. Example: document.body
* @param width The width of the canvas
* @param height The height of the canvas
* @param options The options of PixiJS Application
* @param devtoolsOptions The options of the devtools. You can read more about it in the [PixiJS Devtools documentation](https://pixijs.io/devtools/docs/plugin/)
* @example
* ```typescript
* const body = document.body
* if (!body) {
* throw new Error('body element not found')
* }
* await canvas.initialize(body, {
* width: 1920,
* height: 1080,
* backgroundColor: "#303030"
* })
* ```
*/
initialize(element: HTMLElement, options: Partial<ApplicationOptions> & {
width: number;
height: number;
}, devtoolsOptions?: Devtools): Promise<void>;
/**
* @deprecated
*
* This type of initialization has been deprecated move the width and height to the options parameter.
*
* ```typescript
* await canvas.initialize(body, {
* width: 1920,
* height: 1080,
* // ...
* })
*/
initialize(element: HTMLElement, width: number, height: number, options?: Partial<ApplicationOptions>, devtoolsOptions?: Devtools): Promise<void>;
/**
* Initialize the interface div and add it into a html element.
* @param element it is the html element where I will put the interface div. Example: document.getElementById('root')
* @example
* ```tsx
* const root = document.getElementById('root')
* if (!root) {
* throw new Error('root element not found')
* }
* canvas.initializeHTMLLayout(root)
* const reactRoot = createRoot(canvas.htmlLayout)
* reactRoot.render(
* <App />
* )
* ```
*/
initializeHTMLLayout(element: HTMLElement): void;
/**
* The children of the canvas.
*/
get children(): pixi_js.ContainerChild[];
/**
* Copy the properties of an old canvas element to a new canvas element.
* @param oldAlias Old alias
* @param newAlias New alias
* @returns
*/
copyCanvasElementProperty<T extends CanvasBaseItemMemory>(oldAlias: T | CanvasBaseItem<T> | string, newAlias: CanvasBaseItem<T> | string): Promise<void>;
/**
* Transfer the tickers from an old alias to a new alias.
* @param oldAlias Old alias
* @param newAlias New alias
* @param mode If "move", the old alias will be removed from the ticker. If "duplicate", the old alias will be kept in the ticker.
*/
transferTickers(oldAlias: string, newAlias: string, mode?: "move" | "duplicate"): void;
/**
* Add a canvas element to the canvas.
* If there is a canvas element with the same alias, all "style", zIndex, and {@link TickerBase} will be transferred to the new canvas element,
* and the old canvas element will be removed.
* @param alias The alias of the canvas element.
* @param canvasComponent The canvas elements to be added.
* @param options The options of the canvas element.
* @example
* ```typescript
* const texture = await Assets.load('https://pixijs.com/assets/bunny.png');
* const sprite = Sprite.from(texture);
* canvas.add("bunny", sprite);
* ```
*/
add(alias: string, canvasComponent: CanvasBaseItem<any>, options?: {
/**
* If there is a canvas element with the same alias, the "style" of the old canvas element will be imported to the new canvas element.
* @default false
*/
ignoreOldStyle?: boolean;
/**
* The zIndex of the canvas element.
* @default undefined
*/
zIndex?: number;
}): void;
/**
* @deprecated use canvas.add
*/
addCanvasElement(alias: string, canvasElement: CanvasBaseItem<any>): void;
/**
* Remove a canvas element from the canvas.
* And remove all tickers that are not connected to any canvas element.
* @param alias The alias of the canvas element to be removed.
* @param options The options of the canvas element.
* @returns
* @example
* ```typescript
* canvas.remove("bunny");
* ```
*/
remove(alias: string | string[], options?: {
/**
* If true, the tickers that are connected to the canvas element will not be removed.
* @default false
*/
ignoreTickers?: boolean;
}): void;
/**
* @deprecated use canvas.remove
*/
removeCanvasElement(alias: string | string[]): void;
/**
* Get a canvas element by the alias.
* @param alias The alias of the canvas element.
* @returns The canvas element.
* @example
* ```typescript
* const sprite = canvas.find<Sprite>("bunny");
* ```
*/
find<T extends CanvasBaseItem<any>>(alias: string): T | undefined;
/**
* @deprecated use canvas.find
*/
getCanvasElement<T extends CanvasBaseItem<any>>(alias: string): T | undefined;
/**
* Check if a DisplayObject is on the canvas.
* @param pixiElement The DisplayObject to be checked.
* @returns If the DisplayObject is on the canvas.
*/
canvasElementIsOnCanvas<T extends Container>(pixiElement: T): boolean;
/**
* Remove all canvas elements from the canvas.
* And remove all tickers that are not connected to any canvas element.
*/
removeAll(): void;
/**
* Edit the alias of a canvas element. The tickers that are connected to the canvas element will be transferred.
* @param oldAlias The old alias of the canvas element.
* @param newAlias The new alias of the canvas element.
* @param options The options of the canvas element.
*/
editAlias(oldAlias: string, newAlias: string, options?: {
/**
* If true, the tickers that are connected to the canvas element will not be transferred.
* @default false
*/
ignoreTickers?: boolean;
}): void;
/** Edit Tickers Methods */
/**
* Currently tickers that are running.
*/
get currentTickers(): {
[id: string]: TickerHistory<any>;
};
get currentTickersList(): TickerHistory<any>[];
/**
* The steps of the tickers
*/
get currentTickersSteps(): {
[alias: string]: {
[tickerId: string]: TickersSequence;
};
};
/**
* Run a ticker. You can run multiple addTicker with the same alias and different tickerClasses.
* If you run a ticker with the same alias and tickerClass, the old ticker will be removed.
* If already exists a sequence of tickers with the same alias, it will be removed.
* @param canvasElementAlias The alias of the canvas element that will use the ticker.
* @param ticker The ticker class to be run.
* @returns The id of the ticker.
* @example
* ```typescript
* canvas.addTicker("alien", new RotateTicker({ speed: 0.2 }))
* ```
*/
addTicker<TArgs extends TickerArgs>(canvasElementAlias: string | string[], ticker: TickerBase<TArgs>): string | undefined;
private pushTicker;
private pushEndOfTicker;
/**
* @deprecated use canvas.addTickersSequence
*/
addTickersSteps(alias: string, steps: (Ticker<any> | RepeatType | PauseType)[], currentStepNumber?: number): string | undefined;
/**
* Run a sequence of tickers.
* @param alias The alias of canvas element that will use the tickers.
* @param steps The steps of the tickers.
* @param currentStepNumber The current step number. It is used to continue the sequence of tickers.
* @returns The id of the sequence of tickers.
* @example
* ```typescript
* canvas.addTickersSequence("alien", [
* new RotateTicker({ speed: 0.1, clockwise: true }, 2), // 2 seconds
* Pause(1), // 1 second
* new RotateTicker({ speed: 0.2, clockwise: false }, 2),
* Repeat,
* ])
* ```
*/
addTickersSequence(alias: string, steps: (Ticker<any> | RepeatType | PauseType)[], currentStepNumber?: number): string | undefined;
private runTickersSequence;
private nextTickerStep;
onEndOfTicker(tickerId: string, options: {
aliasToRemoveAfter: string[] | string;
tickerAliasToResume: string[] | string;
ignoreTickerSteps?: boolean;
}): void;
/**
* Remove a connection between a canvas element and a ticker.
* And remove the ticker if there is no canvas element connected to it.
* @param alias The alias of the canvas element that will use the ticker.
* @param ticker The ticker class to be removed.
* @example
* ```typescript
* canvas.unlinkComponentFromTicker("alien", RotateTicker)
* ```
*/
unlinkComponentFromTicker(alias: string | string[], ticker?: typeof TickerBase<any> | TickerBase<any> | string): void;
/**
* Remove all tickers that are not connected to any existing canvas element.
*/
private removeTickersWithoutAssociatedCanvasElement;
/**
* Remove all tickers from the canvas.
*/
removeAllTickers(): void;
/**
* Remove a ticker by the id.
* @param tickerId The id of the ticker.
*/
removeTicker(tickerId: string | string[]): void;
/**
* @deprecated use canvas.pauseTicker
*/
putOnPauseTicker(alias: string, options?: PauseTickerType): void;
/**
* Pause a ticker. If a paused ticker have a time to be removed, it will be removed after the time.
* @param alias The alias of the canvas element that will use the ticker.
* @param options The options of the pause ticker.
*/
pauseTicker(alias: string, options?: PauseTickerType): void;
/**
* @deprecated use canvas.resumeTicker
*/
resumeTickerPaused(alias: string | string[]): void;
/**
* Resume a ticker.
* @param alias The alias of the canvas element that will use the ticker.
*/
resumeTicker(alias: string | string[]): void;
/**
* Check if a ticker is paused.
* @param alias The alias of the canvas element that will use the ticker.
* @param tickerId The ticker that will be checked.
* @returns If the ticker is paused.
*/
isTickerPaused(alias: string, tickerId?: string): boolean;
/**
* Add a ticker that must be completed before the next step.
* This method is used for example into a transition between scenes.
* @param step The step that the ticker must be completed before the next step.
*/
completeTickerOnStepEnd(step: {
/**
* The id of the step.
*/
id: string;
/**
* If is a sequence of tickers, the alias of the sequence of tickers.
*/
alias?: string;
}): void;
/**
* This method force the completion of the tickers that are running.
* This funcions is called in the next step.
* @param id The id of the ticker. If the alias provided, the id is the id of the sequence of tickers.
* @param alias The alias of the sequence of tickers.
*/
forceCompletionOfTicker(id: string, alias?: string): void;
/**
* Add a layer to the canvas.
* @param label The label of the layer.
* @param layer The layer to be added.
* @returns The layer.
* @example
* ```typescript
* const uiLayer = new Container();
* canvas.addLayer("ui", uiLayer);
* ```
*/
addLayer(label: string, layer: Container): Container<pixi_js.ContainerChild> | undefined;
/**
* Get a layer from the canvas.
* @param label The label of the layer.
* @returns The layer.
* @example
* ```typescript
* const uiLayer = canvas.getLayer("ui");
* ```
*/
getLayer(label: string): Container<pixi_js.ContainerChild> | null;
/**
* Remove a layer from the canvas.
* @param label The label of the layer to be removed.
* @example
* ```typescript
* canvas.removeLayer("ui");
* ```
*/
removeLayer(label: string): void;
/**
* Extract the canvas as an image.
* @returns The image as a base64 string.
*/
extractImage(): Promise<string>;
/**
* Clear the canvas and the tickers.
*/
clear(): void;
/**
* Export the canvas and the tickers to a JSON string.
* @returns The JSON string.
*/
exportJson(): string;
/**
* Export the canvas and the tickers to an object.
* @returns The object.
*/
export(): ExportedCanvas;
/**
* Import the canvas and the tickers from a JSON string.
* @param dataString The JSON string.
*/
importJson(dataString: string): Promise<void>;
/**
* Import the canvas and the tickers from an object.
* @param data The object.
*/
import(data: object): Promise<void>;
}
export { CanvasManager as default };