ui

UI package: High-level UI components, HUD, and menu systems.

This package contains UI widgets and rendering helpers used by the engine’s menus, HUD overlay, and in-world item UI. Submodules provide discrete components such as components, hud, menus, and meshes used by the application to compose screen-space interfaces.

Public objects are re-exported here for easier autodoc consumption.

components

Reusable UI component classes for building complex, hierarchical game menus.

This module provides a node-based scene graph system (UINode, VBox) and a suite of interactive widgets (Button, Slider, TextInput, Toggle). It also includes a lazy-loading resource manager (get_shared_resource) to efficiently share and reuse heavy objects like fonts and meshes, preventing VRAM bloat.

ui.components.get_shared_resource(app, resource_type, **kwargs)

Lazily loads and shares UI meshes, fonts, and textures to prevent VRAM and CPU bloat.

This function acts as a singleton factory, ensuring that expensive resources like text renderers or button mask textures are only created once and then reused across all UI components that request them.

Parameters:

• app (Any)

• resource_type (str)

• kwargs (Any)

Return type:

Any

class ui.components.UINode(size=(0, 0))

Bases: object

Base class for all UI elements in the hierarchical layout system.

This class forms the foundation of the scene graph, allowing UI elements to be nested within each other. It handles the recursive calculation of global positions and the propagation of update, event, and render calls.

Parameters:

size (Tuple[float, float]) – The normalized width and height of the node.

add_child(child)

Adds a child node to this node’s list of children and sets its parent.

Parameters:

child (UINode)

Return type:

UINode

get_global_pos()

Recursively computes absolute screen position by climbing the scene graph.

Return type:

Tuple[float, float]

update_layout()

Recursively calls update_layout on all children.

Return type:

None

update(mouse_pos=None)

Recursively calls update on all children, passing down the mouse position.

Parameters:

mouse_pos (Tuple[int, int] | None)

Return type:

None

handle_event(event)

Recursively calls handle_event on all children, passing down the Pygame event.

Parameters:

event (Any)

Return type:

None

render(offset=(0, 0), alpha=1.0)

Recursively calls render on all children, passing down animation offsets and alpha.

Parameters:

• offset (Tuple[float, float])

• alpha (float)

Return type:

None

class ui.components.VBox(position=(0, 0), spacing=0.05)

Bases: UINode

Vertical stacking container that automatically arranges its children.

This layout group simplifies menu creation by positioning child nodes one after another in a vertical column, with a configurable spacing between them.

Parameters:

• position (Tuple[float, float]) – The normalized screen position of the container’s origin.

• spacing (float) – The normalized vertical gap to place between each child element.

update_layout()

Layout children vertically and update this container’s size.

Arranges children with the configured spacing and computes the total height for correct nesting in parent containers.

Return type:

None

class ui.components.Button(app, text, position, size, action=None, border_radius=12, elevation=5)

Bases: UINode

Represents a clickable UI button with text, hover effects, and an assigned action.

Features a pseudo-3D elevation effect that visually depresses when clicked. It lazily loads shared resources to minimize VRAM usage.

Parameters:

• app (Any) – The main application instance.

• text (str) – The text label to display on the button.

• position (Tuple[float, float]) – The local normalized position.

• size (Tuple[float, float]) – The normalized width and height.

• action (Callable[[], None]) – The function to call when the button is clicked.

• border_radius (int) – The pixel radius for the rounded corners.

• elevation (int) – The pixel height of the 3D elevation effect.

check_hover(mouse_pos)

Check whether the mouse cursor is inside the button’s bounding box.

Parameters:

mouse_pos (Tuple[int, int]) – Mouse position in pixel coordinates as (x, y).

Returns:

True if the mouse is hovering the button, False otherwise.

Return type:

bool

update(mouse_pos=None)

Update visual/interaction state for this button.

Parameters:

mouse_pos (Tuple[int, int] | None) – Optional mouse position in pixels; when None the current system mouse position is used.

Return type:

None

handle_event(event)

