John McCardle
98489a96fd
Three small bugs surfaced by the #314 docstring-accuracy verify pass: #317 automation.scroll() dropped the x of its position argument: scroll() resolved (x, y) but called injectMouseEvent(MouseWheelScrolled, clicks, y), passing the scroll amount as x. injectMouseEvent now takes the scroll delta as its own parameter and scroll() forwards the real x/y. #318 GridView.texture always returned None (a TODO stub). It now returns a Texture wrapper sharing the underlying shared_ptr<PyTexture>, mirroring Grid.texture. (mcrfpy.Grid and mcrfpy.GridView are the same type post-#252, so this fixes both names.) #319 Entity.visible_entities(radius=None) raised TypeError: radius was parsed with the 'i' format code, which rejects None. It now parses radius as an object and treats None / omitted / -1 as "use the grid's default fov_radius"; a non-int, non-None radius raises a clear TypeError. - regression tests for each under tests/regression/ - api_surface snapshot re-baselined (visible_entities signature; texture property now Texture | None) and docs/stubs regenerated; frozen docstring gate still 100% closes #317 closes #318 closes #319 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KnywUddaFRhkxo5kijxJnv
2060 lines
119 KiB
Python
2060 lines
119 KiB
Python
"""Type stubs for McRogueFace Python API.
|
|
|
|
Auto-generated by tools/generate_stubs_v2.py via runtime introspection.
|
|
Do not edit by hand -- regenerate after API changes:
|
|
|
|
make && ./tools/generate_all_docs.sh
|
|
"""
|
|
|
|
from enum import IntEnum
|
|
from typing import Any, Callable, Dict, List, Optional, Tuple, Union, overload
|
|
|
|
# --- Enums --------------------------------------------------------------
|
|
class Alignment(IntEnum):
|
|
"""Alignment enum for positioning UI elements relative to parent bounds."""
|
|
BOTTOM_CENTER: int
|
|
BOTTOM_LEFT: int
|
|
BOTTOM_RIGHT: int
|
|
CENTER: int
|
|
CENTER_LEFT: int
|
|
CENTER_RIGHT: int
|
|
TOP_CENTER: int
|
|
TOP_LEFT: int
|
|
TOP_RIGHT: int
|
|
|
|
class Behavior(IntEnum):
|
|
"""Enum representing entity behavior types for grid.step() turn management."""
|
|
CUSTOM: int
|
|
FLEE: int
|
|
IDLE: int
|
|
LOOP: int
|
|
NOISE4: int
|
|
NOISE8: int
|
|
PATH: int
|
|
PATROL: int
|
|
SEEK: int
|
|
SLEEP: int
|
|
WAYPOINT: int
|
|
|
|
class Easing(IntEnum):
|
|
"""Easing type."""
|
|
EASE_IN: int
|
|
EASE_IN_BACK: int
|
|
EASE_IN_BOUNCE: int
|
|
EASE_IN_CIRC: int
|
|
EASE_IN_CUBIC: int
|
|
EASE_IN_ELASTIC: int
|
|
EASE_IN_EXPO: int
|
|
EASE_IN_OUT: int
|
|
EASE_IN_OUT_BACK: int
|
|
EASE_IN_OUT_BOUNCE: int
|
|
EASE_IN_OUT_CIRC: int
|
|
EASE_IN_OUT_CUBIC: int
|
|
EASE_IN_OUT_ELASTIC: int
|
|
EASE_IN_OUT_EXPO: int
|
|
EASE_IN_OUT_QUAD: int
|
|
EASE_IN_OUT_QUART: int
|
|
EASE_IN_OUT_SINE: int
|
|
EASE_IN_QUAD: int
|
|
EASE_IN_QUART: int
|
|
EASE_IN_SINE: int
|
|
EASE_OUT: int
|
|
EASE_OUT_BACK: int
|
|
EASE_OUT_BOUNCE: int
|
|
EASE_OUT_CIRC: int
|
|
EASE_OUT_CUBIC: int
|
|
EASE_OUT_ELASTIC: int
|
|
EASE_OUT_EXPO: int
|
|
EASE_OUT_QUAD: int
|
|
EASE_OUT_QUART: int
|
|
EASE_OUT_SINE: int
|
|
LINEAR: int
|
|
PING_PONG: int
|
|
PING_PONG_EASE_IN: int
|
|
PING_PONG_EASE_IN_OUT: int
|
|
PING_PONG_EASE_OUT: int
|
|
PING_PONG_SMOOTH: int
|
|
|
|
class FOV(IntEnum):
|
|
"""FOV type."""
|
|
BASIC: int
|
|
DIAMOND: int
|
|
PERMISSIVE_0: int
|
|
PERMISSIVE_1: int
|
|
PERMISSIVE_2: int
|
|
PERMISSIVE_3: int
|
|
PERMISSIVE_4: int
|
|
PERMISSIVE_5: int
|
|
PERMISSIVE_6: int
|
|
PERMISSIVE_7: int
|
|
PERMISSIVE_8: int
|
|
RESTRICTIVE: int
|
|
SHADOW: int
|
|
SYMMETRIC_SHADOWCAST: int
|
|
|
|
class Heuristic(IntEnum):
|
|
"""Built-in A* heuristic function selector."""
|
|
CHEBYSHEV: int
|
|
DIAGONAL: int
|
|
EUCLIDEAN: int
|
|
MANHATTAN: int
|
|
ZERO: int
|
|
|
|
class InputState(IntEnum):
|
|
"""Enum representing input event states (pressed/released)."""
|
|
PRESSED: int
|
|
RELEASED: int
|
|
|
|
class Key(IntEnum):
|
|
"""Enum representing keyboard keys."""
|
|
A: int
|
|
ADD: int
|
|
APOSTROPHE: int
|
|
B: int
|
|
BACKSLASH: int
|
|
BACKSPACE: int
|
|
C: int
|
|
COMMA: int
|
|
D: int
|
|
DELETE: int
|
|
DIVIDE: int
|
|
DOWN: int
|
|
E: int
|
|
END: int
|
|
ENTER: int
|
|
EQUAL: int
|
|
ESCAPE: int
|
|
F: int
|
|
F1: int
|
|
F10: int
|
|
F11: int
|
|
F12: int
|
|
F13: int
|
|
F14: int
|
|
F15: int
|
|
F2: int
|
|
F3: int
|
|
F4: int
|
|
F5: int
|
|
F6: int
|
|
F7: int
|
|
F8: int
|
|
F9: int
|
|
G: int
|
|
GRAVE: int
|
|
H: int
|
|
HOME: int
|
|
HYPHEN: int
|
|
I: int
|
|
INSERT: int
|
|
J: int
|
|
K: int
|
|
L: int
|
|
LEFT: int
|
|
LEFT_ALT: int
|
|
LEFT_BRACKET: int
|
|
LEFT_CONTROL: int
|
|
LEFT_SHIFT: int
|
|
LEFT_SYSTEM: int
|
|
M: int
|
|
MENU: int
|
|
MULTIPLY: int
|
|
N: int
|
|
NUMPAD_0: int
|
|
NUMPAD_1: int
|
|
NUMPAD_2: int
|
|
NUMPAD_3: int
|
|
NUMPAD_4: int
|
|
NUMPAD_5: int
|
|
NUMPAD_6: int
|
|
NUMPAD_7: int
|
|
NUMPAD_8: int
|
|
NUMPAD_9: int
|
|
NUM_0: int
|
|
NUM_1: int
|
|
NUM_2: int
|
|
NUM_3: int
|
|
NUM_4: int
|
|
NUM_5: int
|
|
NUM_6: int
|
|
NUM_7: int
|
|
NUM_8: int
|
|
NUM_9: int
|
|
O: int
|
|
P: int
|
|
PAGE_DOWN: int
|
|
PAGE_UP: int
|
|
PAUSE: int
|
|
PERIOD: int
|
|
Q: int
|
|
R: int
|
|
RIGHT: int
|
|
RIGHT_ALT: int
|
|
RIGHT_BRACKET: int
|
|
RIGHT_CONTROL: int
|
|
RIGHT_SHIFT: int
|
|
RIGHT_SYSTEM: int
|
|
S: int
|
|
SEMICOLON: int
|
|
SLASH: int
|
|
SPACE: int
|
|
SUBTRACT: int
|
|
T: int
|
|
TAB: int
|
|
U: int
|
|
UNKNOWN: int
|
|
UP: int
|
|
V: int
|
|
W: int
|
|
X: int
|
|
Y: int
|
|
Z: int
|
|
|
|
class MouseButton(IntEnum):
|
|
"""Enum representing mouse buttons and scroll wheel."""
|
|
LEFT: int
|
|
MIDDLE: int
|
|
RIGHT: int
|
|
SCROLL_DOWN: int
|
|
SCROLL_UP: int
|
|
X1: int
|
|
X2: int
|
|
|
|
class Perspective(IntEnum):
|
|
"""Enum representing an entity's knowledge of a cell."""
|
|
DISCOVERED: int
|
|
UNKNOWN: int
|
|
VISIBLE: int
|
|
|
|
class Transition(IntEnum):
|
|
"""Transition type."""
|
|
FADE: int
|
|
NONE: int
|
|
SLIDE_DOWN: int
|
|
SLIDE_LEFT: int
|
|
SLIDE_RIGHT: int
|
|
SLIDE_UP: int
|
|
|
|
class Traversal(IntEnum):
|
|
"""Traversal type."""
|
|
INVERTED_LEVEL_ORDER: int
|
|
IN_ORDER: int
|
|
LEVEL_ORDER: int
|
|
POST_ORDER: int
|
|
PRE_ORDER: int
|
|
|
|
class Trigger(IntEnum):
|
|
"""Enum representing trigger types passed to entity step() callbacks."""
|
|
BLOCKED: int
|
|
DONE: int
|
|
TARGET: int
|
|
|
|
# --- Classes ------------------------------------------------------------
|
|
class AStarPath:
|
|
"""A computed A* path result, consumed step by step."""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
destination: Vector # Ending position of the path (Vector, read-only).
|
|
origin: Vector # Starting position of the path (Vector, read-only).
|
|
remaining: int # Number of steps remaining in the path (int, read-only).
|
|
def peek(self) -> Vector:
|
|
"""See the next step without consuming it."""
|
|
...
|
|
def walk(self) -> Vector:
|
|
"""Get and consume the next step in the path."""
|
|
...
|
|
|
|
class Arc:
|
|
"""An arc UI element for drawing curved line segments."""
|
|
def __init__(self, center=None, radius=0, start_angle=0, end_angle=90, color=None, thickness=1, **kwargs) -> None: ...
|
|
align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
|
|
bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
center: Vector # Center position of the arc (Vector).
|
|
color: Color # Arc fill color (Color).
|
|
end_angle: float # Ending angle in degrees (float).
|
|
global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
|
|
grid_pos: Vector # Position in grid tile coordinates (Vector, only when parent is Grid).
|
|
grid_size: Vector # Size in grid tile coordinates (Vector, only when parent is Grid).
|
|
horiz_margin: float # Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
|
|
hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
|
|
margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
|
|
name: str # Name for finding this element (str).
|
|
on_click: Any # Callable executed when arc is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
|
|
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
|
|
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
|
|
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
origin: Any # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
|
|
parent: Any # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
|
|
pos: Any # Position as a Vector (same as center).
|
|
radius: float # Arc radius in pixels (float).
|
|
rotate_with_camera: bool # Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of ...
|
|
rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property.
|
|
start_angle: float # Starting angle in degrees (float).
|
|
thickness: float # Line thickness in pixels (float).
|
|
vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
z_index: int # Z-order for rendering (int, lower values rendered first).
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this drawable's property."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Reapply alignment relative to parent, useful for responsive layouts."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
|
|
class AutoRuleSet:
|
|
"""AutoRuleSet - LDtk auto-tile rule set for pattern-based terrain rendering."""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
grid_size: int # Cell size in pixels (int, read-only).
|
|
group_count: int # Number of rule groups (int, read-only).
|
|
name: str # Rule set name / layer identifier (str, read-only).
|
|
rule_count: int # Total number of rules across all groups (int, read-only).
|
|
value_count: int # Number of IntGrid terrain values (int, read-only).
|
|
values: Any # List of IntGrid value dicts with value and name (read-only).
|
|
def apply(self, discrete_map: DiscreteMap, tile_layer: TileLayer, seed: int = 0) -> None:
|
|
"""Resolve auto-rules and write tile indices directly into a TileLayer."""
|
|
...
|
|
def resolve(self, discrete_map: DiscreteMap, seed: int = 0) -> list[int]:
|
|
"""Resolve IntGrid data to tile indices using LDtk auto-rules."""
|
|
...
|
|
def terrain_enum(self) -> IntEnum:
|
|
"""Generate a Python IntEnum from this rule set's IntGrid values."""
|
|
...
|
|
|
|
class BSP:
|
|
"""Binary Space Partitioning tree for procedural dungeon generation."""
|
|
def __init__(self, pos: tuple[int, int], size: tuple[int, int]) -> None: ...
|
|
adjacency: Any # Leaf adjacency graph. adjacency[i] returns tuple of neighbor indices. Read-only.
|
|
bounds: Any # Root node bounds as ((x, y), (w, h)). Read-only.
|
|
pos: Any # Top-left position (x, y). Read-only.
|
|
root: Any # Reference to the root BSPNode. Read-only.
|
|
size: Any # Dimensions (width, height). Read-only.
|
|
def clear(self) -> BSP:
|
|
"""Remove all children, keeping only the root node with original bounds. WARNING: Invalidates all existing BSPNode references from this tree."""
|
|
...
|
|
def find(self, pos: tuple[int, int] | list | Vector) -> BSPNode | None:
|
|
"""Find the smallest (deepest) node containing the position."""
|
|
...
|
|
def get_leaf(self, index: int) -> BSPNode:
|
|
"""Get a leaf node by its index (0 to len(bsp)-1). This is useful when working with adjacency data, which returns leaf indices."""
|
|
...
|
|
def leaves(self) -> Iterator[BSPNode]:
|
|
"""Iterate all leaf nodes (the actual rooms). Same as iterating the BSP directly."""
|
|
...
|
|
def split_once(self, horizontal: bool, position: int) -> BSP:
|
|
"""Split the root node once at the specified position. horizontal=True creates a horizontal divider, producing top/bottom rooms. horizontal=False creates a vert..."""
|
|
...
|
|
def split_recursive(self, depth: int, min_size: tuple[int, int], max_ratio: float = 1.5, seed: int | None = None) -> BSP:
|
|
"""Recursively split to the specified depth. WARNING: Invalidates all existing BSPNode references from this tree."""
|
|
...
|
|
def to_heightmap(self, size: tuple[int, int] | None = None, select: str = 'leaves', shrink: int = 0, value: float = 1.0) -> HeightMap:
|
|
"""Convert BSP node selection to a HeightMap."""
|
|
...
|
|
def traverse(self, order: Traversal = Traversal.LEVEL_ORDER) -> Iterator[BSPNode]:
|
|
"""Iterate all nodes in the specified order."""
|
|
...
|
|
|
|
class Billboard:
|
|
"""A camera-facing 3D sprite for trees, items, particles, etc."""
|
|
def __init__(self, texture=None, sprite_index=0, pos=(0,0,0), scale=1.0, facing='camera_y') -> None: ...
|
|
facing: str # Facing mode: 'camera', 'camera_y', or 'fixed' (str)
|
|
opacity: float # Opacity from 0.0 (transparent) to 1.0 (opaque) (float)
|
|
phi: float # Vertical tilt for 'fixed' mode in radians (float)
|
|
pos: Any # World position as (x, y, z) tuple
|
|
scale: float # Uniform scale factor (float)
|
|
sprite_index: int # Index into sprite sheet (int)
|
|
texture: Any # Sprite sheet texture (Texture or None)
|
|
theta: float # Horizontal rotation for 'fixed' mode in radians (float)
|
|
visible: bool # Visibility state (bool)
|
|
|
|
class CallableBinding:
|
|
"""A binding that calls a Python function to get its value."""
|
|
def __init__(self, callable: Callable[[], float]) -> None: ...
|
|
callable: Any # The Python callable (read-only).
|
|
is_valid: bool # True if the callable is still valid (bool, read-only).
|
|
value: float # Current value from calling the callable (float, read-only). Returns None on error.
|
|
|
|
class Caption:
|
|
"""A text display UI element with customizable font and styling."""
|
|
def __init__(self, pos=None, font=None, text='', **kwargs) -> None: ...
|
|
align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
|
|
bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
fill_color: Color # Fill color of the text (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
|
|
font_size: int # Font size in points (int). Clamped to the range [0, 65535].
|
|
global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
|
|
grid_pos: Vector # Position in grid tile coordinates (Vector). Only valid when parent is a Grid.
|
|
grid_size: Vector # Size in grid tile coordinates (Vector). Only valid when parent is a Grid.
|
|
h: float # Text height in pixels (float, read-only).
|
|
horiz_margin: float # Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
|
|
hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
|
|
margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
|
|
name: str # Name for finding elements (str).
|
|
on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
|
|
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
|
|
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
|
|
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
origin: Any # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
|
|
outline: float # Thickness of the text outline border (float). Clamped to non-negative values.
|
|
outline_color: Color # Outline color of the text (Color). Returns a copy; modifying components requires reassignment. For animation, use 'outline_color.r', 'outline_color.g', etc.
|
|
parent: Any # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
|
|
pos: Any # Position as (x, y) Vector.
|
|
rotate_with_camera: bool # Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of ...
|
|
rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property.
|
|
shader: Any # Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
|
|
size: Any # Text dimensions as Vector (read-only).
|
|
text: str # The text string displayed by this Caption (str).
|
|
uniforms: Any # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/...
|
|
vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
w: float # Text width in pixels (float, read-only).
|
|
x: float # X coordinate of top-left corner (float).
|
|
y: float # Y coordinate of top-left corner (float).
|
|
z_index: Any # Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this drawable's property."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Reapply alignment relative to parent, useful for responsive layouts."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
|
|
class Circle:
|
|
"""A circle UI element for drawing filled or outlined circles."""
|
|
def __init__(self, radius=0, center=None, fill_color=None, outline_color=None, outline=0, **kwargs) -> None: ...
|
|
align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
|
|
bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
center: Vector # Center position of the circle (Vector).
|
|
fill_color: Color # Fill color of the circle (Color).
|
|
global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
|
|
grid_pos: Vector # Position in grid tile coordinates (Vector). Only meaningful when parent is a Grid.
|
|
grid_size: Vector # Size in grid tile coordinates (Vector). Only meaningful when parent is a Grid.
|
|
horiz_margin: float # Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
|
|
hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
|
|
margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
|
|
name: str # Name for finding this element (str).
|
|
on_click: Callable | None # Callable executed when circle is clicked (Callable | None). Function receives (pos: Vector, button: MouseButton, action: InputState).
|
|
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
|
|
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
|
|
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
origin: Any # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
|
|
outline: float # Outline thickness in pixels (float). Use 0 for no outline.
|
|
outline_color: Color # Outline color of the circle (Color).
|
|
parent: Any # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
|
|
pos: Vector # Position as a Vector (same as center) (Vector).
|
|
radius: float # Circle radius in pixels (float).
|
|
rotate_with_camera: bool # Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of ...
|
|
rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property.
|
|
vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
z_index: int # Z-order for rendering (int). Lower values are rendered first.
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this drawable's property."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Reapply alignment relative to parent, useful for responsive layouts."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
|
|
class Color:
|
|
"""RGBA color representation."""
|
|
def __init__(self, r: int = 0, g: int = 0, b: int = 0, a: int = 255) -> None: ...
|
|
a: Any # Alpha component (0-255, where 0=transparent, 255=opaque). Automatically clamped to valid range.
|
|
b: Any # Blue component (0-255). Automatically clamped to valid range.
|
|
g: Any # Green component (0-255). Automatically clamped to valid range.
|
|
r: Any # Red component (0-255). Automatically clamped to valid range.
|
|
def from_hex(self, hex_string: str) -> Color:
|
|
"""Create a Color from a hexadecimal string."""
|
|
...
|
|
def lerp(self, other: Color, t: float) -> Color:
|
|
"""Linearly interpolate between this color and another."""
|
|
...
|
|
def to_hex(self) -> str:
|
|
"""Convert this Color to a hexadecimal string."""
|
|
...
|
|
|
|
class ColorLayer:
|
|
"""A grid layer that stores RGBA colors per cell for background/overlay effects."""
|
|
def __init__(self, z_index=-1, name=None, grid_size=None) -> None: ...
|
|
grid: Grid | None # Parent Grid or None (Grid | None). Setting manages layer association and handles lazy allocation.
|
|
grid_size: tuple # Layer dimensions as (width, height) tuple (tuple, read-only).
|
|
name: str # Layer name (str, read-only). Used for Grid.layer(name) lookup.
|
|
visible: bool # Whether the layer is rendered (bool).
|
|
z_index: int # Layer z-order (int). Negative values render below entities.
|
|
def apply_gradient(self, source: HeightMap, range: tuple, color_low: Color, color_high: Color) -> ColorLayer:
|
|
"""Interpolate between two colors based on HeightMap value within a range. Uses the original heightmap value for smooth transitions."""
|
|
...
|
|
def apply_perspective(self, entity: Entity, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None:
|
|
"""Bind this layer to an entity for automatic FOV updates. After binding, call update_perspective() when the entity moves."""
|
|
...
|
|
def apply_ranges(self, source: HeightMap, ranges: list) -> ColorLayer:
|
|
"""Apply multiple color assignments from a HeightMap in a single pass. Later ranges override earlier ones if overlapping."""
|
|
...
|
|
def apply_threshold(self, source: HeightMap, range: tuple, color: Color) -> ColorLayer:
|
|
"""Set a fixed color for cells where the HeightMap value falls within a range."""
|
|
...
|
|
def at(self, *args, **kwargs) -> Any:
|
|
"""at(pos: tuple | Vector) or (x: int, y: int) -> Color"""
|
|
...
|
|
def clear_perspective(self) -> None:
|
|
"""Remove the perspective binding from this layer."""
|
|
...
|
|
def draw_fov(self, source: tuple, radius: int | None = None, fov: FOV | None = None, visible: Color | None = None, discovered: Color | None = None, unknown: Color | None = None) -> None:
|
|
"""Paint cells based on field-of-view visibility from a source position."""
|
|
...
|
|
def fill(self, color: Color) -> None:
|
|
"""Fill the entire layer with the specified color."""
|
|
...
|
|
def fill_rect(self, pos: tuple, size: tuple, color: Color) -> None:
|
|
"""Fill a rectangular region with a color."""
|
|
...
|
|
def set(self, pos, color: Color) -> None:
|
|
"""Set the color at a cell position."""
|
|
...
|
|
def update_perspective(self) -> None:
|
|
"""Redraw FOV based on the bound entity's current position. Call this after the entity moves to update the visibility layer."""
|
|
...
|
|
|
|
class DijkstraMap:
|
|
"""A Dijkstra distance map from a fixed root position."""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
root: Vector # Root position that distances are measured from (Vector, read-only).
|
|
def descent_step(self, pos: Vector | tuple) -> Vector | None:
|
|
"""Get the adjacent cell with the lowest distance (steepest descent). Unlike step_from, this always returns the best neighbor in a single hop without following ..."""
|
|
...
|
|
def distance(self, pos: Vector | tuple) -> float | None:
|
|
"""Get distance from position to root."""
|
|
...
|
|
def invert(self) -> DijkstraMap:
|
|
"""Return a new DijkstraMap whose distance field is inverted (safety field). Cells near a root become high values; descend to flee from original roots. The orig..."""
|
|
...
|
|
def path_from(self, pos: Vector | tuple) -> AStarPath:
|
|
"""Get full path from position to root."""
|
|
...
|
|
def step_from(self, pos: Vector | tuple) -> Vector | None:
|
|
"""Get single step from position toward root."""
|
|
...
|
|
def to_heightmap(self, size=None, unreachable=-1.0) -> HeightMap:
|
|
"""Convert distance field to a HeightMap. Each cell's height equals its pathfinding distance from the root, useful for visualization, procedural terrain, or inf..."""
|
|
...
|
|
|
|
class DiscreteMap:
|
|
"""A 2D grid of uint8 values (0-255) for discrete/categorical data."""
|
|
def __init__(self, size: tuple[int, int], fill: int = 0, enum: type[IntEnum] = None) -> None: ...
|
|
enum_type: Any # Optional IntEnum class for value interpretation.
|
|
size: Any # Dimensions (width, height) of the map. Read-only.
|
|
def add(self, other: DiscreteMap | int, *, pos=None, source_pos=None, size=None) -> DiscreteMap:
|
|
"""Add values from another map or a scalar, with saturation to 0-255."""
|
|
...
|
|
def bitwise_and(self, other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap:
|
|
"""Bitwise AND with another DiscreteMap."""
|
|
...
|
|
def bitwise_or(self, other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap:
|
|
"""Bitwise OR with another DiscreteMap."""
|
|
...
|
|
def bitwise_xor(self, other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap:
|
|
"""Bitwise XOR with another DiscreteMap."""
|
|
...
|
|
def bool(self, condition: int | set | callable) -> DiscreteMap:
|
|
"""Create binary mask from condition. Returns NEW DiscreteMap."""
|
|
...
|
|
def clear(self) -> DiscreteMap:
|
|
"""Set all cells to 0. Equivalent to fill(0)."""
|
|
...
|
|
def copy_from(self, other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap:
|
|
"""Copy values from another DiscreteMap into the specified region."""
|
|
...
|
|
def count(self, value: int) -> int:
|
|
"""Count cells with the specified value."""
|
|
...
|
|
def count_range(self, min_val: int, max_val: int) -> int:
|
|
"""Count cells with values in the specified range (inclusive)."""
|
|
...
|
|
def fill(self, value: int, *, pos=None, size=None) -> DiscreteMap:
|
|
"""Set cells in region to the specified value."""
|
|
...
|
|
def from_bytes(self, data: bytes, size: tuple[int, int], *, enum: type = None) -> DiscreteMap:
|
|
"""Create a DiscreteMap from raw byte data."""
|
|
...
|
|
def from_heightmap(self, hmap: HeightMap, mapping: list[tuple[tuple[float, float], int]], *, enum=None) -> DiscreteMap:
|
|
"""Create DiscreteMap from HeightMap using range-to-value mapping."""
|
|
...
|
|
def get(self, *args, **kwargs) -> Any:
|
|
"""get(x, y) or (pos) -> int | Enum"""
|
|
...
|
|
def histogram(self) -> dict[int, int]:
|
|
"""Get a histogram of value counts."""
|
|
...
|
|
def invert(self) -> DiscreteMap:
|
|
"""Return NEW DiscreteMap with (255 - value) for each cell."""
|
|
...
|
|
def mask(self) -> memoryview:
|
|
"""Get raw uint8_t data as memoryview for libtcod compatibility."""
|
|
...
|
|
def max(self, other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap:
|
|
"""Set each cell to the maximum of this and another DiscreteMap."""
|
|
...
|
|
def min(self, other: DiscreteMap, *, pos=None, source_pos=None, size=None) -> DiscreteMap:
|
|
"""Set each cell to the minimum of this and another DiscreteMap."""
|
|
...
|
|
def min_max(self) -> tuple[int, int]:
|
|
"""Get the minimum and maximum values in the map."""
|
|
...
|
|
def multiply(self, factor: float, *, pos=None, size=None) -> DiscreteMap:
|
|
"""Multiply values by a scalar factor, with saturation to 0-255."""
|
|
...
|
|
def set(self, x: int, y: int, value: int) -> None:
|
|
"""Set the value at integer coordinates."""
|
|
...
|
|
def subtract(self, other: DiscreteMap | int, *, pos=None, source_pos=None, size=None) -> DiscreteMap:
|
|
"""Subtract values from another map or a scalar, with saturation to 0-255."""
|
|
...
|
|
def to_bytes(self) -> bytes:
|
|
"""Serialize map data to bytes (row-major, one byte per cell)."""
|
|
...
|
|
def to_heightmap(self, mapping: dict[int, float] = None) -> HeightMap:
|
|
"""Convert to HeightMap, optionally mapping values to floats."""
|
|
...
|
|
|
|
class Drawable:
|
|
"""Base class for all drawable UI elements"""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
z_index: Any # Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
|
|
class Entity:
|
|
"""A game entity that exists on a grid with sprite rendering."""
|
|
def __init__(self, grid_pos=None, texture=None, sprite_index=0, **kwargs) -> None: ...
|
|
behavior_type: int # Current behavior type (int, read-only). Use set_behavior() to change.
|
|
cell_pos: Vector # Integer logical cell position (Vector). Alias for grid_pos (the canonical name).
|
|
cell_x: int # Integer X cell coordinate (int). Alias for grid_x.
|
|
cell_y: int # Integer Y cell coordinate (int). Alias for grid_y.
|
|
default_behavior: int # Default behavior type (int, maps to Behavior enum). Entity reverts to this after DONE trigger. Default: 0 (IDLE).
|
|
draw_pos: Vector # Fractional tile position for rendering (Vector). Use for smooth animation between grid cells.
|
|
grid: Any # Grid this entity belongs to (Grid or None). Assign a Grid to attach the entity, or None to remove it from its current grid.
|
|
grid_pos: Vector # Integer logical cell position (Vector). Canonical cell-position property matching the 'grid_pos' constructor argument. Decoupled from draw_pos. Determines wh...
|
|
grid_x: int # Integer X cell coordinate (int). Canonical; matches grid_pos.
|
|
grid_y: int # Integer Y cell coordinate (int). Canonical; matches grid_pos.
|
|
labels: frozenset # String labels for collision and targeting (frozenset). Assign any iterable of strings to replace all labels.
|
|
move_speed: float # Animation duration for behavior movement in seconds (float). 0 = instant. Default: 0.15.
|
|
name: str # Entity name for lookup (str).
|
|
opacity: float # Render opacity (float). 0.0 = fully transparent, 1.0 = fully opaque.
|
|
perspective_map: DiscreteMap # Per-entity FOV memory (DiscreteMap). 3-state values per cell: 0=unknown, 1=discovered, 2=visible. Lazy-allocated on first access once entity has a grid; retu...
|
|
pos: Vector # Pixel position relative to grid (Vector). Computed as draw_pos * tile_size. Requires entity to be attached to a grid.
|
|
shader: Any # GPU shader for visual effects (Shader or None). Set to None to disable shader rendering.
|
|
sight_radius: int # FOV radius for TARGET trigger (int). Default: 10.
|
|
sprite_grid: Any # Per-tile sprite indices for composite multi-tile entities (list of lists or None). Row-major, dimensions must match tile_width x tile_height. Use -1 for empt...
|
|
sprite_index: int # Sprite index into the entity's texture atlas (int).
|
|
sprite_offset: Vector # Pixel offset for oversized sprites (Vector). Applied pre-zoom during grid rendering.
|
|
sprite_offset_x: float # X component of sprite pixel offset (float).
|
|
sprite_offset_y: float # Y component of sprite pixel offset (float).
|
|
step: Any # Step callback for grid.step() turn management (Callable or None). Called with (trigger, data) when behavior triggers fire.
|
|
target_label: Any # Label to search for with TARGET trigger (str or None). Default: None.
|
|
texture: Texture # Sprite texture atlas (Texture). Defaults to mcrfpy.default_texture at construction. Setting preserves sprite_index (not re-validated against the new atlas).
|
|
tile_height: int # Entity height in tiles (int). Must be >= 1. Default 1.
|
|
tile_size: Vector # Entity size in tiles as (width, height) (Vector). Default (1, 1).
|
|
tile_width: int # Entity width in tiles (int). Must be >= 1. Default 1.
|
|
turn_order: int # Turn order for grid.step() (int). 0 = skip, higher values go later. Default: 1.
|
|
uniforms: UniformCollection # Collection of shader uniforms (UniformCollection, read-only). Set values via dict-like syntax: entity.uniforms['name'] = value.
|
|
visible: bool # Visibility flag (bool). When False, the entity is not rendered.
|
|
x: float # Pixel X position relative to grid (float). Requires entity to be attached to a grid.
|
|
y: float # Pixel Y position relative to grid (float). Requires entity to be attached to a grid.
|
|
def add_label(self, label: str) -> None:
|
|
"""Add a label to this entity. Idempotent; adding the same label twice is safe."""
|
|
...
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this entity's property."""
|
|
...
|
|
def at(self, x: int, y: int) -> GridPoint | None:
|
|
"""Return the GridPoint at (x, y) if currently VISIBLE to this entity's perspective_map, otherwise None."""
|
|
...
|
|
def die(self) -> None:
|
|
"""Remove this entity from its grid."""
|
|
...
|
|
def find_path(self, target, diagonal_cost: float = 1.41, collide: str = None) -> AStarPath | None:
|
|
"""Find a path from this entity to the target position."""
|
|
...
|
|
def has_label(self, label: str) -> bool:
|
|
"""Check if this entity has the given label."""
|
|
...
|
|
def index(self) -> int:
|
|
"""Return the index of this entity in its grid's entity collection."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def path_to(self, x: int, y: int) -> list:
|
|
"""Find a path to the target position using A* pathfinding."""
|
|
...
|
|
def remove_label(self, label: str) -> None:
|
|
"""Remove a label from this entity. No-op if label is not present."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
def set_behavior(self, type, waypoints=None, turns: int = 0, path=None, pathfinder=None) -> None:
|
|
"""Configure this entity's behavior for grid.step() turn management."""
|
|
...
|
|
def update_visibility(self) -> None:
|
|
"""Recompute which cells are visible from this entity's position and update perspective_map."""
|
|
...
|
|
def visible_entities(self, fov=None, radius: int | None = None) -> list[Entity]:
|
|
"""Get list of other entities visible from this entity's position."""
|
|
...
|
|
|
|
class Entity3D:
|
|
"""A 3D game entity that exists on a Viewport3D's navigation grid."""
|
|
def __init__(self, pos=None, **kwargs) -> None: ...
|
|
anim_clip: Any # Current animation clip name. Set to play an animation.
|
|
anim_frame: Any # Current animation frame number (read-only, approximate at 30fps).
|
|
anim_loop: Any # Whether animation loops when it reaches the end.
|
|
anim_paused: Any # Whether animation playback is paused.
|
|
anim_speed: Any # Animation playback speed multiplier. 1.0 = normal speed.
|
|
anim_time: Any # Current time position in animation (seconds).
|
|
auto_animate: Any # Enable auto-play of walk/idle clips based on movement.
|
|
color: Any # Entity render color.
|
|
grid_pos: Any # Grid position (x, z). Same as pos.
|
|
idle_clip: Any # Animation clip to play when entity is stationary.
|
|
is_moving: Any # Whether entity is currently moving (read-only).
|
|
model: Model3D # 3D model (Model3D). If None, uses placeholder cube.
|
|
name: str # Entity name (str). Used for find() lookup.
|
|
on_anim_complete: Any # Callback(entity, clip_name) when non-looping animation ends.
|
|
pos: Any # Grid position (x, z). Setting triggers smooth movement.
|
|
rotation: Any # Y-axis rotation in degrees.
|
|
scale: Any # Uniform scale factor. Can also set as (x, y, z) tuple.
|
|
viewport: Any # Owning Viewport3D (read-only).
|
|
visible: Any # Visibility state.
|
|
walk_clip: Any # Animation clip to play when entity is moving.
|
|
world_pos: Any # Current world position (x, y, z) (read-only). Includes animation interpolation.
|
|
def animate(self, property, target, duration, easing=None, delta=False, callback=None, conflict_mode=None) -> Any:
|
|
"""Animate a property over time."""
|
|
...
|
|
def at(self, x, z) -> dict:
|
|
"""Get visibility state for a cell from this entity's perspective."""
|
|
...
|
|
def clear_path(self) -> Any:
|
|
"""Clear the movement queue and stop at current position."""
|
|
...
|
|
def follow_path(self, path) -> Any:
|
|
"""Queue path positions for smooth movement."""
|
|
...
|
|
def path_to(self, *args, **kwargs) -> Any:
|
|
"""path_to(x, z) or path_to(pos=(x, z)) -> list"""
|
|
...
|
|
def teleport(self, *args, **kwargs) -> Any:
|
|
"""teleport(x, z) or teleport(pos=(x, z))"""
|
|
...
|
|
def update_visibility(self) -> Any:
|
|
"""Recompute field of view from current position."""
|
|
...
|
|
|
|
class EntityCollection3D:
|
|
"""Collection of Entity3D objects belonging to a Viewport3D."""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
def append(self, entity) -> Any:
|
|
"""Add an Entity3D to the collection."""
|
|
...
|
|
def clear(self) -> Any:
|
|
"""Remove all entities from the collection."""
|
|
...
|
|
def extend(self, iterable) -> Any:
|
|
"""Add all Entity3D objects from iterable to the collection."""
|
|
...
|
|
def find(self, name) -> Entity3D or None:
|
|
"""Find an Entity3D by name. Returns None if not found."""
|
|
...
|
|
def pop(self, index=-1) -> Entity3D:
|
|
"""Remove and return Entity3D at index (default: last)."""
|
|
...
|
|
def remove(self, entity) -> Any:
|
|
"""Remove an Entity3D from the collection."""
|
|
...
|
|
|
|
class EntityCollection3DIter:
|
|
"""Iterator for EntityCollection3D"""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
|
|
class Font:
|
|
"""A font resource for rendering text in Caption elements."""
|
|
def __init__(self, filename: str) -> None: ...
|
|
family: str # Font family name (str, read-only). Retrieved from font metadata.
|
|
source: str # Source filename path (str, read-only). The path used to load this font.
|
|
|
|
class Frame:
|
|
"""A rectangular frame UI element that can contain other drawable elements."""
|
|
def __init__(self, pos=None, size=None, **kwargs) -> None: ...
|
|
align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
|
|
bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
cache_subtree: bool # Cache the frame and all children to a render texture for performance (bool). Useful for complex static subtrees.
|
|
children: UICollection # UICollection of child drawable objects rendered on top of this frame (UICollection, read-only).
|
|
clip_children: bool # Whether to clip child elements to the frame's bounds (bool). Enables render-texture mode when True.
|
|
fill_color: Color # Fill color of the rectangle (Color). Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
|
|
global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
|
|
grid_pos: Vector # Position in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid.
|
|
grid_size: Vector # Size in grid tile coordinates (Vector). Only meaningful when this element's parent is a Grid.
|
|
h: float # Height of the rectangle (float).
|
|
horiz_margin: float # Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
|
|
hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
|
|
margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
|
|
name: str # Name for finding elements (str).
|
|
on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
|
|
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
|
|
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
|
|
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
origin: Any # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
|
|
outline: float # Thickness of the border in pixels (float).
|
|
outline_color: Color # Outline color of the rectangle (Color). Returns a copy; modifying components requires reassignment. For animation, use 'outline_color.r', 'outline_color.g', ...
|
|
parent: Any # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
|
|
pos: Vector # Position as a Vector (Vector).
|
|
rotate_with_camera: bool # Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of ...
|
|
rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property.
|
|
shader: Any # Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
|
|
uniforms: Any # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/...
|
|
vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
w: float # Width of the rectangle (float).
|
|
x: float # X coordinate of the top-left corner (float).
|
|
y: float # Y coordinate of the top-left corner (float).
|
|
z_index: Any # Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this drawable's property."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Reapply alignment relative to parent, useful for responsive layouts."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
|
|
class Grid:
|
|
"""A grid-based UI element for tile-based rendering and entity management."""
|
|
def __init__(self, grid_size=None, pos=None, size=None, texture=None, **kwargs) -> None: ...
|
|
align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
|
|
bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
camera_rotation: float # Rotation of grid contents around camera center in degrees (float).
|
|
center: Vector # Camera center point in pixel coordinates (Vector).
|
|
center_x: float # Camera center X-coordinate in pixel space (float).
|
|
center_y: float # Camera center Y-coordinate in pixel space (float).
|
|
children: UICollection # UICollection of UIDrawable children such as speech bubbles, effects, and overlays (UICollection, read-only).
|
|
entities: EntityCollection # EntityCollection of entities on this grid (EntityCollection, read-only).
|
|
fill_color: Color # Background fill color (Color). Drawn behind all tiles and entities.
|
|
fov: Any # FOV algorithm for this grid (FOV enum). Used by entity.updateVisibility() and layer methods when fov=None.
|
|
fov_radius: int # Default FOV radius for this grid (int). Used when radius is not specified.
|
|
global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
|
|
grid_data: Grid | None # The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.
|
|
grid_h: int # Grid height in cells (int, read-only).
|
|
grid_pos: Vector # Position in parent grid's tile coordinates (Vector). Only valid when parent is a Grid.
|
|
grid_size: Vector # Grid dimensions as (grid_w, grid_h) (Vector, read-only).
|
|
grid_w: int # Grid width in cells (int, read-only).
|
|
h: float # Visible widget height (float).
|
|
horiz_margin: float # Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
|
|
hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
|
|
hovered_cell: tuple | None # Currently hovered cell as (x, y) tuple, or None if not hovering (tuple | None, read-only).
|
|
layers: tuple # Tuple of grid layers sorted by z_index (tuple, read-only). Contains ColorLayer and TileLayer objects.
|
|
margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
|
|
name: str # Name for finding elements (str).
|
|
on_cell_click: Callable | None # Callback when a grid cell is clicked (Callable | None). Called with (cell_pos: Vector, button: MouseButton, action: InputState).
|
|
on_cell_enter: Callable | None # Callback when mouse enters a grid cell (Callable | None). Called with (cell_pos: Vector).
|
|
on_cell_exit: Callable | None # Callback when mouse exits a grid cell (Callable | None). Called with (cell_pos: Vector).
|
|
on_click: Callable | None # Callable executed when object is clicked (Callable | None).
|
|
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
|
|
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
|
|
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
origin: Any # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
|
|
parent: Any # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
|
|
perspective: Entity | None # Entity whose perspective to use for FOV rendering (Entity | None). Setting an entity automatically enables perspective mode. Set to None for omniscient view.
|
|
perspective_enabled: bool # Whether to use perspective-based FOV rendering (bool). When True with no valid entity, all cells appear undiscovered.
|
|
pos: Vector # Position of the grid as Vector (Vector).
|
|
rotate_with_camera: bool # Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of ...
|
|
rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property.
|
|
shader: Any # Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
|
|
size: Vector # Size of the grid widget as Vector (Vector, width x height in pixels).
|
|
texture: Texture | None # Texture used for tile rendering (Texture | None, read-only).
|
|
uniforms: Any # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/...
|
|
vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
|
|
view: GridView | None # Auto-created GridView for rendering (GridView | None, read-only). When Grid is appended to a scene, this view is what actually renders.
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
w: float # Visible widget width (float).
|
|
x: float # Top-left corner X-coordinate (float).
|
|
y: float # Top-left corner Y-coordinate (float).
|
|
z_index: int # Z-order for rendering (int). Lower values are rendered first.
|
|
zoom: float # Zoom level for rendering (float). Values greater than 1.0 magnify; less than 1.0 shrink.
|
|
def add_layer(self, layer: ColorLayer | TileLayer) -> ColorLayer | TileLayer:
|
|
"""Add a layer to the grid. Layers with size (0, 0) are automatically resized to match the grid."""
|
|
...
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this drawable's property."""
|
|
...
|
|
def apply_ranges(self, source: HeightMap, ranges: list) -> Grid:
|
|
"""Apply multiple walkability thresholds to the grid in a single pass."""
|
|
...
|
|
def apply_threshold(self, source: HeightMap, range: tuple, walkable: bool = None, transparent: bool = None) -> Grid:
|
|
"""Apply walkable/transparent properties to cells where heightmap values fall within range."""
|
|
...
|
|
def at(self, x: int, y: int) -> GridPoint:
|
|
"""Return the GridPoint cell at grid coordinates (x, y)."""
|
|
...
|
|
def center_camera(self, pos: tuple = None) -> None:
|
|
"""Center the camera on a tile coordinate. If pos is None, centers on the grid's middle tile."""
|
|
...
|
|
def clear_dijkstra_maps(self) -> None:
|
|
"""Clear all cached Dijkstra maps. Call this after modifying grid cell walkability to ensure pathfinding uses updated walkability data."""
|
|
...
|
|
def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC) -> None:
|
|
"""Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility."""
|
|
...
|
|
def entities_in_radius(self, pos: tuple | Vector, radius: float) -> list:
|
|
"""Query entities within radius using spatial hash (O(k) where k = nearby entities)."""
|
|
...
|
|
def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0) -> AStarPath | None:
|
|
"""Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step."""
|
|
...
|
|
def get_dijkstra_map(self, root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None) -> DijkstraMap:
|
|
"""Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate."""
|
|
...
|
|
def is_in_fov(self, x: int, y: int) -> bool:
|
|
"""Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility."""
|
|
...
|
|
def layer(self, name: str) -> ColorLayer | TileLayer | None:
|
|
"""Get a layer by its name."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Reapply alignment relative to parent, useful for responsive layouts."""
|
|
...
|
|
def remove_layer(self, name_or_layer: str | ColorLayer | TileLayer) -> None:
|
|
"""Remove a layer from the grid by name or by object reference."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
def step(self, n: int = 1, turn_order: int = None) -> None:
|
|
"""Execute n rounds of turn-based entity behavior. Each round: entities grouped by turn_order (ascending), behaviors executed, triggers fired (TARGET, DONE, BLO..."""
|
|
...
|
|
|
|
class GridView:
|
|
"""A grid-based UI element for tile-based rendering and entity management."""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
|
|
bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
camera_rotation: float # Rotation of grid contents around camera center in degrees (float).
|
|
center: Vector # Camera center point in pixel coordinates (Vector).
|
|
center_x: float # Camera center X-coordinate in pixel space (float).
|
|
center_y: float # Camera center Y-coordinate in pixel space (float).
|
|
children: UICollection # UICollection of UIDrawable children such as speech bubbles, effects, and overlays (UICollection, read-only).
|
|
entities: EntityCollection # EntityCollection of entities on this grid (EntityCollection, read-only).
|
|
fill_color: Color # Background fill color (Color). Drawn behind all tiles and entities.
|
|
fov: Any # FOV algorithm for this grid (FOV enum). Used by entity.updateVisibility() and layer methods when fov=None.
|
|
fov_radius: int # Default FOV radius for this grid (int). Used when radius is not specified.
|
|
global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
|
|
grid_data: Grid | None # The underlying grid data object (Grid | None). Used for multi-view scenarios where multiple GridViews share one Grid.
|
|
grid_h: int # Grid height in cells (int, read-only).
|
|
grid_pos: Vector # Position in parent grid's tile coordinates (Vector). Only valid when parent is a Grid.
|
|
grid_size: Vector # Grid dimensions as (grid_w, grid_h) (Vector, read-only).
|
|
grid_w: int # Grid width in cells (int, read-only).
|
|
h: float # Visible widget height (float).
|
|
horiz_margin: float # Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
|
|
hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
|
|
hovered_cell: tuple | None # Currently hovered cell as (x, y) tuple, or None if not hovering (tuple | None, read-only).
|
|
layers: tuple # Tuple of grid layers sorted by z_index (tuple, read-only). Contains ColorLayer and TileLayer objects.
|
|
margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
|
|
name: str # Name for finding elements (str).
|
|
on_cell_click: Callable | None # Callback when a grid cell is clicked (Callable | None). Called with (cell_pos: Vector, button: MouseButton, action: InputState).
|
|
on_cell_enter: Callable | None # Callback when mouse enters a grid cell (Callable | None). Called with (cell_pos: Vector).
|
|
on_cell_exit: Callable | None # Callback when mouse exits a grid cell (Callable | None). Called with (cell_pos: Vector).
|
|
on_click: Callable | None # Callable executed when object is clicked (Callable | None).
|
|
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
|
|
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
|
|
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
origin: Any # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
|
|
parent: Any # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
|
|
perspective: Entity | None # Entity whose perspective to use for FOV rendering (Entity | None). Setting an entity automatically enables perspective mode. Set to None for omniscient view.
|
|
perspective_enabled: bool # Whether to use perspective-based FOV rendering (bool). When True with no valid entity, all cells appear undiscovered.
|
|
pos: Vector # Position of the grid as Vector (Vector).
|
|
rotate_with_camera: bool # Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of ...
|
|
rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property.
|
|
shader: Any # Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
|
|
size: Vector # Size of the grid widget as Vector (Vector, width x height in pixels).
|
|
texture: Texture | None # Texture used for tile rendering (Texture | None, read-only).
|
|
uniforms: Any # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/...
|
|
vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
|
|
view: GridView | None # Auto-created GridView for rendering (GridView | None, read-only). When Grid is appended to a scene, this view is what actually renders.
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
w: float # Visible widget width (float).
|
|
x: float # Top-left corner X-coordinate (float).
|
|
y: float # Top-left corner Y-coordinate (float).
|
|
z_index: int # Z-order for rendering (int). Lower values are rendered first.
|
|
zoom: float # Zoom level for rendering (float). Values greater than 1.0 magnify; less than 1.0 shrink.
|
|
def add_layer(self, layer: ColorLayer | TileLayer) -> ColorLayer | TileLayer:
|
|
"""Add a layer to the grid. Layers with size (0, 0) are automatically resized to match the grid."""
|
|
...
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this drawable's property."""
|
|
...
|
|
def apply_ranges(self, source: HeightMap, ranges: list) -> Grid:
|
|
"""Apply multiple walkability thresholds to the grid in a single pass."""
|
|
...
|
|
def apply_threshold(self, source: HeightMap, range: tuple, walkable: bool = None, transparent: bool = None) -> Grid:
|
|
"""Apply walkable/transparent properties to cells where heightmap values fall within range."""
|
|
...
|
|
def at(self, x: int, y: int) -> GridPoint:
|
|
"""Return the GridPoint cell at grid coordinates (x, y)."""
|
|
...
|
|
def center_camera(self, pos: tuple = None) -> None:
|
|
"""Center the camera on a tile coordinate. If pos is None, centers on the grid's middle tile."""
|
|
...
|
|
def clear_dijkstra_maps(self) -> None:
|
|
"""Clear all cached Dijkstra maps. Call this after modifying grid cell walkability to ensure pathfinding uses updated walkability data."""
|
|
...
|
|
def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: FOV | int = FOV.BASIC) -> None:
|
|
"""Compute field of view from a position. Updates the internal FOV state; use is_in_fov() to query visibility."""
|
|
...
|
|
def entities_in_radius(self, pos: tuple | Vector, radius: float) -> list:
|
|
"""Query entities within radius using spatial hash (O(k) where k = nearby entities)."""
|
|
...
|
|
def find_path(self, start, end, diagonal_cost: float = 1.41, collide: str = None, heuristic = None, weight: float = 1.0) -> AStarPath | None:
|
|
"""Compute A* path between two points. The returned AStarPath can be iterated or walked step-by-step."""
|
|
...
|
|
def get_dijkstra_map(self, root=None, diagonal_cost: float = 1.41, collide: str = None, roots=None) -> DijkstraMap:
|
|
"""Get or create a cached Dijkstra distance map for a root position. Call clear_dijkstra_maps() after changing grid walkability to invalidate."""
|
|
...
|
|
def is_in_fov(self, x: int, y: int) -> bool:
|
|
"""Check if a cell is in the field of view. Must call compute_fov() first to calculate visibility."""
|
|
...
|
|
def layer(self, name: str) -> ColorLayer | TileLayer | None:
|
|
"""Get a layer by its name."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Reapply alignment relative to parent, useful for responsive layouts."""
|
|
...
|
|
def remove_layer(self, name_or_layer: str | ColorLayer | TileLayer) -> None:
|
|
"""Remove a layer from the grid by name or by object reference."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
def step(self, n: int = 1, turn_order: int = None) -> None:
|
|
"""Execute n rounds of turn-based entity behavior. Each round: entities grouped by turn_order (ascending), behaviors executed, triggers fired (TARGET, DONE, BLO..."""
|
|
...
|
|
|
|
class HeightMap:
|
|
"""A 2D grid of float values for procedural generation."""
|
|
def __init__(self, size: tuple[int, int], fill: float = 0.0) -> None: ...
|
|
size: Any # Dimensions (width, height) of the heightmap. Read-only.
|
|
def add(self, other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap:
|
|
"""Add another heightmap's values to this one in the specified region."""
|
|
...
|
|
def add_bsp(self, bsp: BSP, *, pos=None, select: str = 'leaves', nodes: list = None, shrink: int = 0, value: float = 1.0) -> HeightMap:
|
|
"""Add BSP node regions to heightmap. More efficient than creating intermediate HeightMap."""
|
|
...
|
|
def add_constant(self, value: float, *, pos=None, size=None) -> HeightMap:
|
|
"""Add a constant value to cells in region."""
|
|
...
|
|
def add_hill(self, center, radius: float, height: float) -> HeightMap:
|
|
"""Add a smooth hill at the specified position."""
|
|
...
|
|
def add_noise(self, source: NoiseSource, world_origin: tuple = (0.0, 0.0), world_size: tuple = None, mode: str = 'fbm', octaves: int = 4, scale: float = 1.0) -> HeightMap:
|
|
"""Sample noise and add to current values. More efficient than creating intermediate HeightMap."""
|
|
...
|
|
def add_voronoi(self, num_points: int, coefficients: tuple = (1.0, -0.5), seed: int = None) -> HeightMap:
|
|
"""Add Voronoi-based terrain features."""
|
|
...
|
|
def clamp(self, min: float = 0.0, max: float = 1.0, *, pos=None, size=None) -> HeightMap:
|
|
"""Clamp values in region to the specified range."""
|
|
...
|
|
def clear(self) -> HeightMap:
|
|
"""Set all cells to 0.0. Equivalent to fill(0.0)."""
|
|
...
|
|
def copy_from(self, other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap:
|
|
"""Copy values from another heightmap into the specified region."""
|
|
...
|
|
def count_in_range(self, range: tuple[float, float]) -> int:
|
|
"""Count cells with values in the specified range (inclusive)."""
|
|
...
|
|
def dig_bezier(self, points: tuple, start_radius: float, end_radius: float, start_height: float, end_height: float) -> HeightMap:
|
|
"""Construct a canal along a cubic Bezier curve with specified heights."""
|
|
...
|
|
def dig_hill(self, center, radius: float, target_height: float) -> HeightMap:
|
|
"""Construct a pit or crater with the specified center height."""
|
|
...
|
|
def fill(self, value: float, *, pos=None, size=None) -> HeightMap:
|
|
"""Set cells in region to the specified value."""
|
|
...
|
|
def get(self, *args, **kwargs) -> Any:
|
|
"""get(x, y) or (pos) -> float"""
|
|
...
|
|
def get_interpolated(self, *args, **kwargs) -> Any:
|
|
"""get_interpolated(x, y) or (pos) -> float"""
|
|
...
|
|
def get_normal(self, *args, **kwargs) -> Any:
|
|
"""get_normal(x, y, water_level=0.0) or (pos, water_level=0.0) -> tuple[float, float, float]"""
|
|
...
|
|
def get_slope(self, *args, **kwargs) -> Any:
|
|
"""get_slope(x, y) or (pos) -> float"""
|
|
...
|
|
def inverse(self) -> HeightMap:
|
|
"""Return NEW HeightMap with (1.0 - value) for each cell."""
|
|
...
|
|
def lerp(self, other: HeightMap, t: float, *, pos=None, source_pos=None, size=None) -> HeightMap:
|
|
"""Linear interpolation between this and another heightmap in the specified region."""
|
|
...
|
|
def max(self, other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap:
|
|
"""Set each cell in region to the maximum of this and another heightmap."""
|
|
...
|
|
def mid_point_displacement(self, roughness: float = 0.5, seed: int = None) -> HeightMap:
|
|
"""Generate terrain using midpoint displacement algorithm (diamond-square)."""
|
|
...
|
|
def min(self, other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap:
|
|
"""Set each cell in region to the minimum of this and another heightmap."""
|
|
...
|
|
def min_max(self) -> tuple[float, float]:
|
|
"""Get the minimum and maximum height values in the map."""
|
|
...
|
|
def multiply(self, other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap:
|
|
"""Multiply this heightmap by another in the specified region (useful for masking)."""
|
|
...
|
|
def multiply_bsp(self, bsp: BSP, *, pos=None, select: str = 'leaves', nodes: list = None, shrink: int = 0, value: float = 1.0) -> HeightMap:
|
|
"""Multiply by BSP regions. Effectively masks the heightmap to node interiors."""
|
|
...
|
|
def multiply_noise(self, source: NoiseSource, world_origin: tuple = (0.0, 0.0), world_size: tuple = None, mode: str = 'fbm', octaves: int = 4, scale: float = 1.0) -> HeightMap:
|
|
"""Sample noise and multiply with current values. Useful for applying noise-based masks."""
|
|
...
|
|
def normalize(self, min: float = 0.0, max: float = 1.0, *, pos=None, size=None) -> HeightMap:
|
|
"""Linearly rescale values in region. Current min becomes new min, current max becomes new max."""
|
|
...
|
|
def rain_erosion(self, drops: int, erosion: float = 0.1, sedimentation: float = 0.05, seed: int = None) -> HeightMap:
|
|
"""Simulate rain erosion on the terrain."""
|
|
...
|
|
def scale(self, factor: float, *, pos=None, size=None) -> HeightMap:
|
|
"""Multiply cells in region by a factor."""
|
|
...
|
|
def smooth(self, iterations: int = 1) -> HeightMap:
|
|
"""Smooth the heightmap by averaging neighboring cells."""
|
|
...
|
|
def sparse_kernel(self, weights: dict[tuple[int, int], float]) -> HeightMap:
|
|
"""Apply sparse convolution kernel, returning a NEW HeightMap with results."""
|
|
...
|
|
def sparse_kernel_from(self, source: HeightMap, weights: dict[tuple[int, int], float]) -> None:
|
|
"""Apply sparse convolution from source heightmap into self (for reusing destination buffers)."""
|
|
...
|
|
def subtract(self, other: HeightMap, *, pos=None, source_pos=None, size=None) -> HeightMap:
|
|
"""Subtract another heightmap's values from this one in the specified region."""
|
|
...
|
|
def threshold(self, range: tuple[float, float]) -> HeightMap:
|
|
"""Return NEW HeightMap with original values where in range, 0.0 elsewhere."""
|
|
...
|
|
def threshold_binary(self, range: tuple[float, float], value: float = 1.0) -> HeightMap:
|
|
"""Return NEW HeightMap with uniform value where in range, 0.0 elsewhere."""
|
|
...
|
|
|
|
class Keyboard:
|
|
"""Keyboard state singleton for checking modifier keys"""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
alt: Any # True if either Alt key is currently pressed (read-only).
|
|
ctrl: Any # True if either Control key is currently pressed (read-only).
|
|
shift: Any # True if either Shift key is currently pressed (read-only).
|
|
system: Any # True if either System key (Win/Cmd) is currently pressed (read-only).
|
|
|
|
class LdtkProject:
|
|
"""Load an LDtk project file (.ldtk)."""
|
|
def __init__(self, path: str) -> None: ...
|
|
enums: Any # Enum definitions from the project as a list of dicts (read-only).
|
|
level_names: Any # List of level identifier names (list[str], read-only).
|
|
ruleset_names: Any # List of rule set / layer names (list[str], read-only).
|
|
tileset_names: Any # List of tileset identifier names (list[str], read-only).
|
|
version: str # LDtk JSON format version string (str, read-only).
|
|
def level(self, name: str) -> dict:
|
|
"""Get level data by name."""
|
|
...
|
|
def ruleset(self, name: str) -> AutoRuleSet:
|
|
"""Get an auto-rule set by layer name."""
|
|
...
|
|
def tileset(self, name: str) -> TileSetFile:
|
|
"""Get a tileset by name."""
|
|
...
|
|
|
|
class Line:
|
|
"""A line UI element for drawing straight lines between two points."""
|
|
def __init__(self, start=None, end=None, thickness=1.0, color=None, **kwargs) -> None: ...
|
|
align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
|
|
bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
color: Any # Line color as a Color object.
|
|
end: Any # Ending point of the line as a Vector.
|
|
global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
|
|
grid_pos: Vector # Position in grid tile coordinates (Vector, only when parent is Grid).
|
|
grid_size: Vector # Size in grid tile coordinates (Vector, only when parent is Grid).
|
|
horiz_margin: float # Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
|
|
hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
|
|
margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
|
|
name: Any # Name for finding this element.
|
|
on_click: Any # Callable executed when line is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
|
|
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
|
|
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
|
|
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
origin: Any # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
|
|
parent: Any # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
|
|
pos: Any # Position as a Vector (midpoint of line).
|
|
rotate_with_camera: bool # Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of ...
|
|
rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property.
|
|
start: Any # Starting point of the line as a Vector.
|
|
thickness: Any # Line thickness in pixels.
|
|
vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
z_index: Any # Z-order for rendering (lower values rendered first).
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this drawable's property."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Reapply alignment relative to parent, useful for responsive layouts."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
|
|
class Model3D:
|
|
"""A 3D model resource that can be rendered by Entity3D."""
|
|
def __init__(self, path=None) -> None: ...
|
|
animation_clips: Any # List of animation clip names (read-only)
|
|
bone_count: Any # Number of bones in skeleton (read-only)
|
|
bounds: Any # AABB as ((min_x, min_y, min_z), (max_x, max_y, max_z)) (read-only)
|
|
has_skeleton: Any # Whether model has skeletal animation data (read-only)
|
|
mesh_count: Any # Number of submeshes (read-only)
|
|
name: Any # Model name (read-only)
|
|
triangle_count: Any # Total triangle count across all meshes (read-only)
|
|
vertex_count: Any # Total vertex count across all meshes (read-only)
|
|
def cube(self, size=1.0) -> Model3D:
|
|
"""Create a unit cube centered at origin."""
|
|
...
|
|
def plane(self, width=1.0, depth=1.0, segments=1) -> Model3D:
|
|
"""Create a flat plane."""
|
|
...
|
|
def sphere(self, radius=0.5, segments=16, rings=12) -> Model3D:
|
|
"""Create a UV sphere."""
|
|
...
|
|
|
|
class Mouse:
|
|
"""Mouse state singleton for reading button/position state and controlling cursor visibility"""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
grabbed: Any # Whether the mouse cursor is confined to the window (default: False).
|
|
left: Any # True if left mouse button is currently pressed (read-only).
|
|
middle: Any # True if middle mouse button is currently pressed (read-only).
|
|
pos: Any # Current mouse position as Vector (read-only).
|
|
right: Any # True if right mouse button is currently pressed (read-only).
|
|
visible: Any # Whether the mouse cursor is visible (default: True).
|
|
x: Any # Current mouse X position in window coordinates (read-only).
|
|
y: Any # Current mouse Y position in window coordinates (read-only).
|
|
|
|
class Music:
|
|
"""Streaming music object for longer audio tracks"""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
duration: Any # Total duration of the music in seconds (read-only).
|
|
loop: Any # Whether the music loops when it reaches the end.
|
|
playing: Any # True if the music is currently playing (read-only).
|
|
position: Any # Current playback position in seconds. Can be set to seek.
|
|
source: Any # Filename path used to load this music (read-only).
|
|
volume: Any # Volume level from 0 (silent) to 100 (full volume).
|
|
def pause(self) -> None:
|
|
"""Pause the music. Use play() to resume from the paused position."""
|
|
...
|
|
def play(self) -> None:
|
|
"""Start or resume playing the music."""
|
|
...
|
|
def stop(self) -> None:
|
|
"""Stop playing and reset to the beginning."""
|
|
...
|
|
|
|
class NoiseSource:
|
|
"""A configured noise generator for procedural generation."""
|
|
def __init__(self, dimensions: int = 2, algorithm: str = 'simplex', hurst: float = 0.5, lacunarity: float = 2.0, seed: int = None) -> None: ...
|
|
algorithm: Any # Noise algorithm name ('simplex', 'perlin', or 'wavelet'). Read-only.
|
|
dimensions: Any # Number of input dimensions (1-4). Read-only.
|
|
hurst: Any # Hurst exponent for fbm/turbulence. Read-only.
|
|
lacunarity: Any # Frequency multiplier between octaves. Read-only.
|
|
seed: Any # Random seed used (even if originally None). Read-only.
|
|
def fbm(self, pos: tuple[float, ...], octaves: int = 4) -> float:
|
|
"""Get fractal brownian motion value at coordinates."""
|
|
...
|
|
def get(self, pos: tuple[float, ...]) -> float:
|
|
"""Get flat noise value at coordinates."""
|
|
...
|
|
def sample(self, size: tuple[int, int], world_origin: tuple[float, float] = (0.0, 0.0), world_size: tuple[float, float] = None, mode: str = 'fbm', octaves: int = 4) -> HeightMap:
|
|
"""Sample noise into a HeightMap for batch processing."""
|
|
...
|
|
def turbulence(self, pos: tuple[float, ...], octaves: int = 4) -> float:
|
|
"""Get turbulence (absolute fbm) value at coordinates."""
|
|
...
|
|
|
|
class PropertyBinding:
|
|
"""A binding that reads a property value from a UI drawable."""
|
|
def __init__(self, target: UIDrawable, property: str) -> None: ...
|
|
is_valid: bool # True if the binding target still exists and property is valid (bool, read-only).
|
|
property: str # The property name being read (str, read-only).
|
|
target: Any # The drawable this binding reads from (read-only).
|
|
value: float # Current value of the binding (float, read-only). Returns None if invalid.
|
|
|
|
class Scene:
|
|
"""Object-oriented scene management with lifecycle callbacks."""
|
|
def __init__(self, name: str) -> None: ...
|
|
active: bool # Whether this scene is currently active (bool, read-only). Only one scene can be active at a time.
|
|
children: UICollection # UI element collection for this scene (UICollection, read-only). Use to add, remove, or iterate over UI elements. Changes are reflected immediately.
|
|
name: str # Scene name (str, read-only). Unique identifier for this scene.
|
|
on_key: Any # Keyboard event handler (callable or None). Function receives (key: Key, action: InputState) for keyboard events. Set to None to remove the handler.
|
|
opacity: Any # Scene opacity (0.0-1.0). Applied to all UI elements during rendering.
|
|
pos: Vector # Scene position offset (Vector). Applied to all UI elements during rendering.
|
|
registered: bool # Whether this scene is registered with the game engine (bool, read-only). Unregistered scenes still exist but won't receive lifecycle callbacks.
|
|
visible: bool # Scene visibility (bool). If False, scene is not rendered.
|
|
def activate(self, transition: Transition = None, duration: float = None) -> None:
|
|
"""Make this the active scene with optional transition effect."""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Recalculate alignment for all children with alignment set."""
|
|
...
|
|
def register(self) -> None:
|
|
"""Register this scene with the game engine."""
|
|
...
|
|
def unregister(self) -> None:
|
|
"""Unregister this scene from the game engine."""
|
|
...
|
|
|
|
class Shader:
|
|
"""A GPU shader program for visual effects."""
|
|
def __init__(self, fragment_source: str, dynamic: bool = False) -> None: ...
|
|
dynamic: bool # Whether this shader uses time-varying effects (bool). Dynamic shaders invalidate parent caches each frame.
|
|
is_valid: bool # True if the shader compiled successfully (bool, read-only).
|
|
source: str # The GLSL fragment shader source code (str, read-only).
|
|
def set_uniform(self, name: str, value: float|tuple) -> None:
|
|
"""Set a custom uniform value on this shader."""
|
|
...
|
|
|
|
class Sound:
|
|
"""Sound effect object for short audio clips."""
|
|
def __init__(self, source) -> None: ...
|
|
buffer: Any # The SoundBuffer if created from one, else None (read-only).
|
|
duration: Any # Total duration of the sound in seconds (read-only).
|
|
loop: Any # Whether the sound loops when it reaches the end.
|
|
pitch: Any # Playback pitch multiplier (1.0 = normal, >1 = higher, <1 = lower).
|
|
playing: Any # True if the sound is currently playing (read-only).
|
|
source: Any # Filename path used to load this sound (read-only).
|
|
volume: Any # Volume level from 0 (silent) to 100 (full volume).
|
|
def pause(self) -> None:
|
|
"""Pause the sound. Use play() to resume from the paused position."""
|
|
...
|
|
def play(self) -> None:
|
|
"""Start or resume playing the sound."""
|
|
...
|
|
def play_varied(self, pitch_range: float = 0.1, volume_range: float = 3.0) -> None:
|
|
"""Play with randomized pitch and volume for natural variation."""
|
|
...
|
|
def stop(self) -> None:
|
|
"""Stop playing and reset to the beginning."""
|
|
...
|
|
|
|
class SoundBuffer:
|
|
"""SoundBuffer.from_samples(data: bytes, channels: int, sample_rate: int)"""
|
|
def __init__(self, filename: str) -> None: ...
|
|
channels: Any # Number of audio channels (read-only).
|
|
duration: Any # Total duration in seconds (read-only).
|
|
sample_count: Any # Total number of samples (read-only).
|
|
sample_rate: Any # Sample rate in Hz (read-only).
|
|
sfxr_params: Any # Dict of sfxr parameters if sfxr-generated, else None (read-only).
|
|
def bit_crush(self, bits: int, rate_divisor: int) -> SoundBuffer:
|
|
"""Reduce bit depth and sample rate for lo-fi effect."""
|
|
...
|
|
def concat(self, buffers: list[SoundBuffer], overlap: float = 0.0) -> SoundBuffer:
|
|
"""Concatenate multiple SoundBuffers with optional crossfade overlap."""
|
|
...
|
|
def distortion(self, drive: float) -> SoundBuffer:
|
|
"""Apply tanh soft clipping distortion."""
|
|
...
|
|
def echo(self, delay_ms: float, feedback: float, wet: float) -> SoundBuffer:
|
|
"""Apply echo effect with delay, feedback, and wet/dry mix."""
|
|
...
|
|
def from_samples(self, data: bytes, channels: int, sample_rate: int) -> SoundBuffer:
|
|
"""Create a SoundBuffer from raw int16 PCM sample data."""
|
|
...
|
|
def gain(self, factor: float) -> SoundBuffer:
|
|
"""Multiply all samples by a scalar factor. Use for volume/amplitude control before mixing."""
|
|
...
|
|
def high_pass(self, cutoff_hz: float) -> SoundBuffer:
|
|
"""Apply single-pole IIR high-pass filter."""
|
|
...
|
|
def low_pass(self, cutoff_hz: float) -> SoundBuffer:
|
|
"""Apply single-pole IIR low-pass filter."""
|
|
...
|
|
def mix(self, buffers: list[SoundBuffer]) -> SoundBuffer:
|
|
"""Mix multiple SoundBuffers together (additive, clamped)."""
|
|
...
|
|
def normalize(self) -> SoundBuffer:
|
|
"""Scale samples to 95%% of int16 max."""
|
|
...
|
|
def pitch_shift(self, factor: float) -> SoundBuffer:
|
|
"""Resample to shift pitch. factor>1 = higher+shorter."""
|
|
...
|
|
def reverb(self, room_size: float, damping: float, wet: float) -> SoundBuffer:
|
|
"""Apply simplified Freeverb-style reverb."""
|
|
...
|
|
def reverse(self) -> SoundBuffer:
|
|
"""Reverse the sample order."""
|
|
...
|
|
def sfxr(self, preset: str = None, seed: int = None, **params) -> SoundBuffer:
|
|
"""Generate retro sound effects using sfxr synthesis."""
|
|
...
|
|
def sfxr_mutate(self, amount: float = 0.05, seed: int = None) -> SoundBuffer:
|
|
"""Jitter sfxr params and re-synthesize. Only works on sfxr-generated buffers."""
|
|
...
|
|
def slice(self, start: float, end: float) -> SoundBuffer:
|
|
"""Extract a time range in seconds."""
|
|
...
|
|
def tone(self, frequency: float, duration: float, waveform: str = 'sine', **kwargs) -> SoundBuffer:
|
|
"""Generate a tone with optional ADSR envelope."""
|
|
...
|
|
|
|
class Sprite:
|
|
"""A sprite UI element that displays a texture or portion of a texture atlas."""
|
|
def __init__(self, pos=None, texture=None, sprite_index=0, **kwargs) -> None: ...
|
|
align: Any # Alignment relative to parent bounds (Alignment enum or None). When set, position is automatically calculated when parent is assigned or resized. Set to None ...
|
|
bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
|
|
grid_pos: Vector # Position in grid tile coordinates (Vector, only when parent is Grid).
|
|
grid_size: Vector # Size in grid tile coordinates (Vector, only when parent is Grid).
|
|
horiz_margin: float # Horizontal margin override (float, 0 = use general margin). Invalid for vertically-centered alignments (TOP_CENTER, BOTTOM_CENTER, CENTER).
|
|
hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
|
|
margin: float # General margin from edge when aligned (float). Applied to both horizontal and vertical edges unless overridden. Invalid for CENTER alignment (raises ValueErr...
|
|
name: str # Name for finding elements (str).
|
|
on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
|
|
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
|
|
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
|
|
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
origin: Any # Transform origin as Vector (pivot point for rotation). Default (0,0) is top-left; set to (w/2, h/2) to rotate around center.
|
|
parent: Any # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
|
|
pos: Vector # Position as a Vector (Vector).
|
|
rotate_with_camera: bool # Whether to rotate visually with parent Grid's camera_rotation (bool). False (default): stay screen-aligned. True: tilt with camera. Only affects children of ...
|
|
rotation: Any # Rotation angle in degrees (clockwise around origin). Animatable property.
|
|
scale: float # Uniform size factor (float). Sets both horizontal and vertical scale to the same value.
|
|
scale_x: float # Horizontal scale factor (float).
|
|
scale_y: float # Vertical scale factor (float).
|
|
shader: Any # Shader for GPU visual effects (Shader or None). When set, the drawable is rendered through the shader program. Set to None to disable shader effects.
|
|
sprite_index: int # Which sprite on the texture is shown (int). Index into the texture atlas; must be in range [0, sprite_count).
|
|
texture: Texture # Texture object (Texture). The texture atlas from which sprites are drawn.
|
|
uniforms: Any # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: drawable.uniforms['name'] = value. Supports float, vec2/3/...
|
|
vert_margin: float # Vertical margin override (float, 0 = use general margin). Invalid for horizontally-centered alignments (CENTER_LEFT, CENTER_RIGHT, CENTER).
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
x: float # X coordinate of top-left corner (float).
|
|
y: float # Y coordinate of top-left corner (float).
|
|
z_index: Any # Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this drawable's property."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Reapply alignment relative to parent, useful for responsive layouts."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
|
|
class Texture:
|
|
"""A texture atlas for sprites and tiles."""
|
|
def __init__(self, filename: str, sprite_width: int = 0, sprite_height: int = 0, display_size: tuple = None, display_origin: tuple = None) -> None: ...
|
|
display_height: int # Display height of sprite content within each cell (int, read-only). Defaults to sprite_height.
|
|
display_offset_x: int # X offset of sprite content within each cell (int, read-only). Default 0.
|
|
display_offset_y: int # Y offset of sprite content within each cell (int, read-only). Default 0.
|
|
display_width: int # Display width of sprite content within each cell (int, read-only). Defaults to sprite_width.
|
|
sheet_height: int # Number of sprite rows in the texture sheet (int, read-only). Calculated as texture_height / sprite_height.
|
|
sheet_width: int # Number of sprite columns in the texture sheet (int, read-only). Calculated as texture_width / sprite_width.
|
|
source: str # Source filename path (str, read-only). The path used to load this texture.
|
|
sprite_count: int # Total number of sprites in the texture sheet (int, read-only). Equals sheet_width * sheet_height.
|
|
sprite_height: int # Height of each sprite in pixels (int, read-only). Specified during texture initialization.
|
|
sprite_width: int # Width of each sprite in pixels (int, read-only). Specified during texture initialization.
|
|
def composite(self, layers: list[Texture], sprite_width: int, sprite_height: int, name: str = '<composite>') -> Texture:
|
|
"""Alpha-composite multiple texture layers into a single texture."""
|
|
...
|
|
def from_bytes(self, data: bytes, width: int, height: int, sprite_width: int, sprite_height: int, name: str = '<generated>') -> Texture:
|
|
"""Create a Texture from raw RGBA pixel data."""
|
|
...
|
|
def hsl_shift(self, hue_shift: float, sat_shift: float = 0.0, lit_shift: float = 0.0) -> Texture:
|
|
"""Create a new texture with HSL color adjustments applied."""
|
|
...
|
|
|
|
class TileLayer:
|
|
"""A grid layer that stores sprite indices per cell for tile-based rendering."""
|
|
def __init__(self, z_index=-1, name=None, texture=None, grid_size=None) -> None: ...
|
|
grid: Grid | None # Parent Grid or None (Grid | None). Setting manages layer association and handles lazy allocation.
|
|
grid_size: tuple # Layer dimensions as (width, height) tuple (tuple, read-only).
|
|
name: str # Layer name (str, read-only). Used for Grid.layer(name) lookup.
|
|
texture: Texture | None # Texture atlas for tile sprites (Texture | None).
|
|
visible: bool # Whether the layer is rendered (bool).
|
|
z_index: int # Layer z-order (int). Negative values render below entities.
|
|
def apply_ranges(self, source: HeightMap, ranges: list) -> TileLayer:
|
|
"""Apply multiple tile assignments from a HeightMap in a single pass. Later ranges override earlier ones if overlapping."""
|
|
...
|
|
def apply_threshold(self, source: HeightMap, range: tuple, tile: int) -> TileLayer:
|
|
"""Set a tile index for cells where the HeightMap value falls within a range."""
|
|
...
|
|
def at(self, *args, **kwargs) -> Any:
|
|
"""at(pos: tuple | Vector) or (x: int, y: int) -> int"""
|
|
...
|
|
def fill(self, index: int) -> None:
|
|
"""Fill the entire layer with the specified tile index."""
|
|
...
|
|
def fill_rect(self, pos: tuple, size: tuple, index: int) -> None:
|
|
"""Fill a rectangular region with a tile index."""
|
|
...
|
|
def set(self, pos, index: int) -> None:
|
|
"""Set the tile index at a cell position. Use -1 to clear the tile."""
|
|
...
|
|
|
|
class TileMapFile:
|
|
"""Load a Tiled map file (.tmx or .tmj)."""
|
|
def __init__(self, path: str) -> None: ...
|
|
height: int # Map height in tiles (int, read-only).
|
|
object_layer_names: Any # List of object layer names (read-only).
|
|
orientation: str # Map orientation, e.g. 'orthogonal' (str, read-only).
|
|
properties: Any # Custom map properties as a dict (read-only).
|
|
tile_height: int # Tile height in pixels (int, read-only).
|
|
tile_layer_names: Any # List of tile layer names (read-only).
|
|
tile_width: int # Tile width in pixels (int, read-only).
|
|
tileset_count: int # Number of referenced tilesets (int, read-only).
|
|
width: int # Map width in tiles (int, read-only).
|
|
def apply_to_tile_layer(self, tile_layer: TileLayer, layer_name: str, tileset_index: int = 0) -> None:
|
|
"""Resolve GIDs and write sprite indices into a TileLayer."""
|
|
...
|
|
def object_layer(self, name: str) -> list[dict]:
|
|
"""Get objects from an object layer as Python dicts."""
|
|
...
|
|
def resolve_gid(self, gid: int) -> tuple[int, int]:
|
|
"""Resolve a global tile ID to tileset index and local tile ID."""
|
|
...
|
|
def tile_layer_data(self, name: str) -> list[int]:
|
|
"""Get raw global GID data for a tile layer."""
|
|
...
|
|
def tileset(self, index: int) -> tuple[int, TileSetFile]:
|
|
"""Get a referenced tileset by index."""
|
|
...
|
|
|
|
class TileSetFile:
|
|
"""Load a Tiled tileset file (.tsx or .tsj)."""
|
|
def __init__(self, path: str) -> None: ...
|
|
columns: int # Number of columns in tileset image (int, read-only).
|
|
image_source: str # Resolved path to the tileset image file (str, read-only).
|
|
margin: int # Margin around tiles in pixels (int, read-only).
|
|
name: str # Tileset name (str, read-only).
|
|
properties: Any # Custom tileset properties as a dict (read-only).
|
|
spacing: int # Spacing between tiles in pixels (int, read-only).
|
|
tile_count: int # Total number of tiles (int, read-only).
|
|
tile_height: int # Height of each tile in pixels (int, read-only).
|
|
tile_width: int # Width of each tile in pixels (int, read-only).
|
|
wang_sets: Any # List of WangSet objects from this tileset (read-only).
|
|
def tile_info(self, tile_id: int) -> dict | None:
|
|
"""Get metadata for a specific tile."""
|
|
...
|
|
def to_texture(self) -> Texture:
|
|
"""Create a Texture from the tileset image."""
|
|
...
|
|
def wang_set(self, name: str) -> WangSet:
|
|
"""Look up a WangSet by name."""
|
|
...
|
|
|
|
class Timer:
|
|
"""Create a timer that calls a function at regular intervals."""
|
|
def __init__(self, name, callback, interval, once=False, start=True) -> None: ...
|
|
active: bool # Running state (bool, read-write). True if running (not paused, not stopped). Set True to start/resume, False to pause.
|
|
callback: Callable # The callback function (callable). Preserved when stopped, allowing timer restart.
|
|
interval: int # Timer interval in milliseconds (int). Must be positive. Can be changed while timer is running.
|
|
name: str # Timer name (str, read-only). Unique identifier for this timer.
|
|
once: bool # Whether the timer stops after firing once (bool). One-shot timers can be restarted.
|
|
paused: bool # Whether the timer is paused (bool, read-only). Paused timers preserve their remaining time.
|
|
remaining: int # Time remaining until next trigger in milliseconds (int, read-only). Full interval when stopped.
|
|
stopped: bool # Whether the timer is stopped (bool, read-only). Stopped timers are not in the engine tick loop but preserve their callback.
|
|
def pause(self) -> None:
|
|
"""Pause the timer, preserving the time remaining until next trigger."""
|
|
...
|
|
def restart(self) -> None:
|
|
"""Restart the timer from the beginning and ensure it's running."""
|
|
...
|
|
def resume(self) -> None:
|
|
"""Resume a paused timer from where it left off."""
|
|
...
|
|
def start(self) -> None:
|
|
"""Start the timer, adding it to the engine tick loop."""
|
|
...
|
|
def stop(self) -> None:
|
|
"""Stop the timer and remove it from the engine tick loop."""
|
|
...
|
|
|
|
class Vector:
|
|
"""2D vector for positions, sizes, and directions."""
|
|
def __init__(self, x: float = 0, y: float = 0) -> None: ...
|
|
int: Any # Integer tuple (floor of x and y) for use as dict keys. Read-only.
|
|
x: float # X coordinate of the vector (float)
|
|
y: float # Y coordinate of the vector (float)
|
|
def angle(self) -> float:
|
|
"""Get the angle of this vector in radians."""
|
|
...
|
|
def copy(self) -> Vector:
|
|
"""Create a copy of this vector."""
|
|
...
|
|
def distance_to(self, other: Vector) -> float:
|
|
"""Calculate the distance to another vector."""
|
|
...
|
|
def dot(self, other: Vector) -> float:
|
|
"""Calculate the dot product with another vector."""
|
|
...
|
|
def floor(self) -> Vector:
|
|
"""Return a new vector with floored (integer) coordinates."""
|
|
...
|
|
def magnitude(self) -> float:
|
|
"""Calculate the length/magnitude of this vector."""
|
|
...
|
|
def magnitude_squared(self) -> float:
|
|
"""Calculate the squared magnitude of this vector."""
|
|
...
|
|
def normalize(self) -> Vector:
|
|
"""Return a unit vector in the same direction."""
|
|
...
|
|
|
|
class Viewport3D:
|
|
"""A 3D rendering viewport that displays a 3D scene as a UI element."""
|
|
def __init__(self, pos=None, size=None, **kwargs) -> None: ...
|
|
bg_color: Any # Background clear color.
|
|
bounds: tuple # Axis-aligned bounding box (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
camera_pos: Any # Camera position as (x, y, z) tuple.
|
|
camera_target: Any # Camera look-at target as (x, y, z) tuple.
|
|
cell_size: Any # World units per navigation grid cell.
|
|
enable_affine: Any # Enable PS1-style affine texture mapping (warped textures).
|
|
enable_dither: Any # Enable PS1-style color dithering.
|
|
enable_fog: Any # Enable distance fog.
|
|
enable_vertex_snap: Any # Enable PS1-style vertex snapping (jittery vertices).
|
|
entities: Any # Collection of Entity3D objects (read-only). Use append/remove to modify.
|
|
fog_color: Any # Fog color.
|
|
fog_far: Any # Fog end distance.
|
|
fog_near: Any # Fog start distance.
|
|
fov: Any # Camera field of view in degrees.
|
|
global_bounds: tuple # Axis-aligned bounding box in screen coordinates (tuple, read-only) as a (pos, size) pair of Vectors: (Vector(x, y), Vector(width, height)).
|
|
global_position: Any # Global screen position (read-only). Calculates absolute position by walking up the parent chain.
|
|
grid_size: Any # Navigation grid dimensions as (width, depth) tuple.
|
|
h: Any # Display height in pixels.
|
|
hovered: Any # Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
|
|
on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: MouseButton, action: InputState).
|
|
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector) when mouse enters this element's bounds.
|
|
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector) when mouse leaves this element's bounds.
|
|
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector) for each mouse movement while inside. Performance note: Called frequently during movemen...
|
|
opacity: Any # Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
|
|
parent: Any # Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
|
|
pos: Any # Position as Vector (x, y).
|
|
render_resolution: Any # Internal render resolution (width, height). Lower values for PS1 effect.
|
|
visible: bool # Whether the object is visible (bool). Invisible objects are not rendered or clickable.
|
|
w: Any # Display width in pixels.
|
|
x: Any # X position in pixels.
|
|
y: Any # Y position in pixels.
|
|
z_index: Any # Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
|
|
def add_billboard(self, billboard) -> Any:
|
|
"""Add a Billboard to the viewport."""
|
|
...
|
|
def add_layer(self, name, z_index=0) -> dict:
|
|
"""Add a new mesh layer to the viewport."""
|
|
...
|
|
def add_mesh(self, layer_name, model, pos, rotation=0, scale=1.0) -> int:
|
|
"""Add a Model3D instance to a layer at the specified position."""
|
|
...
|
|
def add_voxel_layer(self, voxel_grid, z_index=0) -> Any:
|
|
"""Add a VoxelGrid as a renderable layer."""
|
|
...
|
|
def animate(self, property: str, target: Any, duration: float, easing=None, delta=False, loop=False, callback=None, conflict_mode='replace') -> Animation:
|
|
"""Create and start an animation on this drawable's property."""
|
|
...
|
|
def apply_heightmap(self, heightmap, y_scale=1.0) -> Any:
|
|
"""Set cell heights from HeightMap."""
|
|
...
|
|
def apply_terrain_colors(self, layer_name, r_map, g_map, b_map) -> Any:
|
|
"""Apply per-vertex colors to terrain from RGB HeightMaps."""
|
|
...
|
|
def apply_threshold(self, heightmap, min_height, max_height, walkable=True) -> Any:
|
|
"""Set cell walkability based on height thresholds."""
|
|
...
|
|
def at(self, x, z) -> VoxelPoint:
|
|
"""Get VoxelPoint at grid coordinates."""
|
|
...
|
|
def billboard_count(self) -> int:
|
|
"""Get the number of billboards."""
|
|
...
|
|
def build_terrain(self, layer_name, heightmap, y_scale=1.0, cell_size=1.0) -> int:
|
|
"""Build terrain mesh from HeightMap on specified layer."""
|
|
...
|
|
def clear_billboards(self) -> Any:
|
|
"""Remove all billboards from the viewport."""
|
|
...
|
|
def clear_meshes(self, layer_name) -> Any:
|
|
"""Clear all mesh instances from a layer."""
|
|
...
|
|
def clear_voxel_nav_region(self, voxel_grid) -> Any:
|
|
"""Clear navigation cells in a voxel grid's footprint."""
|
|
...
|
|
def compute_fov(self, origin, radius=10) -> list:
|
|
"""Compute field of view from a position."""
|
|
...
|
|
def find_path(self, start, end) -> list:
|
|
"""Find A* path between two points."""
|
|
...
|
|
def follow(self, entity, distance=10, height=5, smoothing=1.0) -> Any:
|
|
"""Position camera to follow an entity."""
|
|
...
|
|
def get_billboard(self, index) -> Billboard:
|
|
"""Get a Billboard by index."""
|
|
...
|
|
def get_layer(self, name) -> dict or None:
|
|
"""Get a layer by name."""
|
|
...
|
|
def is_in_fov(self, x, z) -> bool:
|
|
"""Check if a cell is in the current FOV (after compute_fov)."""
|
|
...
|
|
def layer_count(self) -> int:
|
|
"""Get the number of mesh layers."""
|
|
...
|
|
def move(self, *args, **kwargs) -> Any:
|
|
"""move(dx, dy) or (delta) -> None"""
|
|
...
|
|
def orbit_camera(self, angle=0, distance=10, height=5) -> Any:
|
|
"""Position camera to orbit around origin."""
|
|
...
|
|
def place_blocking(self, grid_pos, footprint, walkable=False, transparent=False) -> Any:
|
|
"""Mark grid cells as blocking for pathfinding and FOV."""
|
|
...
|
|
def project_all_voxels_to_nav(self, headroom=2) -> Any:
|
|
"""Project all voxel layers to the navigation grid."""
|
|
...
|
|
def project_voxel_to_nav(self, voxel_grid, headroom=2) -> Any:
|
|
"""Project a VoxelGrid to the navigation grid."""
|
|
...
|
|
def realign(self) -> None:
|
|
"""Reapply alignment relative to parent, useful for responsive layouts."""
|
|
...
|
|
def remove_billboard(self, billboard) -> Any:
|
|
"""Remove a Billboard from the viewport."""
|
|
...
|
|
def remove_layer(self, name) -> bool:
|
|
"""Remove a layer by name. Returns True if found and removed."""
|
|
...
|
|
def remove_voxel_layer(self, voxel_grid) -> bool:
|
|
"""Remove a VoxelGrid layer from the viewport."""
|
|
...
|
|
def resize(self, *args, **kwargs) -> Any:
|
|
"""resize(width, height) or (size) -> None"""
|
|
...
|
|
def screen_to_world(self, x, y, y_plane=0.0) -> tuple or None:
|
|
"""Convert screen coordinates to world position via ray casting."""
|
|
...
|
|
def set_grid_size(self, width, depth) -> Any:
|
|
"""Initialize navigation grid with specified dimensions."""
|
|
...
|
|
def set_slope_cost(self, max_slope=0.5, cost_multiplier=1.0) -> Any:
|
|
"""Calculate slope costs and mark steep cells unwalkable."""
|
|
...
|
|
def voxel_layer_count(self) -> int:
|
|
"""Get the number of voxel layers."""
|
|
...
|
|
|
|
class VoxelGrid:
|
|
"""A dense 3D grid of voxel material IDs with a material palette."""
|
|
def __init__(self, size: tuple[int, int, int], cell_size: float = 1.0) -> None: ...
|
|
cell_size: Any # World units per voxel. Read-only.
|
|
depth: Any # Grid depth (Z dimension). Read-only.
|
|
greedy_meshing: Any # Enable greedy meshing optimization (reduces vertex count for uniform regions).
|
|
height: Any # Grid height (Y dimension). Read-only.
|
|
material_count: Any # Number of materials in the palette. Read-only.
|
|
offset: Any # World-space position (x, y, z) of the grid origin.
|
|
rotation: Any # Y-axis rotation in degrees.
|
|
size: Any # Dimensions (width, height, depth) of the grid. Read-only.
|
|
vertex_count: Any # Number of vertices after mesh generation. Read-only.
|
|
visible: Any # Show or hide this voxel grid in rendering.
|
|
width: Any # Grid width (X dimension). Read-only.
|
|
def add_material(self, name, color=Color(255, 255, 255), sprite_index=-1, transparent=False, path_cost=1.0) -> int:
|
|
"""Add a new material to the palette. Returns the material ID (1-indexed)."""
|
|
...
|
|
def clear(self) -> None:
|
|
"""Clear the grid (fill with air, material 0)."""
|
|
...
|
|
def copy_region(self, min_coord, max_coord) -> VoxelRegion:
|
|
"""Copy a rectangular region to a VoxelRegion prefab."""
|
|
...
|
|
def count_material(self, material) -> int:
|
|
"""Count the number of voxels with the specified material ID."""
|
|
...
|
|
def count_non_air(self) -> int:
|
|
"""Count the number of non-air voxels in the grid."""
|
|
...
|
|
def fill(self, material) -> None:
|
|
"""Fill the entire grid with the specified material ID."""
|
|
...
|
|
def fill_box(self, min_coord, max_coord, material) -> None:
|
|
"""Fill a rectangular region with the specified material."""
|
|
...
|
|
def fill_box_hollow(self, min_coord, max_coord, material, thickness=1) -> None:
|
|
"""Create a hollow rectangular room (walls only, hollow inside)."""
|
|
...
|
|
def fill_cylinder(self, base_pos, radius, height, material) -> None:
|
|
"""Fill a vertical cylinder (Y-axis aligned)."""
|
|
...
|
|
def fill_noise(self, min_coord, max_coord, material, threshold=0.5, scale=0.1, seed=0) -> None:
|
|
"""Fill region with 3D noise-based pattern (caves, clouds)."""
|
|
...
|
|
def fill_sphere(self, center, radius, material) -> None:
|
|
"""Fill a spherical region."""
|
|
...
|
|
def from_bytes(self, data) -> bool:
|
|
"""Load voxel data from a bytes object."""
|
|
...
|
|
def get(self, x, y, z) -> int:
|
|
"""Get the material ID at integer coordinates."""
|
|
...
|
|
def get_material(self, id) -> dict:
|
|
"""Get material properties by ID."""
|
|
...
|
|
def load(self, path) -> bool:
|
|
"""Load voxel data from a binary file."""
|
|
...
|
|
def paste_region(self, region, position, skip_air=True) -> None:
|
|
"""Paste a VoxelRegion prefab at the specified position."""
|
|
...
|
|
def project_column(self, x, z, headroom=2) -> dict:
|
|
"""Project a single column to navigation info."""
|
|
...
|
|
def rebuild_mesh(self) -> None:
|
|
"""Force immediate mesh rebuild for rendering."""
|
|
...
|
|
def save(self, path) -> bool:
|
|
"""Save the voxel grid to a binary file."""
|
|
...
|
|
def set(self, x, y, z, material) -> None:
|
|
"""Set the material ID at integer coordinates."""
|
|
...
|
|
def to_bytes(self) -> bytes:
|
|
"""Serialize the voxel grid to a bytes object."""
|
|
...
|
|
|
|
class VoxelRegion:
|
|
"""VoxelRegion - Portable voxel data for copy/paste operations."""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
depth: Any # Region depth. Read-only.
|
|
height: Any # Region height. Read-only.
|
|
size: Any # Dimensions (width, height, depth) of the region. Read-only.
|
|
width: Any # Region width. Read-only.
|
|
|
|
class WangSet:
|
|
"""WangSet - Wang terrain auto-tile set from a Tiled tileset."""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
color_count: int # Number of terrain colors (int, read-only).
|
|
colors: Any # List of color dicts with name, index, tile_id, probability (read-only).
|
|
name: str # Wang set name (str, read-only).
|
|
type: str # Wang set type: 'corner', 'edge', or 'mixed' (str, read-only).
|
|
def apply(self, discrete_map: DiscreteMap, tile_layer: TileLayer) -> None:
|
|
"""Resolve terrain and write tile indices directly into a TileLayer."""
|
|
...
|
|
def resolve(self, discrete_map: DiscreteMap) -> list[int]:
|
|
"""Resolve terrain data to tile indices using Wang tile rules."""
|
|
...
|
|
def terrain_enum(self) -> IntEnum:
|
|
"""Generate a Python IntEnum from this WangSet's terrain colors."""
|
|
...
|
|
|
|
class Window:
|
|
"""Window singleton for accessing and modifying the game window properties"""
|
|
def __init__(self, *args, **kwargs) -> None: ...
|
|
framerate_limit: int # Frame rate limit in FPS (int, 0 for unlimited). Caps maximum frame rate.
|
|
fullscreen: bool # Window fullscreen state (bool). Setting this recreates the window.
|
|
game_resolution: Any # Fixed game resolution as (width, height) tuple. Enables resolution-independent rendering with scaling.
|
|
resolution: Any # Window resolution as (width, height) tuple. Setting this recreates the window.
|
|
scaling_mode: str # Viewport scaling mode (str): 'center' (no scaling), 'stretch' (fill window), or 'fit' (maintain aspect ratio).
|
|
title: str # Window title string (str). Displayed in the window title bar.
|
|
visible: bool # Window visibility state (bool). Hidden windows still process events.
|
|
vsync: bool # Vertical sync enabled state (bool). Prevents screen tearing but may limit framerate.
|
|
def center(self) -> None:
|
|
"""Center the window on the screen."""
|
|
...
|
|
def get(self) -> Window:
|
|
"""Get the Window singleton instance."""
|
|
...
|
|
def screenshot(self, filename: str = None) -> bytes | None:
|
|
"""Take a screenshot of the current window contents."""
|
|
...
|
|
|
|
# --- Submodules ---------------------------------------------------------
|
|
class _automation_module:
|
|
"""Stub for mcrfpy.automation submodule."""
|
|
@staticmethod
|
|
def click(pos: tuple | list | Vector | None = None, clicks: int = 1, interval: float = 0.0, button: str = 'left') -> None:
|
|
"""Click the mouse at the specified position."""
|
|
...
|
|
@staticmethod
|
|
def doubleClick(pos: tuple | list | Vector | None = None) -> None:
|
|
"""Double-click the mouse at the specified position."""
|
|
...
|
|
@staticmethod
|
|
def dragRel(offset: tuple | list | Vector, duration: float = 0.0, button: str = 'left') -> None:
|
|
"""Drag the mouse relative to its current position."""
|
|
...
|
|
@staticmethod
|
|
def dragTo(pos: tuple | list | Vector, duration: float = 0.0, button: str = 'left') -> None:
|
|
"""Drag the mouse from the current position to the specified position."""
|
|
...
|
|
@staticmethod
|
|
def hotkey(*keys: str) -> None:
|
|
"""Press a hotkey combination by pressing all keys in order then releasing in reverse."""
|
|
...
|
|
@staticmethod
|
|
def keyDown(key: str) -> None:
|
|
"""Press and hold a keyboard key."""
|
|
...
|
|
@staticmethod
|
|
def keyUp(key: str) -> None:
|
|
"""Release a keyboard key."""
|
|
...
|
|
@staticmethod
|
|
def middleClick(pos: tuple | list | Vector | None = None) -> None:
|
|
"""Middle-click the mouse at the specified position."""
|
|
...
|
|
@staticmethod
|
|
def mouseDown(pos: tuple | list | Vector | None = None, button: str = 'left') -> None:
|
|
"""Press and hold a mouse button at the specified position."""
|
|
...
|
|
@staticmethod
|
|
def mouseUp(pos: tuple | list | Vector | None = None, button: str = 'left') -> None:
|
|
"""Release a mouse button at the specified position."""
|
|
...
|
|
@staticmethod
|
|
def moveRel(offset: tuple | list | Vector, duration: float = 0.0) -> None:
|
|
"""Move the mouse cursor relative to its current position."""
|
|
...
|
|
@staticmethod
|
|
def moveTo(pos: tuple | list | Vector, duration: float = 0.0) -> None:
|
|
"""Move the mouse cursor to the specified position."""
|
|
...
|
|
@staticmethod
|
|
def onScreen(self, *args, **kwargs) -> Any:
|
|
"""onScreen(x: int, y: int) or (pos: tuple | list | Vector) -> bool"""
|
|
...
|
|
@staticmethod
|
|
def position() -> Vector:
|
|
"""Get the current mouse position as a Vector."""
|
|
...
|
|
@staticmethod
|
|
def rightClick(pos: tuple | list | Vector | None = None) -> None:
|
|
"""Right-click the mouse at the specified position."""
|
|
...
|
|
@staticmethod
|
|
def screenshot(filename: str) -> bool:
|
|
"""Save a screenshot of the current render target to the specified file."""
|
|
...
|
|
@staticmethod
|
|
def scroll(clicks: int, pos: tuple | list | Vector | None = None) -> None:
|
|
"""Scroll the mouse wheel at the specified position."""
|
|
...
|
|
@staticmethod
|
|
def size() -> Vector:
|
|
"""Get the current screen (render target) size as a Vector."""
|
|
...
|
|
@staticmethod
|
|
def tripleClick(pos: tuple | list | Vector | None = None) -> None:
|
|
"""Triple-click the mouse at the specified position."""
|
|
...
|
|
@staticmethod
|
|
def typewrite(message: str, interval: float = 0.0) -> None:
|
|
"""Type text by injecting keyboard events for each character."""
|
|
...
|
|
automation: _automation_module
|
|
|
|
# --- Module-level functions ---------------------------------------------
|
|
def bresenham(start, end, include_start=True, include_end=True) -> list[tuple[int, int]]:
|
|
"""Compute grid cells along a line using Bresenham's algorithm."""
|
|
...
|
|
def end_benchmark() -> str:
|
|
"""Stop benchmark capture and write data to JSON file."""
|
|
...
|
|
def exit() -> None:
|
|
"""Cleanly shut down the game engine and exit the application."""
|
|
...
|
|
def find(name: str, scene: str = None) -> UIDrawable | None:
|
|
"""Find the first UI element with the specified name."""
|
|
...
|
|
def find_all(pattern: str, scene: str = None) -> list:
|
|
"""Find all UI elements matching a name pattern."""
|
|
...
|
|
def get_metrics() -> dict:
|
|
"""Get current performance metrics."""
|
|
...
|
|
def lock() -> _LockContext:
|
|
"""Get a context manager for thread-safe UI updates from background threads."""
|
|
...
|
|
def log_benchmark(message: str) -> None:
|
|
"""Add a log message to the current benchmark frame."""
|
|
...
|
|
def set_dev_console(enabled: bool) -> None:
|
|
"""Enable or disable the developer console overlay."""
|
|
...
|
|
def set_scale(multiplier: float) -> None:
|
|
"""Deprecated: use Window.resolution instead. Scale the game window size."""
|
|
...
|
|
def start_benchmark() -> None:
|
|
"""Start capturing benchmark data to a file."""
|
|
...
|
|
def step(dt: float = None) -> float:
|
|
"""Advance simulation time (headless mode only)."""
|
|
...
|
|
|
|
# --- Module-level constants ---------------------------------------------
|
|
default_font: Font
|
|
default_fov: FOV
|
|
default_texture: Texture
|
|
keyboard: Keyboard
|
|
mouse: Mouse
|
|
window: Window
|