uiplugin

The HUD: its own PixiJS stage over the game, with panels, buttons, bars, modals and focus.

#Putting it in a scene

The HUD is a PixiJS stage of its own, drawn by its own renderer on a transparent canvas that the page lays over the game's canvas in the same grid cell and at the same size. That size is the game renderer's size, which is the engine prefab's width and height, or the window's under render2d's fit: "window". A scene with nothing but a UI, a menu, names no game renderer and takes the engine prefab's size. The renderer draws at the screen's pixel ratio, so the game may draw at any size under it and the UI stays sharp. When the window is resized under fit: "window", the canvas takes the new size and every panel is placed again by its anchor. When render2d's fit scales the game's canvas, the UI's canvas is sized on the page by the same scale, so it still lies over the game's. A local actor that shows things is listed after ui, because the UI reads world.ui in its tick.

"plugins": ["loader", "scenemanager", "player", "render2d", "ui"],
"world": {
  "ui": {
    "keys": { "up": ["ArrowUp", "w"], "down": ["ArrowDown", "s"], "left": ["ArrowLeft", "a"], "right": ["ArrowRight", "d"], "press": ["Enter", " "], "back": "Escape" },
    "panels": {
      "hud": { "anchor": "top-left", "at": [8, 8], "size": [200, 48] },
      "pause": { "anchor": "center", "size": [240, 160], "layer": 10, "modal": true, "backdrop": { "color": 0, "alpha": 0.5 }, "key": "Escape", "group": "menus" }
    },
    "styles": {
      "title": { "fontFamily": "monospace", "fontSize": 24, "fill": "#ffffff", "stroke": { "color": 0, "width": 3, "join": "round" } }
    }
  }
}

The UI has no row, so world.ui is read off the scene and never sent. A world.ui in the manager scene is every scene's until a scene gives its own.

#Properties

Read from world.ui.

.keys : { up, down, left, right, press, back }

The keys the UI acts on, each one key or a list of them. up, down, left and right move the focus, press presses the focused thing, and back goes out of a modal. Name all six. A key is named by its place on the keyboard, not by the character it types: a, ' ', Enter, Escape, ArrowUp. A gamepad's keys, Pad0 and the rest, are named the same way, and reach the UI when player plays by actions.

.panels : { [name]: Panel }

Everything the UI draws is on a panel, a plain PIXI.Container named here.

.styles : { [name]: object }

Named options objects, each passed as it is to PixiJS or to button. style(name) hands back a copy of one. A text style's outline, stroke, carries "join": "round": the canvas mitres an outline's corners by default, and at a glyph's sharp points they run out into spikes.

#Modals, menus and focus

#Drawn between steps

Each frame, just before it draws, every thing on the stage, and on a panel drawn on a surface, is put between where the last two steps left it: its position in a straight line, its turn the short way round, and its scale. Once the frame is drawn each is put back where it was set. A dial's hand turned from a row turns as smoothly as the game's own things move under it.

#Methods

On the page, through plugins.ui.

Showing things

show( panel, key, make ) : T

Puts a thing on a panel, in an actor's tick, every frame it wants the thing shown. make runs the first time and returns the PIXI container to show, and the same object comes back every frame after that, for the actor to write this frame's values on. The thing's PixiJS label is key, so anything that reads the panel finds it. After a frame in which nobody showed it, it is destroyed with its children and its Graphics contexts. A texture it draws is the loader's and stays. So a row that ends takes its UI with it, and a thing drawn only sometimes is shown behind an if. A key is shown once a frame on a panel. show is the only way onto a panel. Something that cannot be seen was not shown this frame, or was shown off the canvas, under another panel or pinned behind the camera.

panel( name ) : PIXI.Container

The panel's container. Its boundsArea is its size.

style( name ) : object

A copy of one of styles.

project( at ) : { x, y, behind }

The canvas point of a world point, from whichever renderer the scene names: render3d's project through its camera, or render2d's through its world and camera.

