Quickstart

This page gets a minimal Tessella window on screen. See Installation first if you haven’t set up your environment yet.

The game loop

Tessella doesn’t manage the pygame window or event loop for you: it’s a widget layer that sits inside a regular pygame application. Every Tessella app follows the same four steps, once per frame:

1. calculate_layout: (re)computes the widget tree’s sizing and positioning against the available screen area. Called once up front, and again whenever the window is resized.

2. process_event: forwards pygame events (clicks, key presses, …) to the widget tree so interactive widgets can react to them.

3. update: advances any time-based state (e.g. animations) using the frame’s delta time.

4. render: draws the widget tree onto a target surface.

Hello, Tessella

Here’s the smallest useful example: a window that centers a piece of text.

import pygame
from tessella import *

pygame.init()

display = pygame.display.set_mode((400, 300), pygame.RESIZABLE)
clock = pygame.time.Clock()

gui: Widget = Center(
    Text(
        "Hello, Tessella!",
        style=TextStyle(font_size=32, font_color="#eeeeee")
    )
)
gui.calculate_layout(display.get_rect())

running = True
while running:
    delta_time = clock.tick(60)

    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            running = False
        elif event.type == pygame.WINDOWRESIZED:
            gui.calculate_layout(display.get_rect())

        # consumed is True if the UI acted on this event (e.g. a button
        # click). Not used here since this example has no game logic of
        # its own, but you'd check it to decide whether an unconsumed
        # event should also be handled as gameplay input, e.g. a click
        # the UI ignored being treated as aiming or firing a weapon.
        consumed = gui.process_event(event)

    gui.update(delta_time)

    display.fill(Palette.BACKGROUND)
    gui.render(display)
    pygame.display.update()

pygame.quit()

Running this script opens a resizable 400x300 window with the text “Hello, Tessella!” centered on it:

A quick tour of what’s happening

• from tessella import * pulls in the whole public widget API: widgets (Center, Text, …), style classes (TextStyle, …) and helpers like ValueNotifier.

• Center positions its single child in the middle of the space available to it.

• Text renders a string using a TextStyle, which controls font size, color, font file and anti-aliasing.

• gui.calculate_layout(display.get_rect()) must be called before the first render (and again on WINDOWRESIZED) so every widget in the tree knows its size and position.

Next steps

Head over to Tutorial to build something interactive: buttons, state, and reactive updates. Or browse the API reference for the full list of available widgets and styles.