simvx.core.ui.gamepad_overlay

GamepadOverlay: on-screen virtual gamepad for touch / mobile play.

Promoted from games/dungeon_explorer/scripts/virtual_controls_overlay.py. Renders a left-side analog stick, a primary action button (right-bottom), a secondary button (back / dodge), four ability buttons in an arc, and two optional rectangle menu buttons + a hotbar strip. Touch input is multi-touch aware (each finger tracks one element independently); desktop falls back to a single-pointer mouse path.

Inputs are emitted through :func:simvx.core.Input.inject_key so existing keyboard-driven game logic works unchanged: no signals to wire up.

Unlike the lower-level :class:VirtualJoystick / :class:VirtualButton widgets (which are signal-based Controls), GamepadOverlay is a plain object you instantiate, configure, then drive from on_process / on_draw callbacks of your root node. Multi-touch tracking, joystick → WASD nav, and context-sensitive button labels all live here.

Example::

from simvx.core.ui import GamepadOverlay
self.overlay = GamepadOverlay()
self.overlay.configure(screen_w=1280, screen_h=720, mobile=True)
# in on_process:
self.overlay.on_process(dt)
# in on_draw:
self.overlay.on_draw(renderer)

Module Contents

Classes

GamepadOverlay

On-screen virtual gamepad: joystick + 6 buttons + optional hotbar.

Data

__all__

API

simvx.core.ui.gamepad_overlay.__all__

[‘GamepadOverlay’]

class simvx.core.ui.gamepad_overlay.GamepadOverlay(*, ability_keys: Iterable[simvx.core.input.Key] = (Key.KEY_1, Key.KEY_2, Key.KEY_3, Key.KEY_4), primary_keys: Iterable[simvx.core.input.Key] = (Key.SPACE, Key.E), secondary_key: simvx.core.input.Key = Key.LEFT_SHIFT, menu_key: simvx.core.input.Key = Key.ESCAPE, inventory_key: simvx.core.input.Key = Key.I, hotbar_keys: Iterable[simvx.core.input.Key] = (Key.KEY_1, Key.KEY_2, Key.KEY_3, Key.KEY_4), primary_label: str = 'ATK', secondary_label: str = 'DODGE', menu_label: str = 'MENU', inventory_label: str = 'ITEMS')[source]

On-screen virtual gamepad: joystick + 6 buttons + optional hotbar.

Initialization

configure(screen_w: int, screen_h: int, mobile: bool = False) → None[source]

Recompute positions for the given viewport.

Dropping any in-flight touch / press state, so a viewport rotation doesn’t leave a button or joystick stuck to a stale coordinate.

property visible: bool[source]
set_context(*, has_shield: bool = False, near_interactable: bool = False, in_menu: bool = False) → None[source]

Update context-sensitive labels (interact prompt, block vs dodge, menu mode).

property joystick_value: simvx.core.math.types.Vec2[source]

Normalised joystick output (-1..1, -1..1). Drives player input.

on_process(dt: float) → None[source]
on_draw(renderer) → None[source]