pin( c, at )

Puts the shown thing c at the canvas point of the world point at, measured after every actor has ticked, so a nameplate is placed by the camera the frame is drawn with and not by the one before it. A thing pinned where the camera draws nothing is not shown. Call it every frame.

Menus and input

open( name ) / dismiss( name ) / opened( name ) : boolean

Open a panel, close it, and ask whether it is open. opened returns a boolean.

modal( ) : string | undefined

The name of the modal that has the input, or undefined. player asks it each frame.

hit( x, y ) : PIXI.Container | null

The thing under a canvas point that takes the pointer, or null. While a modal is up, its backdrop is the answer wherever nothing on it is. x and y are canvas pixels from the top left: a click's offsetX and offsetY on the game's canvas, divided by the renderer's scale when render2d's fit scales the canvas. player asks it before turning a click or mouse button into a game message.

took( e ) : boolean

Whether the UI took this key event, so it is not a game key. The UI hears every key first. player asks before it treats a key as a game key.

keyDown( key ) : boolean / keyUp( key )

A gamepad's key going down, as player hands it on when it plays by actions, and the same key coming up. keyDown returns whether the UI took it, so it is not a game key.

focused( c ) : boolean

Whether c has the focus.

Surfaces

surface( name ) : { canvas, box } | undefined

Asked in a frame, draws that panel on a surface for the frame instead of over the game, so a 3D renderer can read the canvas as a picture, such as a screen in a cockpit. The panel needs a size and must not be a modal. It leaves the stage, so it is neither drawn on the UI's canvas nor hit. At the end of the frame it is drawn on the surfaces' canvas, one canvas every surface shares, with one upload a frame for every screen it feeds. The surfaces asked in a frame lie side by side along the canvas's top, in the order world.ui lists them, each its size times its scale across at the UI's pixel ratio, a pixel apart, on the panel's screen colour. box is [x, y, width, height], where the panel lies on the canvas in its pixels as the frame ends. It is the same object every frame, and undefined where there is no page to draw on. A frame that does not ask for it puts the panel back in its place by its anchor. Everything on it is shown with show.

Pieces

Actors write plain PixiJS: Graphics, Text, Sprite, Container and PixiJS's own pointer events. These three are added.

button( o ) : PIXI.Container

A background and a label centred on it, which the pointer hits as one thing. It is drawn with focus while the UI has it focused and with fill otherwise. What it does is the actor's: on('pointertap', ...) hands the button back, so a button that does something is one expression.

bar( o ) : PIXI.Container & { set(k, fill) }

A track size [width, height] pixels across, with a frame edge pixels thick all round it in frame (black when left out; edge is 0 when left out). Its top left is the track's, so the frame lies outside it. track is the track's fill. set(k, fill) fills the part k of the track, 0 to 1, from its left, in fill, to a whole pixel.

iris( o ) : PIXI.Graphics & { set(x, y, r) }

A cover of a box size [width, height] pixels across in fill, black when left out. set(x, y, r) lets the circle of radius r pixels about the point (x, y) of the box show through, cut a row of pixels at a time, so its edge steps a whole pixel as the circle a SNES game closes on its hero does. An r of 0 covers the box, and one past its far corner from (x, y) covers none of it.

#Properties of the plugin

Also on plugins.ui.

PIXI

PixiJS. Draw with plugins.ui.PIXI rather than importing it.

stage : PIXI.Container

The root container of the UI's stage.

canvas : HTMLCanvasElement | undefined

The UI's canvas, undefined until the page has mounted one. A client with no page, such as a test or a bot, shows, destroys, places and hit-tests the same things and draws and listens for nothing. The canvas stays hidden until the first frame that has anything to draw.

#Used by

• cutscene
  Draws its bars, veil and line on the panels cutscene.top, cutscene.bottom, cutscene.veil and cutscene.line.
• chat
  Shows its panel and takes lines on it.

pancamera and party also use it.

#In the guide