pixi-zunil-ui

pixi-zunil-ui is a very simple layout and ui library for PixiJS.

The easiest way to see it in action is to look at the examples.

If you like this, you may like my other PixiJS library pixi-actions.

This is manually for personal use, using an API which is useful for me. If you want more well-developed ui and layout libraries, the official pixi-ui and pixi-layout are probably more suitable. That said, if you like this library, then feel free to use it!

Installing

npm install pixi-zunil-ui

Some of the UI components require assets. If you want to use these, the assets are included in the package and should be copied into the assets folder of your project. This can be done as part of an appropriate script in package.json if you want to make sure it's kept up-to-date, or as a one-off:

cp node_modules/pixi-zunil-ui/assets/* public/zunil-ui/

The copied assets will also need loading when initialising the application. Where "zunil-ui" is the path to the folder into which you copied the assets.

await Z.Application.loadAssets("zunil-ui");

General Usage

You can import just the classes you need, or import everything with a namespace such as Z:

import { Panel } from "pixi-zunil-ui";
import * as Z from "pixi-zunil-ui";

Application

Z.Application is a replacement for PIXI.Application which handles:

• scaling and placement of the stage according to a chosen resize mode
• switching between various screens
• maintaing a modal stack
• ensuring screens and modals take up the full screen

Resize modes mean you can code to target a specific width/height no matter the screen size. The stage is scaled such that your application fits on the screen.

import * as Z from "pixi-zunil-ui";
const app = new Z.Application();
await app.init({
  targetHeight: 1920,
  targetWidth: 1080,
  resizeMode: "extend",
  // plus any other PIXI.Application options...
});

Screens and Modals

Screens and modals will take up the full screen, even as you resize the application.

app.setScreen(new Z.MenuScreen());
app.pushModal(new Z.TextModal({ text: "This is a message", dismissible: true }));

Screens should implement onSizeChanged(_width: number, _height: number): void to layout their elements according to the size of the screen. This ensures that even if the user resizes the window, all the screen elements are correctly placed.

If you're using Tables, then you should resize the root table here.

Components

Every component has a mutable default props object which are applied when a new component of that type is instantiated. If you supply any props to the constructor, any values supplied override the defaults. In this way you can set a "look and feel" for your application.

Z.Panel.defaultProps.color = 0x90bade;
Z.TextButton.defaultProps.rounded = "lg";
Z.Button.defaultProps.rounded = "md";

Currently, the components which exist are:

• Button
• TextButton
• Panel
• Label

Tables

The crux of the layout system is the Table class. It's a PIXI.Container that manages the size and position of its child elements.

Creating a Table

You can create an add a table to the stage as with any other PIXI.Container. Be sure to set the table's size as appropriate; this is what determines the bounds of its child elements.

const root = new Table();
root.setSize(500, 500);
container.addChild(root);

If you are using a table to manage layout of the whole stage, and you want to take advantage of the automatic resizing capabilities, it makes sense to add a resize listener. For example, if you are using the resizeTo option, and adding the root directly to the stage:

await app.init({ resizeTo: window });

const root = new Table();
app.stage.addChild(root);
function resizeTable() {
	root.setSize(app.renderer.width, app.renderer.height);
}
app.renderer.on('resize', resizeTable);
resizeTable();

Layout

Tables are made up of rows, and rows are made up of cells. Rows and cells have a basis, which determines how much room they take up:

• number - the size in pixels to take up
• string of the form "10%" - the percentage of the total space in pixels
• null (default) - all remaining space is divided equally by items with a null-basis

That is, a row with a basis of 50 will have a height of 50px. A cell with a basis of 25% will take up 25% of the total available width.

A cell can also have any number of elements. An element is a PIXI.Container, a sizing strategy and an anchor. Each of the cell's elements are added to the table, and the position and size of each are managed according to the sizing strategy and anchor.

| Sizing strategy| Details | |:---|:---| | null | Default. Do not size the element, manage only the position. | | 'contain' | Set size as large as possible whilst still fitting within the cell. Maintain aspect ratio. | | 'cover' | Set size to the minimum size such that the cell is entired covered. Maintain aspect ratio. | | 'stretch' or 'cover!' | Set size to the exact size of the cell. Ignore aspect ratio. | | grow | If the cell is larger than the initial size, grow the element to fit the cell. Maintain aspect ratio. | | grow! | If the cell is larger than the initial size, grow the element to fit the cell. Ignore aspect ratio. | | shrink | If the cell is smaller than the initial size, shrink the element to fit the cell. Maintain aspect ratio. | | shrink! | If the cell is smaller than the initial size, shrink the element to fit the cell. Ignore aspect ratio. |

Cell anchor is a PIXI.Point representing the x and y anchors. There are some self-explanatory helper constants:

• CellAnchor.TopLeft
• CellAnchor.Top
• CellAnchor.TopRight
• CellAnchor.Left
• CellAnchor.Middle (default)
• CellAnchor.Right
• CellAnchor.BottomLeft
• CellAnchor.Bottom
• CellAnchor.BottomRight

API

Add rows, cells and elements to the table using these methods:

• Table.row(basis: Basis = null)
• Table.cell(basis: Basis = null)
• Table.element(element: PIXI.Container, strategy: SizingStrategy = null, anchor: PIXI.Point = null)

You can turn on debug drawing which draws a red outline around each cell:

• Table.debug = true;

It is recommended to disable prettier for the table definition so you can use the indentation to visualise the layout.

Examples

All of these examples are show with debug draw on.