Transitions

In Pixi’VN provides various transition effect to show or remove an canvas component and the possibility to create your own transitions.

( More are on the way )

Dissolve transition

The dissolve transition when:

• shows a component, gradually increases alpha. If a component with the same alias exists, the component will be removed when the new component transition is complete.
• removes a component, gradually decreases alpha.

This transition has been created with the FadeAlphaTicker.

The showWithDissolve function show a canvas element with dissolve transition. This function has the following parameters:

• alias: The alias to identify the component.
• image (Optional): The image to show. If you don't provide the URL, then the alias is used as the URL. It can be:
  • a URL/path. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a array of URL/paths. In this case, will be added a ImageContainer.
  • a { value: string, options: ImageSpriteOptions }, where value is the URL/path and options is the the options of the ImageSprite. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a { value: string[], options: ImageContainerOptions }, where value is the array of URL/paths and options is the the options of the ImageContainer.
  • a canvas component.
• props (Optional): The properties of the effect. It corresponds to the props of the Fade effect.
• priority (Optional): The priority of the effect.

The removeWithDissolve function remove a canvas element with dissolve transition. This function has the following parameters:

• alias: The alias of the component to remove.
• props (Optional): The properties of the effect. It corresponds to the props of the Fade effect.
• priority (Optional): The priority of the effect.

import { Assets, newLabel, removeWithDissolve, showWithDissolve } from "@drincs/pixi-vn";

export const startLabel = newLabel("start_label", [
    async () => {
        await showWithDissolve("alien", "egg_head", { duration: 5 }); 
        await showWithDissolve("human", { 
            value: ["m01-body", "m01-eyes", "m01-mouth"], 
            options: { scale: 0.5, xAlign: 0.7 }, 
        }); 
    },
    async () => {
        await showWithDissolve("alien", "flower_top"); 
        removeWithDissolve("human"); 
    },
], {
    onLoadingLabel: async () => {
        await Assets.load(["egg_head", "m01-mouth", "m01-body", "m01-eyes"]);
    },
});

Fade transition

The fade transition when:

• shows a component, gradually increases alpha. If a component with the same alias exists, the existing component will be removed with a fade-out effect before the new component is shown.
• removes a component, gradually decreases alpha.

This transition has been created with the FadeAlphaTicker.

The showWithFade function show a canvas element with fade transition. This function has the following parameters:

• alias: The alias to identify the component.
• image (Optional): The image to show. If you don't provide the URL, then the alias is used as the URL. It can be:
  • a URL/path. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a array of URL/paths. In this case, will be added a ImageContainer.
  • a { value: string, options: ImageSpriteOptions }, where value is the URL/path and options is the the options of the ImageSprite. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a { value: string[], options: ImageContainerOptions }, where value is the array of URL/paths and options is the the options of the ImageContainer.
  • a canvas component.
• props (Optional): The properties of the effect. It corresponds to the props of the Fade effect.
• priority (Optional): The priority of the effect.

The removeWithFade function remove a canvas element with fade transition. This function has the following parameters:

• alias: The alias of the component to remove.
• props (Optional): The properties of the effect. It corresponds to the props of the Fade effect.
• priority (Optional): The priority of the effect.

import { Assets, newLabel, removeWithFade, showWithFade } from "@drincs/pixi-vn";

export const startLabel = newLabel("start_label", [
    async () => {
        await showWithFade("alien", "egg_head", { duration: 5 }); 
        await showWithFade("human", { 
            value: ["m01-body", "m01-eyes", "m01-mouth"], 
            options: { scale: 0.5, xAlign: 0.7 }, 
        }); 
    },
    async () => {
        await showWithFade("alien", "flower_top"); 
        removeWithFade("human"); 
    },
], {
    onLoadingLabel: async () => {
        await Assets.load(["egg_head", "m01-mouth", "m01-body", "m01-eyes"]);
    },
});

Move in/out transition

The move in/out transition when:

• shows a component, moves the component from outside of the right or left ot top or bottom end of the canvas to the canvas component position. If a component with the same alias exists, the existing component will be removed with a move-out effect before the new component is shown.
• removes a component, moves the component from a position to outside of the right or left ot top or bottom end of the canvas.

This transition has been created with the MoveTicker.

The moveIn function show a canvas element with move in transition. This function has the following parameters:

• alias: The alias to identify the component.
• image (Optional): The image to show. If you don't provide the URL, then the alias is used as the URL. It can be:
  • a URL/path. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a array of URL/paths. In this case, will be added a ImageContainer.
  • a { value: string, options: ImageSpriteOptions }, where value is the URL/path and options is the the options of the ImageSprite. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a { value: string[], options: ImageContainerOptions }, where value is the array of URL/paths and options is the the options of the ImageContainer.
  • a canvas component.
• props (Optional): The properties of the effect. It combines the properties of the Move effect with following properties:
  • direction: The direction of the move. It can be right, left, top, bottom. default is right.
  • removeOldComponentWithMoveOut (Optional): If a component with the same alias exists, the existing component will be removed with a moveOut effect when the new component transition is complete. default is false.
• priority (Optional): The priority of the effect.

The moveOut function remove a canvas element with move out transition. This function has the following parameters:

• alias: The alias of the component to remove.
• props (Optional): The properties of the effect. It combines the properties of the Move effect with following properties:
  • direction: The direction of the move. It can be right, left, top, bottom. default is right.
• priority (Optional): The priority of the effect.

import { Assets, moveIn, moveOut, newLabel } from "@drincs/pixi-vn";

export const startLabel = newLabel("start_label", [
    async () => {
        await moveIn("alien", "egg_head", { direction: "up" }); 
        await moveIn("human", { 
            value: ["m01-body", "m01-eyes", "m01-mouth"], 
            options: { scale: 0.5, xAlign: 0.7 }, 
        }); 
    },
    async () => {
        await moveIn("alien", "flower_top", { direction: "up" }); 
        moveOut("human"); 
    },
], {
    onLoadingLabel: async () => {
        await Assets.load(["egg_head", "m01-mouth", "m01-body", "m01-eyes"]);
    },
});

Push in/out transition

The push in/out transition when:

• shows a component, moves the component from outside of the right or left ot top or bottom end of the canvas to the canvas component position. If a component with the same alias exists, the existing component will be removed with a push-out effect while the transition of the new component is in progress.
• removes a component, moves the component from a position to outside of the right or left ot top or bottom end of the canvas.

This transition has been created with the MoveTicker.

The pushIn function show a canvas element with push in transition. This function has the following parameters:

• alias: The alias to identify the component.
• image (Optional): The image to show. If you don't provide the URL, then the alias is used as the URL. It can be:
  • a URL/path. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a array of URL/paths. In this case, will be added a ImageContainer.
  • a { value: string, options: ImageSpriteOptions }, where value is the URL/path and options is the the options of the ImageSprite. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a { value: string[], options: ImageContainerOptions }, where value is the array of URL/paths and options is the the options of the ImageContainer.
  • a canvas component.
• props (Optional): The properties of the effect. It combines the properties of the Move effect with following properties:
  • direction: The direction of the move. It can be right, left, top, bottom. default is right.
• priority (Optional): The priority of the effect.

The pushOut function remove a canvas element with push out transition. This function has the following parameters:

• alias: The alias of the component to remove.
• props (Optional): The properties of the effect. It combines the properties of the Move effect with following properties:
  • direction: The direction of the move. It can be right, left, top, bottom. default is right.
• priority (Optional): The priority of the effect.

import { Assets, newLabel, pushIn, pushOut } from "@drincs/pixi-vn";

export const startLabel = newLabel("start_label", [
    async () => {
        await pushIn("alien", "egg_head"); 
        await pushIn("human", { 
            value: ["m01-body", "m01-eyes", "m01-mouth"], 
            options: { scale: 0.5, xAlign: 0.7 }, 
        }); 
    },
    async () => {
        await pushIn("alien", "flower_top", { direction: "up" }); 
        pushOut("human"); 
    },
], {
    onLoadingLabel: async () => {
        await Assets.load(["egg_head", "m01-mouth", "m01-body", "m01-eyes"]);
    },
});

Zoom in/out transition

The zoom in/out transition when:

• shows a component, scales the component from 0, from outside of the right or left ot top or bottom end of the canvas, to the original scale and to the component position. If a component with the same alias exists, the existing component will be removed when the new component transition is complete.
• removes a component, scales the component from the original scale to 0, to outside of the right or left ot top or bottom end of the canvas.