Handle Pygame mouse button events and trigger the button’s action.

Parameters:

event (Any) – Pygame event object to handle (mouse down/up).

Return type:

None

render(offset=(0, 0), alpha=1.0)

Render the button visuals including elevation, mask, and text.

Parameters:

• offset (Tuple[float, float]) – Render offset applied to the button position.

• alpha (float) – Opacity multiplier for rendering.

Return type:

None

class ui.components.WorldButton(app, save_name, display_name, seed, game_mode, creation_date, last_played, position, size, action=None, border_radius=12, elevation=5)

Bases: UINode

A specialized button used in the World Selection menu to display rich information about a saved game world, including its thumbnail, seed, and playtime data.

Parameters:

• app (Any) – The main application instance.

• save_name (str) – The raw filename of the save.

• display_name (str) – The user-friendly world name.

• seed (int) – The world’s procedural generation seed.

• game_mode (int) – The game mode (Survival/Creative).

• creation_date (str) – ISO format creation timestamp.

• last_played (str) – ISO format last played timestamp.

• position (Tuple[float, float]) – The local normalized position.

• size (Tuple[float, float]) – The normalized width and height.

• action (Callable[[], None]) – The function to call when clicked.

• border_radius (int) – The pixel radius for the rounded corners.

• elevation (int) – The pixel height of the 3D elevation effect.

check_hover(mouse_pos)

Check whether the mouse cursor is inside the world button’s bounding box.

Parameters:

mouse_pos (Tuple[int, int]) – Mouse position in pixel coordinates as (x, y).

Returns:

True if the mouse is hovering this world button, False otherwise.

Return type:

bool

update(mouse_pos=None)

Update hover state for the world button.

Parameters:

mouse_pos (Tuple[int, int] | None) – Optional mouse position; current mouse position is used when None.

Return type:

None

handle_event(event)

Handle mouse events for clicking/pressing the world button.

Parameters:

event (Any) – Pygame event instance.

Return type:

None

render(offset=(0, 0), alpha=1.0)

Render the world button including thumbnail, title and details.

Parameters:

• offset (Tuple[float, float]) – Render offset applied to the button.

• alpha (float) – Opacity multiplier.

Return type:

None

class ui.components.TextInput(app, position, size, label='')

Bases: UINode

Provides a simple interactive text entry field for the UI.

Captures keyboard input, renders a blinking cursor when active, and displays a placeholder label when empty.

Parameters:

• app (Any) – The main application instance.

• position (Tuple[float, float]) – The local normalized position.

• size (Tuple[float, float]) – The normalized width and height.

• label (str) – The placeholder text to show when the input is empty.

handle_event(event)

Handle mouse and keyboard events for the text input control.

Parameters:

event (Any) – Pygame event instance to process.

Return type:

None

render(offset=(0, 0), alpha=1.0)

Render the input box, current text and blinking cursor.

Parameters:

• offset (Tuple[float, float]) – Render offset applied to the control position.

• alpha (float) – Opacity multiplier for rendering.

Return type:

None

class ui.components.Slider(app, text, position, size, min_val, max_val, config_key, action=None, is_int=False)

Bases: UINode

An interactive UI slider component used to adjust numerical settings between a minimum and maximum value.

Parameters:

• app (Any) – The main application instance.

• text (str) – The text label to display next to the slider.

• position (Tuple[float, float]) – The local normalized position.

• size (Tuple[float, float]) – The normalized width and height.

• min_val (float) – The minimum value of the slider.

• max_val (float) – The maximum value of the slider.

• config_key (str) – The key in app.config this slider controls.

• action (Optional[Callable[[Any], None]]) – An optional callback to run on value change.

• is_int (bool) – If True, the slider value will be rounded to the nearest integer.

update(mouse_pos=None)

Update the slider’s hover/drag state and apply value changes.

Parameters:

mouse_pos (Tuple[int, int] | None) – Optional mouse position in pixels; current mouse position used when None.

Return type:

None

handle_event(event)

