kadajett/ts-tui-game-skill
Overview
This skill helps you build beautiful, performant terminal user interfaces and games using TypeScript and blessed. It provides opinionated patterns, templates, and best practices focused on rendering, state management, input routing, layout composition, and lifecycle/cleanup. Follow these conventions to produce maintainable, testable, and responsive TUI apps that behave well across terminals.
How this skill works
The skill prescribes a project layout that separates UI, game logic, and engine concerns, along with recommended screen options for blessed. It enforces a render-scheduler pattern that centralizes calls to screen.render(), a single authoritative state with pure reducers, and an input router for context-aware key handling. Theme tokens, layout primitives (3-pane), modal patterns, and performance guards are included so you can implement UIs without rebuilding widgets or rendering from event handlers.
When to use it
- Starting a new TypeScript TUI app or terminal game that uses blessed
- Implementing a game loop, render scheduler, or frame-cap in a terminal
- Designing responsive terminal layouts (main viewport, sidebar, log)
- Adding keyboard-first input routing, modal dialogs, or focus handling
- Optimizing terminal rendering performance and reducing flicker
Best practices
- Use TypeScript strict mode and keep game core free of terminal side effects
- Never call screen.render() from event handlers; use a render scheduler
- Maintain one authoritative state and use pure reducers for updates
- Reuse widgets: update content/styles instead of rebuilding elements each frame
- Centralize colors and styles in a theme; choose one accent and one danger color
- Ensure clean shutdown: destroy screen, clear timers, and exit safely
Example use cases
- Turn-based roguelike with a fluid map viewport, right sidebar for inventory, and bottom log
- Real-time puzzle or arcade terminal game with a capped FPS render scheduler
- CLI dashboard that composes multiple panels and uses modals for settings or confirmations
- Interactive forms and list management with keyboard-first navigation and focus routing
- Prototyping terminal UIs where performance matters: avoid per-tick allocations and tag-heavy renders
FAQ
Calling screen.render() directly from handlers causes uncontrolled render frequency and can produce jank; a render scheduler batches requests and caps FPS for smooth updates.
How do I structure state and UI interactions?
Keep a single authoritative state in the game core, dispatch actions from UI code, and implement pure reducers so logic is testable and decoupled from blessed.