This transition has been created with the ZoomTicker.

The zoomIn function show a canvas element with zoom in transition. This function has the following parameters:

• alias: The alias to identify the component.
• image (Optional): The image to show. If you don't provide the URL, then the alias is used as the URL. It can be:
  • a URL/path. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a array of URL/paths. In this case, will be added a ImageContainer.
  • a { value: string, options: ImageSpriteOptions }, where value is the URL/path and options is the the options of the ImageSprite. In this case, if URL/path is a video will be added a VideoSprite, else a ImageSprite.
  • a { value: string[], options: ImageContainerOptions }, where value is the array of URL/paths and options is the the options of the ImageContainer.
  • a canvas component.
• props (Optional): The properties of the effect. It combines the properties of the Zoom effect with following properties:
  • direction: The direction of the zoom. It can be right, left, top, bottom. default is right.
  • removeOldComponentWithZoomOut (Optional): If a component with the same alias exists, the existing component will be removed with a zoomOut effect when the new component transition is complete. default is false.
• priority (Optional): The priority of the effect.

The zoomOut function remove a canvas element with zoom out transition. This function has the following parameters:

• alias: The alias of the component to remove.
• props (Optional): The properties of the effect. It combines the properties of the Zoom effect with following properties:
  • direction: The direction of the zoom. It can be right, left, top, bottom. default is right.
• priority (Optional): The priority of the effect.

import { Assets, newLabel, zoomIn, zoomOut } from "@drincs/pixi-vn";

export const startLabel = newLabel("start_label", [
    async () => {
        await zoomIn("alien", "egg_head"); 
        await zoomIn("human", { 
            value: ["m01-body", "m01-eyes", "m01-mouth"], 
            options: { scale: 0.5, xAlign: 0.7 }, 
        }); 
    },
    async () => {
        await zoomIn("alien", "flower_top"); 
        zoomOut("human"); 
    },
], {
    onLoadingLabel: async () => {
        await Assets.load(["egg_head", "m01-mouth", "m01-body", "m01-eyes"]);
    },
});

Create your own transition

Create your own transition is very simple, you can combine more Animations and Effects to create your own transition.

( The Pixi’VN Team welcomes new proposals/sharing to make this library more and more complete. So you can create a discussion to share/propose it. )

To better understand how to create one, a simplified version of showWithDissolve will be left as an example below.

import { canvas, FadeAlphaTicker, FadeAlphaTickerProps, ImageSprite, UPDATE_PRIORITY } from "@drincs/pixi-vn"

export async function showWithDissolve(
    alias: string,
    canvasElement: ImageSprite,
    props: FadeAlphaTickerProps = {},
    priority?: UPDATE_PRIORITY,
): Promise<string[] | undefined> {
    canvas.add(alias, canvasElement)
    canvasElement.alpha = 0

    let effect = new FadeAlphaTicker({
        ...props,
        type: "show",
        startOnlyIfHaveTexture: true,
    }, undefined, priority)
    let id = canvas.addTicker(alias, effect)
    if (canvasElement.haveEmptyTexture) {
        await canvasElement.load()
    }
    if (id) {
        return [id]
    }
}

Force completion of the transition at the end of the step

It is recommended to create a transition that forces the completion of the transition at the end of the step.

To do this, you can use the canvas.completeTickerOnStepEnd function.

This example shows how to create a transition that forces the completion of the transition at the end of the step.

import { canvas, FadeAlphaTicker, FadeAlphaTickerProps, ImageSprite, UPDATE_PRIORITY } from "@drincs/pixi-vn"

export default async function showWithDissolve(
    alias: string,
    canvasElement: ImageSprite,
    props: FadeAlphaTickerProps && {
        mustBeCompletedBeforeNextStep?: boolean
    } = {},
    priority?: UPDATE_PRIORITY,
): Promise<string[] | undefined> {
    let mustBeCompletedBeforeNextStep = props.mustBeCompletedBeforeNextStep ?? true
    canvas.add(alias, canvasElement)
    canvasElement.alpha = 0

    let effect = new FadeAlphaTicker({
        ...props,
        type: "show",
        startOnlyIfHaveTexture: true,
    }, undefined, priority)
    let id = canvas.addTicker(alias, effect)
    if (id) { 
        mustBeCompletedBeforeNextStep && canvas.completeTickerOnStepEnd({ id: id }) 
    } 
    if (canvasElement.haveEmptyTexture) {
        await canvasElement.load()
    }
    if (id) {
        return [id]
    }
}

