Properties for positioning

Before we get into the different positioning properties, note that Pixi’VN considers the default for all position properties to be { x: 0, y: 0 }, which corresponds to the top-left of the element you’re positioning.

Positive numbers move the element to the right and down. So, something at a position of { x: 200, y: 300 } in the game will be 200 pixels from the left edge of the screen and 300 pixels from the top edge of the screen. Negative numbers move the element left and up relative to their starting position.

Position and anchor are the main properties you use to move elements around on the screen. It’s important to understand how they work, because most other positioning properties act as some combination of these two.

Position (pixel)

Position is used to position the component using pixel units.

You can modify it with these properties:

• x: moves the component left-to-right (along the x-axis)
• y: moves the component top-to-bottom (along the y-axis)
• position: an object { x: number, y: number }. You can also set both x and y to the same value, e.g. component.position = 200.

Anchor and pivot

The pivot is an offset, expressed in pixels, from the top-left corner of the component. If you have a component whose texture is 100px x 50px, and want to set the pivot point to the center of the image, you'd set your pivot to (50, 25) - half the width, and half the height.

Anchors are specified in percentages, from 0.0 to 1.0, in each dimension. It has the same utility as the pivot, but to deduce the point where it is located it calculates the percentage of the height and width of the texture. For example, to rotate around the center point of a texture using anchors, you'd set your component's anchor to (0.5, 0.5) - 50% in width and height. Anchors compared to Pivot are easier to use.

You can modify it with these properties:

• anchor: an object { x: number, y: number }. You can also set both x and y to the same value, e.g. conponent.anchor = 0.5.
• pivot: is an object that corresponds to { x: number, y: number }.

Position with percentage

Pixi’VN introduces the ability to position a component by percentage. Its operation is very similar to that of html.

In practice, the percentage will be multiplied by the height or width of the parent component to calculate the position in pixels.

You can modify it with these properties:

• percentageX: for moving things left-to-right (along the x-axis)
• percentageY: for moving things top-to-bottom (along the y-axis).
• percentagePosition: an object { x: number, y: number }. You can also set both x and y to the same value, e.g. conponent.align = 0.5.

import { newLabel, showImage } from "@drincs/pixi-vn";

export const startLabel = newLabel("start", [
    async () => {
        await showImage("egg_head", "egg_head", {
            percentagePosition: 0.5,
            anchor: 0.5,
        });
        await showImage("flower_top", "flower_top", {
            percentagePosition: 0,
        });
        await showImage("panda", "panda", {
            percentageX: 1,
            percentageY: 0,
            anchor: { x: 1, y: 0 },
        });
        await showImage("skully", "skully", {
            percentageX: 0,
            percentageY: 1,
            anchor: { x: 0, y: 1 },
        });
        await showImage("helmlok", "helmlok", {
            percentagePosition: 1,
            anchor: 1,
        });
        await showImage("bunny", "bunny", {
            percentageX: 0.5,
            percentageY: 1,
            anchor: { x: 0.5, y: 1 },
        });
    },
]);

Align

Until now we have seen positioning methods influenced by anchor/pivot. The disadvantage of these methods is that if for example you want to add your component to the center of the screen you will first have to set the anchor to 0.5 and then set the position to half the width and height of the screen. This is where the align property comes in.

Align is a feature originally created for Ren'Py, which was also introduced in Pixi’VN. Align combines position and anchor/pivot to give you a more intuitive way to position your components at the beginning, in the center or in the end of the screen.

Align are specified in percentages, from 0.0 to 1.0, in each dimension. For example if you use 0.25 as a percentage, your component will be positioned at 25% of the screen with anchor at 0.25.

You can modify it with these properties:

• xAlign: for moving things left-to-right (along the x-axis)
• yAlign: for moving things top-to-bottom (along the y-axis).
• align: an object { x: number, y: number }. You can also set both x and y to the same value, e.g. conponent.align = 0.5.

import { newLabel, showImage } from "@drincs/pixi-vn";

export const startLabel = newLabel("start", [
    async () => {
        await showImage("egg_head", "egg_head", { align: 0.5 });
        await showImage("flower_top", "flower_top", { align: 0 });
        await showImage("panda", "panda", { xAlign: 1, yAlign: 0 });
        await showImage("skully", "skully", { xAlign: 0, yAlign: 1 });
        await showImage("helmlok", "helmlok", { align: 1 });
        await showImage("bunny", "bunny", { xAlign: 0.5, yAlign: 1 });
    },
]);