pixterm 0.1.1

A pygame-powered ANSI terminal emulator framework for building text-based games and apps.

PixTerm

A pygame-powered ANSI terminal emulator framework for building text-based games and TUI applications.

PixTerm renders a fixed-size character grid (120 × 40 by default) using bitmap BDF fonts and a fully parsed ANSI escape code pipeline — giving you the look of a classic terminal with the full power of Python and pygame underneath.

---

Features

• ANSI escape code rendering — foreground/background colours (16-colour palette), bold, cursor movement
• Bitmap BDF fonts — bundled Terminus fonts in sizes 12–24 px (normal, bold, variable-width variants)
• Screen manager — stack-based screen system with on_entry / render / update / handle_event / on_exit lifecycle
• Theme system — swap colour palettes at runtime; ships with basic_black, basic_white, and more
• Preferences — persistent JSON preferences stored in ~/.pixterm/preferences.json
• Hot-reloader — optional watchdog-based module reloader for rapid development

---

Installation

pip install pixterm

Requires Python 3.10+ and pygame 2.6+.

---

Quick Start

import pygame
from pixterm import Game, Screen, Preferences

class HelloScreen(Screen):
    def render(self):
        self._cli.write("\x1b[2;2H\x1b[93mHello, PixTerm!\x1b[0m")

    def update(self, dt: float):
        pass

    def handle_event(self, event: pygame.event.Event):
        if event.type == pygame.KEYDOWN and event.key == pygame.K_ESCAPE:
            self._game.quit()

game = Game(title="Hello World", target_fps=60)

prefs = Preferences.load()
prefs.apply_theme(game.cli)           # apply saved colour theme

game.screen_manager.register("hello", HelloScreen())
game.screen_manager.switch_to("hello")
game.run()

---

Core Concepts

Game

The main entry point. Creates the pygame window, owns the CLI, ScreenManager, and main loop.

game = Game(title="My Game", target_fps=60)
game.run()

CLI

The character-grid terminal emulator. Write ANSI-escaped strings to any position:

# Absolute cursor position then coloured text
cli.write("\x1b[5;10H\x1b[32mGreen text\x1b[0m")

# Helper — write at explicit (col, row) without escape sequences
cli.write_at("Hello", col=10, row=5, fg=2, bold=False)

The grid is 120 columns × 40 rows (STANDARD_WIDTH × STANDARD_HEIGHT).

Screen

Base class for all application views. Override the lifecycle methods:

from pixterm import Screen

class GameScreen(Screen):
    def on_entry(self):
        """Called once when this screen becomes active."""

    def render(self):
        """Called every frame — redraw everything here."""

    def update(self, dt: float):
        """Called every frame with elapsed seconds since last frame."""

    def handle_event(self, event):
        """Receives every pygame event while this screen is active."""

    def on_exit(self):
        """Called once when leaving this screen."""

BDFFont

Bitmap font loader. Terminus fonts (12–24 px) are bundled and loaded automatically:

from pixterm import BDFFont

font = BDFFont.get_font(16)          # 16 px normal weight
font_bold = BDFFont.get_font(16, bold=True)

Preferences

Singleton for persistent user settings (theme, etc.):

from pixterm import Preferences

prefs = Preferences.load()           # load from ~/.pixterm/preferences.json
prefs.theme_name = "basic_white"
prefs.save()
prefs.apply_theme(game.cli)

Themes

Built-in colour themes:

Name	Description
basic_black	Default dark terminal (standard ANSI colours)
basic_white	Light background variant

from pixterm import get_theme_names, get_theme

print(get_theme_names())             # ['basic_black', 'basic_white', ...]
theme = get_theme("basic_black")

---

Font Sizes

Bundled Terminus BDF fonts:

Size (px)	Normal	Bold	Variable
12	✓	✓	—
14	✓	✓	✓
16	✓	✓	✓
18	✓	✓	—
20	✓	✓	—
22	✓	✓	—
24	✓	✓	—

---

Project Layout

pixterm/
├── __init__.py        # Public API
├── cli.py             # ANSI terminal emulator + TerminalCell grid
├── font_renderer.py   # BDF font loader and glyph renderer
├── game.py            # Main game loop + pygame initialisation
├── screen.py          # Screen base class
├── screen_manager.py  # Screen registration + switching
├── preferences.py     # Persistent user preferences (singleton)
├── themes.py          # Colour theme definitions
├── hotreloader.py     # Optional watchdog-based hot-reloader
└── fonts/             # Bundled Terminus BDF bitmap fonts
    └── ter-u*.bdf

---

Licence

MIT — see LICENSE.

Author's Notes on Artificial Intelligence

This project was developed with the assistance of AI. The AI was used to generate code snippets, suggest improvements, and help with debugging. The AI's contributions were reviewed and edited by the author to ensure they fit the project's requirements and coding style.