Migrating to WGLT v2

WGLT v2 is a breaking release. It retains the text-mode renderer while reorganizing the library around a shared application core, a new graphics renderer, and a redesigned GUI. Existing applications should expect source changes when upgrading from a pre-v2 release.

This guide focuses on the most common changes from 0.6.4, the last stable version published before v2. It is not an exhaustive list of every changed or removed symbol. Compile your application against v2 and use the current examples as the reference for APIs not covered here.

Creating an application

Terminal.init() is the simplest way to create a text-mode application in v2. It creates and centers its own canvas. The constructor remains available when the application supplies a canvas or CSS selector. 

import { Terminal } from 'wglt';

// 0.6.4
const canvas = document.querySelector('canvas') as HTMLCanvasElement;
const term = new Terminal(canvas, 80, 45);

// v2: create and center a canvas automatically.
const term = Terminal.init(80, 45);

// v2: or use an existing canvas.
const termWithCanvas = new Terminal('#game', 80, 45);

Text-mode applications use Terminal. Sprite-based applications useGraphicsApp, which accepts dimensions in pixels and renders from an image atlas.

import { FONT_04B03, GraphicsApp } from 'wglt';

const app = GraphicsApp.init(640, 360, {
  imageUrl: './graphics.png',
  defaultFont: FONT_04B03,
});

Terminal options

The v2 terminal options are:

The old font, crt, and maxFps options are not part of the v2 API. Replace Point with Vec2 (or use the structural PointLike type where a class instance is unnecessary).

Console drawing

In 0.6.4, Terminal extended Console. In v2 it owns a Console containing the text cells instead. Common operations such as clear(), fillRect(), drawChar(), drawString(), and drawConsole() are available directly on the terminal. More specialized cell and box operations are available through terminal.console. 

term.drawString(2, 2, 'Hello');
term.console.drawDoubleBox(0, 0, 20, 5);

Input handling

The old terminal.keys property is now terminal.keyboard. Keyboard helpers that were methods on Terminal also live there. The key constant object was renamed from Keys to Key. Mouse coordinates and button state remain available through terminal.mouse. 

term.update = () => {
  const movement = term.keyboard.getMovementKey();
  if (movement) {
    player.x += movement.x;
    player.y += movement.y;
  }

  if (term.mouse.buttons.get(0).isClicked()) {
    console.log(term.mouse.x, term.mouse.y);
  }
};

GUI changes

The GUI system was redesigned and should not be considered source-compatible with the pre-v2 GUI. Create a GUI for the application, install the matching theme, and explicitly process input and draw it from the update callback. 

import { DefaultTerminalTheme, GUI } from 'wglt';

const gui = new GUI(term);
gui.setTheme(new DefaultTerminalTheme());

term.update = () => {
  gui.handleInput();
  gui.draw();
};

The 0.6.4 GUI was a stack of dialogs managed by a single dialog renderer. V2 replaces it with a component tree, renderer maps, themes, layout, tooltips, and drag-and-drop behavior. Port GUI code using the current text-mode and graphics GUI examples rather than assuming old dialogs can be reused unchanged.

New graphics and tilemap APIs

V2 adds the sprite-based GraphicsApp, fonts, sprites, draw batching, and GUI renderers for graphical games. It also adds TileMap, TileMapLayer, TileMapCell, and TileMapRenderer. These APIs did not exist in the published 0.6.4 package.

Serialization

The @serializable decorator has been replaced by explicit registration. A static initialization block keeps registration next to the class declaration while using standard ECMAScript syntax. 

import { registerSerializable } from 'wglt';

class Actor {
  static {
    registerSerializable('my-game.Actor', Actor);
  }
}

serialize() and deserialize() preserve object identity and circular references for registered class instances. Plain objects and arrays are serialized by value, so shared references are duplicated and circular references involving them are not supported. Register a class for objects that require identity or circular-reference support. V2 also supports typed arrays and DataView values.

Serialized bundles include a $wglt format version. Deserialization rejects missing or unsupported versions instead of guessing how to interpret the data. The exact internal marker shapes { $ref: number } and { $type: supportedArrayView, $data: string } are reserved. Plain objects may use those property names when they also contain other properties. Registered class instances must not define their own $type property because that property stores the registered class ID.

Packaging and runtime requirements

Recommended upgrade process

  1. Upgrade wglt and run the TypeScript compiler.
  2. Replace Point, old input delegates, and changed terminal options.
  3. Port GUI code against the current examples.
  4. Replace decorator-based serialization registration.
  5. Build and exercise the application in a WebGL2-capable browser.