@md5crypt/layout-pixi v2.0.3

PIXI layout engine

This package builds on top of @md5crypt/layout to provide a layout engine for PIXI.js. Reading that package's docs is recommended before starting doing anything with this one.

Layout elements

The following layout elements are available:

BaseElement

abstract class BaseElement extends LayoutElement

Configuration reference

Properties reference

Function reference

ContainerElement (container)

class ContainerElement extends BaseElement

Configuration reference

Properties reference

GraphicElement (graphic)

class GraphicElement extends BaseElement

Configuration reference

Properties reference

SpriteElement (sprite)

class SpriteElement extends BaseElement

Configuration reference

Properties reference

Texture scaling modes

SlicedSpriteElement (sprite-sliced)

class SlicedSpriteElement extends BaseElement

Configuration reference

Properties reference

Function reference

TiledSpriteElement (sprite-tiled)

class TiledSpriteElement extends BaseElement

Configuration reference

Properties reference

TextElement (text)

class TextElement extends BaseElement

Configuration reference

Properties reference

Function reference

Text fitting

If text fitting is enabled the text font size will be automatically decreased to fit the element size. Text fitting will never increase the configured font size it will only decrease it.

Text fitting operates in two modes:

• If word wrap is disabled, a single iteration is made to compute the target font size, as no re-flow is needed.
• If word wrap is enabled, a binary search is executed to find the target font size. The search is capped at 8 iterations.

RootElement (root)

class RootElement extends BaseElement

The RootElement class is meant to be used as the layout root. It can not be crated via the factory and is meant to be crated by its constructor.

RootElement has a pre-configured layout config of volatile = true, a hardcoded name @root and type equal to root.

Note that RootElement does not have to be used as the root element. For example a ContainerElement will do just as well.

Properties reference

Function reference

Layout factory

The layout factory shipped with this package extends the LayoutFactory from @md5crypt/layout with a few additional features.

Default values

Default config / layout values can be set for created elements. The defaults can be set for all elements or for specific element types individually. This can be done by calling setDefaults on a factory instance.

Texture resolver

Layout elements using textures allow them to be reference via string names. These string names will be resolved using the factories resolveAsset function, which by default will fail with an exception.

To use this feature a onResolveAsset callback must be set that accepts string names and returns texture instances.

Properties reference

Function reference

Using the module

There are two ways to use this library. The simplest one is to just import layoutFactory from @md5crypt/layout-pixi. This will create a default LayoutFactory instance with all the element types registered.

For some applications this can be unwanted as it will bloat the output code with all the element implementations and their underlying PIXI objects.

To avoid this, the individual elements can be imported one by one and registered to a custom factory instance. For example, if all we need is the container and sprite elements, we can do the following:

import ContainerElement from "@md5crypt/layout-pixi/ContainerElement"
import SpriteElement from "@md5crypt/layout-pixi/SpriteElement"
import LayoutFactory from "@md5crypt/layout-pixi/LayoutFactory"

const layoutFactory = new LayoutFactory()

ContainerElement.register(layoutFactory)
SpriteElement.register(layoutFactory)

Using JSX for writing layouts

JSX bindings are provided as an alternative way for writing the layout configurations.

To use the provided JSX bindings where intended to be used with typescript (tsconfig.json should have jsx set to react).

To use the bindings simply cerate a .tsx file and add the following import:

import React from "@md5crypt/layout-pixi/JSXSupport"

JSX.Element is assignable to LayoutElementJSON and can be passed directly to the layout factory.

One gotcha to watch out for is a top level React.Fragment which will result with a element of type jsx-fragment that the factory will refuse to create. To solve this React.toArray can be used. For more details about this function see the reference section below.

Basic syntax

The tag names are mapped to element types, so <container/> will be compiled into {type: "container"}.

All keys from layout and config objects are merged into a single property namespace, together with name and metadata.

So <sprite name="hello" width={100} image="foo" /> will be compiled into

{
    "type": "sprite",
    "name": "hello",
    "layout": {
        "width": 100
    },
    "config": {
        "image": "foo"
    }
}

This (obviously) means that config and layout keys can not overlap.

Components

Stateless function components are supported, see example below:

const Foo = (props: {name: string, children?: React.ReactNode}) => (
    <container name={props.name}>
        {props.children}
    </container>
)

<Foo name="bar">
    <sprite image="foo-bar" />
</Foo>

This will be compiled to:

