WGLT v2: From Terminal to Toolkit

WGLT is evolving from a WebGL Terminal library focused on ASCII games into a more comprehensive WebGL Toolkit that supports both traditional ASCII roguelikes and modern tile-based games. Version 2 maintains backwards compatibility while significantly expanding the library's capabilities.

Core Architecture Changes

New Application Model

• Introduced a new BaseApp abstract class that serves as the foundation
• Two concrete implementations:
  • Terminal (extends BaseApp): For ASCII/text-mode games
  • GraphicsApp (extends BaseApp): For tile-based/graphical games
• Users typically choose one based on their needs, with example demos clearly separated into "Graphics" and "Text Mode" categories

Terminal Class Changes

The Terminal class remains mostly backwards compatible with v1, with a few important architectural changes:

1. Composition Over Inheritance

   • Previously: Terminal extended Console
   • Now: Terminal contains a Console instance
   • Common console operations (fillRect, drawChar, drawString) are delegated
   • Some operations require direct terminal.console access

2. Input Handling

   • Removed delegate methods for mouse and keyboard
   • Now use direct access:
     • terminal.keyboard.isKeyDown()
     • terminal.mouse.getX()

3. TileMap Separation

   • Moved TileMap functionality out of Console class
   • New dedicated classes:
     • TileMap
     • TileMapLayer
     • TileMapCell
   • Updated examples demonstrate TileMap to Console translation

New Graphics Features

GraphicsApp Core Features

1. Sprite Management

   • Single image atlas convention (recommended sizes: 1024x1024, 2048x2048)
   • Support for 4096x4096 atlases (99.96% compatibility)
   • Fast WebGL2 instanced rendering for drawImage operations

2. Font System

   • New Font class for character positioning and dimensions
   • Helper utilities:
     • Font.createMonospaced()
     • Font.createProportional()
     • Built-in pixel art fonts (e.g., "04B03")

3. Sprite System

   • New Sprite class with:
     • Source rect management
     • Animation cycles
     • Animation delay control
   • Color override support for effects (text coloring, sprite flashing)

4. TileMap Rendering

   • Specialized TileMapRenderer
   • Optimized shader for single-pass layer rendering
   • Highly efficient for large tilemaps

Revamped GUI System

The GUI system has been completely redesigned for both text and graphics modes, offering more power and flexibility.

Key Features

1. Optional Integration

   • GUI features only activate when explicitly used
   • Requires GUI class instance
   • Explicit GUI.handleInput and GUI.draw calls in render loop

2. Component Architecture

   • Base Component class
   • Container class for parent-child relationships
   • Built-in drag-and-drop support
   • Optimized for common game patterns (action bars, inventory management)

3. Rendering System

   • Flexible Renderer interface
   • Register renderers for component classes
   • Optional built-in renderer implementations
   • Support for component-level render() methods

Migration Notes

• The GUI system changes are the most potentially disruptive
• Most existing applications didn't heavily use the previous GUI features
• Examples have been updated to demonstrate new patterns
• The last pure-terminal version will be tagged for reference

Development Environment Changes

Modern JavaScript Build Support

• Removed pre-bundled/pre-minified JavaScript output
• Distributing as individual .js and .d.ts files
• Designed for modern bundlers (Webpack, Rollup, Vite)
• Reflects current JavaScript/TypeScript development practices

New Serialization Framework

• Built-in support for complex object graphs
• Handles inheritance, composition, and cyclical references
• Uses TypeScript decorators (@serializable)
• Ideal for roguelike game state management
• Detailed documentation and examples available separately

Migration Example

Here's a simple "Hello World" comparison between v1 and v2:

// v1
const terminal = new Terminal(document.querySelector('canvas'), 80, 25);
terminal.drawString(0, 0, 'Hello World');

// v2
const terminal = new Terminal('canvas', 80, 25);
terminal.drawString(0, 0, 'Hello World');

More detailed migration examples are available in the migration guide.

Design Decisions

Terminal/Console Separation

The original design attempted to simplify usage by combining Terminal and Console functionality through inheritance. In practice, this created unclear boundaries and magical behavior. The v2 separation provides:

• Clearer responsibility boundaries
• More explicit API surface
• Better composability
• Reduced coupling between rendering and state management

Future Direction

WGLT v2 represents a significant evolution while maintaining the library's core identity. The expansion to support both ASCII and graphical games opens new possibilities while keeping the library's focus on performance and flexibility.