If a component with the same alias already exists

If a component with the same alias already exists, you can

• Let it be replaced
• Remove the previous component with a transition
• Remove the previous component when the new component transition is complete

Remove the previous component when the new component transition is complete

To remove the previous component when the new component transition is complete, you can use the aliasToRemoveAfter property. The aliasToRemoveAfter property is the alias of the component to remove when the new component transition is complete, it is available in all Animations and Effects provided by Pixi’VN.

import { canvas, FadeAlphaTicker, FadeAlphaTickerProps, ImageSprite, UPDATE_PRIORITY } from "@drincs/pixi-vn"

export default async function showWithDissolve(
    alias: string,
    canvasElement: ImageSprite,
    props: FadeAlphaTickerProps = {},
    priority?: UPDATE_PRIORITY,
): Promise<string[] | undefined> {
    let oldCanvasAlias: string | undefined = undefined
    if (canvas.find(alias)) { 
        oldCanvasAlias = alias + "_temp_disolve"
        canvas.editAlias(alias, oldCanvasAlias) 
    } 

    canvas.add(alias, canvasElement)
    oldCanvasAlias && canvas.copyCanvasElementProperty(oldCanvasAlias, alias) 
    oldCanvasAlias && canvas.transferTickers(oldCanvasAlias, alias, "duplicate") 
    canvasElement.alpha = 0

    let effect = new FadeAlphaTicker({
        ...props,
        type: "show",
        aliasToRemoveAfter: oldCanvasAlias, 
        startOnlyIfHaveTexture: true,
    }, undefined, priority)
    let id = canvas.addTicker(alias, effect)
    if (canvasElement.haveEmptyTexture) {
        await canvasElement.load()
    }
    if (id) {
        return [id]
    }
}

Remove the previous component with a transition

To remove the previous component with a transition, you can run a Animations or Effects to remove the previous component before the new component transition is complete.

To do this you will also need to use many other functions depending on the transition you are creating.

import { canvas, FadeAlphaTicker, FadeAlphaTickerProps, ImageSprite, UPDATE_PRIORITY, Pause } from "@drincs/pixi-vn"

export default async function showWithFade(
    alias: string,
    canvasElement: ImageSprite,
    props: FadeAlphaTickerProps = {},
    priority?: UPDATE_PRIORITY,
): Promise<string[] | undefined> {
    let oldCanvasAlias: string | undefined = undefined
    if (canvas.find(alias)) { 
        oldCanvasAlias = alias + "_temp_fade"
        canvas.editAlias(alias, oldCanvasAlias) 
    } 

    canvas.add(alias, canvasElement)
    oldCanvasAlias && canvas.copyCanvasElementProperty(oldCanvasAlias, alias) 
    oldCanvasAlias && canvas.transferTickers(oldCanvasAlias, alias, "duplicate") 
    canvasElement.alpha = 0

    let res: undefined | string[] = undefined

    if (oldCanvasAlias) { 
        let id1 = canvas.addTicker(oldCanvasAlias, 
            new FadeAlphaTicker({ 
                ...props, 
                type: "hide", 
                startOnlyIfHaveTexture: true, 
                tickerAliasToResume: alias 
            }, undefined, priority), 
        ) 
        if (id1) { 
            res = [id1] 
        } 
        let id2 = canvas.addTicker(alias, 
            new FadeAlphaTicker({ 
                ...props, 
                type: "show", 
                startOnlyIfHaveTexture: true, 
                aliasToRemoveAfter: oldCanvasAlias, 
            }, undefined, priority) 
        ) 
        canvas.pauseTicker(alias) 
        if (id2) { 
            res ? res.push(id2) : res = [id2] 
        } 
    } 
    else { 
        let effect = new FadeAlphaTicker({
            ...props,
            type: "show",
            startOnlyIfHaveTexture: true,
        }, undefined, priority)
        let id = canvas.addTicker(alias, effect)
        if (id) { 
            res = [id] 
        } 
    } 
    if (canvasElement.haveEmptyTexture) {
        await canvasElement.load()
    }
    return res 
}