{
    "type": "container",
    "name": "bar",
    "children": [
        {
            "type": "sprite",
            "config": {
                "image": "foo-bar"
            }
        }
    ]
}

Slots

As a bonus basic slot support was added, see example below:

const Foo = (props: {children?: React.ReactNode}, slots: React.Slots<"bar">) => (
    <container name={props.name}>
        {slots.bar}
        <container>
            {props.children}
        </container>
    </container>
)

<Foo>
    <React.Slot name="bar">
        <sprite image="rab-oof" />
    </React.Slot>
    <sprite image="foo-bar" />
</Foo>

This will be compiled to:

{
    "type": "container",
    "children": [
        {
            "type": "container",
            "children": [
                {
                    "type": "sprite",
                    "config": {
                        "image": "rab-oof"
                    }
                }
            ]
        },
        {
            "type": "sprite",
            "config": {
                "image": "foo-bar"
            }
        }
    ]
}

Function reference

Type reference

Implementing new elements

New element types can be easily added outside the module's code. Let's use the following example implementation of an simple AnimatedSpriteElement to explain the process.

import {
    // our new element will extend BaseElement so it needs to be imported
    BaseElement,

    // the new element's config will extend BaseElement config
    BaseConfig,

    // this is the type of BaseElement's constructor parameter
    BaseConstructorProperties
} from "@md5crypt/layout-pixi/BaseElement"

// we need that type for the register function
import type LayoutFactory from "@md5crypt/layout-pixi/LayoutFactory"

// PIXI stuff that will be needed
import { Texture } from "@pixi/core"
import { AnimatedSprite } from "@pixi/sprite-animated"

// Here we define the element's config properties that will be available in LayoutElementJSON
export interface AnimatedSpriteElementConfig extends BaseConfig {
    images?: (Texture | string)[]
    playing?: boolean
}

export class AnimatedSpriteElement extends BaseElement {
    // we must override handle type to match the PIXI object that this element will use
    declare public handle: AnimatedSprite

    // the static register function that is used to add the element to the layout factory
    public static register(layoutFactory: LayoutFactory) {
        layoutFactory.register("sprite-animated", (factory, name, config) => new this({
            factory,
            name,
            config,
            type: "sprite-animated",
            // the PIXI object instance this element will be using
            handle: new AnimatedSprite([])
        }))
    }

    constructor(props: BaseConstructorProperties<AnimatedSpriteElementConfig>) {
        super(props)
    
        // BaseElement expects all PIXI object's to anchored at the center
        this.handle.anchor.set(0.5, 0.5)
        const config = props.config

        // apply config (if provided)
        if (config) {
            if (config.images) {
                this.images = config.images
            }
            if (config.playing) {
                this.handle.play()
            }
        }
    }

    public set images(value: (Texture | null | string)[]) {
        // here we resolve the string names to Textures using factory.resolveAsset
        this.handle.textures = value.map(x => this.factory.resolveAsset(x))

        // changing the texture can change the element dimensions so we must notify
        // the underlying LayoutElement that its layout must be recalculated
        this.setDirty()
    }

    public get playing() {
        return this.handle.playing
    }

    public set playing(value: boolean) {
        if (value) {
            this.handle.play()
        } else {
            this.handle.stop()
        }
    }

    // this is called every time the layout has changed
    protected onUpdate() {        
        super.onUpdate()

        // we must set the PIXI object's position
        // in most cases the computedLeft / computedTop helper properties from BaseElement can be used
        this.handle.position.set(this.computedLeft, this.computedTop)

        // no fancy scaling options, just stretch the sprite to size
        this.handle.width = this.innerWidth
        this.handle.height = this.innerHeight
    }

    // we must override contentHeight and contentWidth to let the layout know what size
    // is this element's content (in this case the texture dimensions)

    public get contentHeight() {
        return (this.handle.textures[0] as Texture).height
    }

    public get contentWidth() {
        return (this.handle.textures[0] as Texture).width
    }
}

export default AnimatedSpriteElement

// we must inject the new element to the type system by adding
// it to a special interface declared inside the layout-pixi package
declare module "@md5crypt/layout-pixi/ElementTypes" {
    export interface ElementTypes {
        "sprite-animated": {
            config: AnimatedSpriteElementConfig,
            element: AnimatedSpriteElement
        }
    }
}

Remember that the created AnimatedSpriteElement class must be registered in a LayoutFactory instance using AnimatedSpriteElement.register.

If the element type was correctly injected into ElementTypes LayoutElementJSON and JSX elements should automatically recognize the new element type.