Handle mouse events to begin dragging the slider.

Parameters:

event (Any) – Pygame event object.

Return type:

None

render(offset=(0, 0), alpha=1.0)

Render the slider track, fill and value text.

Parameters:

• offset (Tuple[float, float]) – Render offset applied to the slider position.

• alpha (float) – Opacity multiplier for rendering.

Return type:

None

class ui.components.Toggle(app, text, position, size, config_key, action=None)

Bases: UINode

A binary toggle switch component for the UI (e.g., for On/Off settings).

Parameters:

• app (Any) – The main application instance.

• text (str) – The text label to display next to the toggle.

• position (Tuple[float, float]) – The local normalized position.

• size (Tuple[float, float]) – The normalized width and height of the switch track.

• config_key (str) – The key in app.config this toggle controls.

• action (Optional[Callable[[bool], None]]) – An optional callback to run on value change.

update(mouse_pos=None)

Update hover state for the toggle control.

Parameters:

mouse_pos (Tuple[int, int] | None) – Optional mouse position in pixels; current mouse position used when None.

Return type:

None

handle_event(event)

Handle mouse clicks to flip the toggle and persist to config.

Parameters:

event (Any) – Pygame event object.

Return type:

None

render(offset=(0, 0), alpha=1.0)

Render the toggle control including track and thumb.

Parameters:

• offset (Tuple[float, float]) – Render offset applied to the toggle position.

• alpha (float) – Opacity multiplier for rendering.

Return type:

None

hud

Heads-Up Display (HUD) elements and dynamic overlays for the game.

This module constructs the in-game overlay, rendering the crosshair, the interactive drag-and-drop inventory, the hotbar with survival statistics, the 3D view-bobbing held item, and the F3 debug screen.

class ui.hud.Crosshair(app)

Bases: object

Renders a simple fixed crosshair at the center of the screen.

Parameters:

app (Any) – The main application context.

render()

Issues the draw call to render the crosshair mesh.

Return type:

None

class ui.hud.Hotbar(app)

Bases: object

Renders the bottom-screen hotbar, including the transparent slot backgrounds, active selection frame, 3D block/item icons, stack counts, and survival status bars.

Parameters:

app (Any) – The main application context.

render()

Dynamically draws the hotbar slots, items, counts, and survival bars.

Return type:

None

class ui.hud.HeldBlock(app)

Bases: object

Renders the 3D model of the currently equipped item or block in the player’s hand. Includes procedural view bobbing and swinging animations for mining/placing.

Parameters:

app (Any) – The main application context.

render()

Applies transformation matrices to simulate hand movement and renders the item.

Return type:

None

class ui.hud.InventoryUI(app)

Bases: object

Manages the full player inventory and crafting grid interface. Handles drag-and-drop item management, stack splitting, and crafting matrix evaluation.

Parameters:

app (Any) – The main application context.

update_crafting()

Evaluates the 2x2 crafting grid and updates the output slot if a valid recipe matches.

Return type:

None

get_slot_pos(i)

Calculates and caches the 2D screen coordinate for a specific inventory slot.

Parameters:

i (int)

Return type:

Tuple[float, float]

get_slot_at_mouse(mouse_pos)

Returns the ID of the inventory slot currently hovered by the mouse cursor.

Parameters:

mouse_pos (Tuple[int, int])

Return type:

int

get_closest_valid_slot(mouse_pos, drag_id, drag_count)

Finds the closest valid drop target slot during a drag-and-drop operation.

Parameters:

• mouse_pos (Tuple[int, int])

• drag_id (int)

• drag_count (int)

Return type:

int

handle_event(event)

Processes left/right mouse clicks for selecting, splitting, and merging item stacks.

Parameters:

event (Any)

Return type:

None

close()

Cleans up the inventory screen, ejecting active crafting items back into the world.

Return type:

None

render()

Issues draw calls for the entire inventory UI, background, and floating tooltip items.

Return type:

None

class ui.hud.DebugOverlay(app)

Bases: object

Displays an on-screen overlay with performance metrics, player coordinates, targeted block info, and current game mode (F3 menu).

Parameters:

app (Any) – The main application context.

render()

Compiles and renders the performance statistics and positional data overlay.

Return type:

None

menus

UI Menu systems: Main Menu, Pause Menu, and Options Menu.

This module manages the interactive overlays and state machines for the game’s user interfaces. It handles dynamic world saving/loading screens, configuration binding for settings, and smooth animated transitions between states.

class ui.menus.MainMenu(app)

Bases: object

Manages the Main Menu, World Selection, and World Creation screens.

Handles smooth state transitions, dynamic world list loading from the SQLite saves directory, and interaction events.

Parameters:

app (Any) – The main application context.

trigger_action(action, animation_direction=1)

Initiate an animated transition and schedule an action to run after it.

Parameters:

• action (Callable[[], None]) – A callable to execute once the ‘OUT’ transition completes.

• animation_direction (int) – Animation direction multiplier; used for transition easing.

Return type:

None

open_options()

Transition from the current menu to the Options Menu.

This sets the application’s menu state and initializes the options menu transition parameters.

Return type:

None

toggle_game_mode()

Toggle the game-mode selection used when creating a new world.

Updates the visible button text to reflect the current selection.

Return type:

None

set_state(new_state)

Switch the active menu state for the main menu and reset dynamic UI.

Parameters:

new_state (str) – One of ‘MAIN’, ‘SELECT_WORLD’, ‘CREATE_WORLD’ representing which menu view should be active.

Return type:

None

load_world_list()

Scan the local saves directory and populate the world selection UI.

This creates WorldButton instances for each found save database and corresponding delete buttons.

Return type:

None

delete_world(save_name)

Remove the saved world database file and its thumbnail (if present).

Parameters:

save_name (str) – Base filename of the save (without extension).

Return type:

None

create_world()

Create a new world using form inputs from the ‘Create World’ UI.

Reads name and seed fields, sanitizes the name, and ensures the save filename is unique before initializing the game session.

Return type:

None

update()

Advance menu animations, update scrolling state and dispatch updates to active UI components depending on the current menu state.

Return type:

None

handle_event(event)

Dispatch incoming Pygame events to the active menu UI elements.

Parameters:

event (Any) – Pygame event to process.

Return type:

None

render_bg()

Render the menu background image, scaled to maintain aspect ratio.

This will skip rendering if no background texture is available.

Return type:

None

render()

Render the active menu layout including title, background, and child UI nodes, applying transition offsets and alpha blending.

Return type:

None

class ui.menus.PauseMenu(app)

Bases: object

Provides the in-game pause screen overlay.

Allows the player to resume the game, open options, or quit back to the Main Menu.

Parameters:

app (Any) – The main application context.

trigger_action(action, animation_direction=1)

Triggers an out-transition before calling the specified action.

Parameters:

• action (Callable[[], None])

• animation_direction (int)

Return type:

None

open_options()

Transitions to the Options Menu.

Return type:

None

resume_game()

Hides the pause menu and re-captures the mouse for gameplay.

Return type:

None

quit_to_menu()

Unloads the game world and returns to the Main Menu.

Return type:

None

update()

Processes animations and propagates update events to children.

Return type:

None

handle_event(event)

Handle incoming Pygame events while the pause menu is active.

Parameters:

event (Any) – Pygame event to process.

Return type:

None

render()

Renders the dimming background and the menu elements with animation easing.

Return type:

None

class ui.menus.OptionsMenu(app)

Bases: object

Manages the game settings screen.

Provides sliders and toggles for FOV, Mouse Sensitivity, Volume, Render Distance, and Visual Tints. Handles serializing these settings to config.json.

Parameters:

app (Any) – The main application context.

trigger_action(action, animation_direction=1)

Initiates an animated transition out before running the requested action.

Parameters:

• action (Callable[[], None])

• animation_direction (int)

Return type:

None

update_fov(val)

Applies the field-of-view setting instantly to the active player.

Parameters:

val (float)

Return type:

None

update_music_volume(val)

Adjusts the global Pygame mixer music volume.

Parameters:

val (float)

Return type:

None

update_sfx_volume(val)

Delegates sound effect volume changes to the central Sounds manager.

Parameters:

val (float)

Return type:

None

go_back()

Returns to the menu that originally opened this options screen.

Return type:

None

update()

Updates animations and cascades logic down to layout components.

Return type:

None

handle_event(event)

Handle incoming Pygame events while the options menu is active.

Parameters:

event (Any) – Pygame event to process.

Return type:

None

render()

Draws the options layout UI nodes alongside their animated transitions.

Return type:

None

meshes

ModernGL definitions for 2D User Interface element geometries.

This module implements the underlying mathematical layouts (vertices and UV coordinates) for generating screen-space flat meshes. It provides the geometry structures for rendering the crosshair, the 2D scaled block inventory icons, text fonts, and solid-color backgrounds that compose the Pyrite game overlay.

class ui.meshes.CrosshairMesh(app)

Bases: BaseMesh

Generates the geometry for the on-screen crosshair.

Draws a simple ‘+’ sign directly in the center of the player’s view, utilizing aspect-ratio scaling to remain perfectly proportioned.

Parameters:

app (Any) – The main application context containing shaders and window properties.

get_vertex_data()

Calculates the vertex coordinates and color data needed to form the horizontal and vertical lines of the crosshair, scaling it properly to match the window’s aspect ratio.

Return type:

ndarray[tuple[Any, …], dtype[float32]]

class ui.meshes.BlockIconMesh(app)

Bases: BaseMesh

Handles the rendering geometry for 2D flat representations of 3D blocks.

Used extensively in the Hotbar and Inventory UI slots. Produces a basic texture-mapped quad that the shader transforms dynamically into slots.

Parameters:

app (Any) – The main application context.

get_vertex_data()

Returns the vertices and texture coordinates for a standard full-screen quad, which is later scaled and positioned by the shader based on uniform offsets.

Return type:

ndarray[tuple[Any, …], dtype[float32]]

class ui.meshes.UIColorMesh(app)

Bases: BaseMesh

Provides the geometry for rendering solid-color geometric elements in the UI.

Used for rendering non-textured components such as backgrounds, frames, selection highlights, and dimming overlays using flat-color shaders.

Parameters:

app (Any) – The main application context.

get_vertex_data()

Returns the raw vertex positions for a 2D quad without texture coordinates, as the shape relies solely on color uniforms.

Return type:

ndarray[tuple[Any, …], dtype[float32]]

class ui.meshes.UITextMesh(app)

Bases: BaseMesh

Generates the geometry required to display text strings on the screen.

Acts as a surface to map dynamically generated text textures onto, utilizing alpha-blended shaders to properly draw fonts over the background elements.

Parameters:

app (Any) – The main application context.

get_vertex_data()

Returns the standard set of vertices and UV coordinates mapping a full texture onto a simple 2D rectangular quad.

Return type:

ndarray[tuple[Any, …], dtype[float32]]

text

Text rendering and caching for OpenGL textures.

This module provides the TextRenderer class, which converts strings into Pygame surfaces with drop shadows, and then uploads them to the GPU as ModernGL textures. It supports both caching for static text and immediate generation for dynamic, single-frame text.

class ui.text.TextRenderer(app)

Bases: object

Handles the rendering of text strings into OpenGL textures.

Provides methods for caching static text and generating single-frame dynamic text.

Parameters:

app (Any) – The main application context.

get_texture(text)

Generates and returns an OpenGL texture for the specified text string. Caches the generated texture so subsequent requests for the same text are returned instantly without re-rendering.

Parameters:

text (str)

Return type:

Any

get_dynamic_texture(text)

Generates and returns an OpenGL texture for text that changes frequently. Does not cache the texture or build mipmaps, saving memory and processing time for single-frame usage.

Parameters:

text (str)

Return type:

Any