john/McRogueFace
1
0
Fork 0
Code Issues 26 Pull requests Projects Releases Wiki Activity
McRogueFace/stubs/mcrfpy.pyi
John McCardle 2d2c333cd7 Refactor UIEntity::grid to shared_ptr<GridData>; add entity.texture; closes #313 
UIEntity now depends on the grid DATA layer only:
- GridData gains cell_width_px/cell_height_px (mirrored from the grid
  texture in UIGrid's 5-arg ctor; texture is write-once) so entity
  tile<->pixel math no longer reaches into rendering (getTexture()).
- GridData gains markDirty()/markCompositeDirty(): set the flag on the
  UIGrid subobject AND notify owning_view, covering both render paths.
  UIGrid disambiguates via 'using UIDrawable::markDirty' so all
  pre-existing UIGrid-receiver calls resolve exactly as before.
- The three Python wrappers that still need the full UIGrid (GridPoint
  from entity.at(), the _GridData fallback in get_grid, find_path's temp
  wrapper) reconstruct it via a single aliasing-downcast helper
  (grid_as_uigrid) that documents the never-independently-allocated
  GridData invariant; init/set_grid simplify (share grid_data directly).
  Removing the casts is deferred to #252.

entity.texture (new, frozen surface +1): thin get/set over the entity's
own UISprite. Entities render with their OWN texture (default_texture
fallback at construction); the grid's texture only determines cell size.
Setter preserves sprite_index; rejects non-Texture (TypeError),
null-data Texture wrappers (ValueError), and deletion.

Adversarial review fixes folded in:
- set_texture/get_texture guard uninitialized Entity wrappers
  (RuntimeError), isinstance errors, and null-data Textures.
- PyUIGridViewType tp_dealloc no longer unconditionally severs
  GridData::owning_view: gated on last-owner (#251 use_count pattern)
  plus owning-view identity. Previously ANY Grid wrapper GC while the
  view lived (e.g. scene.children.append(mcrfpy.Grid(...))) silently
  broke entity.grid -> Grid identity and data-layer dirty notification.

Tests: tests/regression/issue_313_entity_grid_data_test.py (texture
semantics, grid-cell-size invariance, entity.grid identity, #251 gate
survival, GridPoint outliving teardown, review-fix guards, owning_view
survival) + tests/unit/entity_texture_test.py. API snapshot golden
re-baselined: exactly +1 surface line (Entity.texture) + writability
probe flip. Docs/stubs regenerated. Native + Emscripten builds verified.

Known edges recorded in docs/api-audit-2026-04.md: texture read-back is
a fresh wrapper each get (no Texture __eq__); sprite_index not
re-validated against a new atlas. Multi-view markDirty broadcast and
pure-GridData wrappers remain deferred to #252. Addresses #314.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-06-11 00:51:22 -04:00

2056 lines
113 KiB
Python
Raw Blame History

"""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 next step without consuming it."""
...
def walk(self) -> Vector:
"""Get and consume 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: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
center: Any # Center position of the arc
color: Any # Arc color
end_angle: Any # Ending angle in degrees
global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (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: Any # Position in grid tile coordinates (only when parent is Grid)
grid_size: Any # Size in grid tile coordinates (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 arc is clicked. Function receives (pos: Vector, button: str, action: str).
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
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: Any # Arc radius in pixels
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: Any # Starting angle in degrees
thickness: Any # Line thickness
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 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]) -> 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) -> 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, 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: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
fill_color: Any # Fill color of the text. Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
font_size: Any # Font size (integer) in points
global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (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: Any # Position in grid tile coordinates (only when parent is Grid)
grid_size: Any # Size in grid tile coordinates (only when parent is Grid)
h: Any # Text height in pixels (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: Any # Name for finding elements
on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
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: Any # Thickness of the border
outline_color: Any # Outline color of the text. 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 # (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: Any # The text displayed
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: Any # Text width in pixels (read-only)
x: Any # X coordinate of top-left corner
y: Any # Y coordinate of top-left corner
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: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
center: Any # Center position of the circle
fill_color: Any # Fill color of the circle
global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (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: Any # Position in grid tile coordinates (only when parent is Grid)
grid_size: Any # Size in grid tile coordinates (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 circle is clicked. Function receives (pos: Vector, button: str, action: str).
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
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: Any # Outline thickness (0 for no outline)
outline_color: Any # Outline color of the circle
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: Any # Circle radius in pixels
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: 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 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: Any # Parent Grid or None. Setting manages layer association and handles lazy allocation.
grid_size: Any # Layer dimensions as (width, height) tuple.
name: str # Layer name (str, read-only). Used for Grid.layer(name) lookup.
visible: Any # Whether the layer is rendered.
z_index: Any # Layer z-order. Negative values render below entities.
def apply_gradient(self, source, range, color_low, color_high) -> ColorLayer:
"""Interpolate between colors based on HeightMap value within range."""
...
def apply_perspective(self, entity, visible=None, discovered=None, unknown=None) -> Any:
"""Bind this layer to an entity for automatic FOV updates."""
...
def apply_ranges(self, source, ranges) -> ColorLayer:
"""Apply multiple color assignments in a single pass."""
...
def apply_threshold(self, source, range, color) -> ColorLayer:
"""Set fixed color for cells where HeightMap value is within range."""
...
def at(self, pos) -> Color:
"""at(x, y) -> Color"""
...
def clear_perspective(self) -> Any:
"""Remove the perspective binding from this layer."""
...
def draw_fov(self, source, radius=None, fov=None, visible=None, discovered=None, unknown=None) -> Any:
"""Paint cells based on field-of-view visibility from source position."""
...
def fill(self, color) -> Any:
"""Fill the entire layer with the specified color."""
...
def fill_rect(self, pos, size, color) -> Any:
"""Fill a rectangular region with a color."""
...
def set(self, pos, color) -> Any:
"""Set the color at cell position."""
...
def update_perspective(self) -> Any:
"""Redraw FOV based on the bound entity's current position."""
...
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 | None:
"""Get the adjacent cell with the lowest distance (steepest descent)."""
...
def distance(self, pos) -> float | None:
"""Get distance from position to root."""
...
def invert(self) -> DijkstraMap:
"""Return a NEW DijkstraMap whose distance field is the safety field."""
...
def path_from(self, pos) -> AStarPath:
"""Get full path from position to root."""
...
def step_from(self, pos) -> 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."""
...
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: str, action: str).
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: Any # Integer X cell coordinate. Alias for grid_x.
cell_y: Any # Integer Y cell coordinate. 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. Get: Returns the Grid or None. Set: Assign a Grid to move entity, or None to remove from grid.
grid_pos: Vector # Integer logical cell position (Vector). Canonical cell-position property; matches the 'grid_pos' constructor argument. Decoupled from draw_pos. Determines wh...
grid_x: Any # Integer X cell coordinate. Canonical; matches grid_pos.
grid_y: Any # Integer Y cell coordinate. Canonical; matches grid_pos.
labels: frozenset # Set of string labels for collision/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: Any # Name for finding elements
opacity: Any # Opacity (0.0 = transparent, 1.0 = opaque)
perspective_map: DiscreteMap # Per-entity FOV memory (DiscreteMap, read-write). 3-state values per cell: 0 = unknown (never seen), 1 = discovered (seen before, not currently visible), 2 = ...
pos: Vector # Pixel position relative to grid (Vector). Computed as draw_pos * tile_size. Requires entity to be attached to a grid.
shader: Any # Shader for GPU visual effects (Shader or None). When set, the entity is rendered through the shader program. Set to None to disable shader effects.
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: Any # Sprite index on the texture on the display
sprite_offset: Vector # Pixel offset for oversized sprites (Vector). Applied pre-zoom during grid rendering.
sprite_offset_x: Any # X component of sprite pixel offset.
sprite_offset_y: Any # Y component of sprite pixel offset.
step: Any # Step callback for grid.step() turn management. Called with (trigger, data) when behavior triggers fire. Set to None to clear.
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 when the entity is constructed without one. Setting preserves sprite_index (the index is n...
tile_height: int # Entity height in tiles (int). Must be >= 1. Default 1.
tile_size: Any # 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: Any # Collection of shader uniforms (read-only access to collection). Set uniforms via dict-like syntax: entity.uniforms['name'] = value. Supports float, vec2/3/4 ...
visible: Any # Visibility flag
x: Any # Pixel X position relative to grid. Requires entity to be attached to a grid.
y: Any # Pixel Y position relative to grid. Requires entity to be attached to a grid.
def add_label(self, label: str) -> None:
"""Add a label to this entity. Idempotent (adding 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, *args, **kwargs) -> Any:
"""at(x, y) or at(pos) -> GridPoint | None"""
...
def die(self, *args, **kwargs) -> Any:
"""Remove this entity from its grid."""
...
def find_path(self, target, diagonal_cost=1.41, collide=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, *args, **kwargs) -> Any:
"""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, *args, **kwargs) -> Any:
"""path_to(x, y) or path_to(target) -> list"""
...
def remove_label(self, label: str) -> None:
"""Remove a label from this entity. No-op if label not present."""
...
def resize(self, *args, **kwargs) -> Any:
"""resize(width, height) or (size) -> None"""
...
def set_behavior(self, type, waypoints=None, turns=0, path=None) -> None:
"""Configure this entity's behavior for grid.step() turn management."""
...
def update_visibility(self) -> None:
"""Update entity's visibility state based on current FOV."""
...
def visible_entities(self, fov=None, radius=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: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
cache_subtree: Any # #144: Cache subtree rendering to texture for performance
children: Any # UICollection of objects on top of this one
clip_children: Any # Whether to clip children to frame bounds
fill_color: Any # Fill color of the rectangle. Returns a copy; modifying components requires reassignment. For animation, use 'fill_color.r', 'fill_color.g', etc.
global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (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: Any # Position in grid tile coordinates (only when parent is Grid)
grid_size: Any # Size in grid tile coordinates (only when parent is Grid)
h: Any # height of the rectangle
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 elements
on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
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: Any # Thickness of the border
outline_color: Any # Outline color of the rectangle. 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 a 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: Any # width of the rectangle
x: Any # X coordinate of top-left corner
y: Any # Y coordinate of top-left corner
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: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
camera_rotation: Any # Rotation of grid contents around camera center (degrees).
center: Any # Camera center point in pixel coordinates.
center_x: Any # center of the view X-coordinate
center_y: Any # center of the view Y-coordinate
children: Any # UICollection of UIDrawable children (speech bubbles, effects, overlays)
entities: Any # EntityCollection of entities on this grid
fill_color: Any # Background fill color.
fov: Any # FOV algorithm for this grid (mcrfpy.FOV enum). Used by entity.updateVisibility() and layer methods when fov=None.
fov_radius: Any # Default FOV radius for this grid. Used when radius not specified.
global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (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: Any # The underlying grid data object (for multi-view scenarios).
grid_h: Any # Grid height in cells
grid_pos: Any # Position in parent grid's tile coordinates (only when parent is Grid)
grid_size: Any # Grid dimensions (grid_w, grid_h)
grid_w: Any # Grid width in cells
h: Any # visible widget height
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: Any # Currently hovered cell as (x, y) tuple, or None if not hovering.
layers: ColorLayer # List of grid layers (ColorLayer, TileLayer) sorted by z_index
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 elements
on_cell_click: Any # Callback when a grid cell is clicked. Called with (cell_pos: Vector).
on_cell_enter: Any # Callback when mouse enters a grid cell. Called with (cell_pos: Vector).
on_cell_exit: Any # Callback when mouse exits a grid cell. Called with (cell_pos: Vector).
on_click: Any # Callable executed when object is clicked.
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
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: Any # Entity whose perspective to use for FOV rendering (None for omniscient view). Setting an entity automatically enables perspective mode.
perspective_enabled: Any # Whether to use perspective-based FOV rendering. When True with no valid entity, all cells appear undiscovered.
pos: Any # Position of the grid as 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 # Size of the grid as Vector (width, height)
texture: Any # Texture used for tile rendering (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: Any # Auto-created GridView for rendering (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: Any # visible widget width
x: Any # top-left corner X-coordinate
y: Any # top-left corner Y-coordinate
z_index: Any # Z-order for rendering (lower values rendered first).
zoom: Any # Zoom level for rendering.
def add_layer(self, layer: ColorLayer | TileLayer) -> ColorLayer | TileLayer:
"""Add a layer to 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 thresholds in a single pass."""
...
def apply_threshold(self, source: HeightMap, range: tuple, walkable: bool = None, transparent: bool = None) -> Grid:
"""Apply walkable/transparent properties where heightmap values are in range."""
...
def at(self, *args, **kwargs) -> Any: ...
def center_camera(self, pos: tuple = None) -> None:
"""Center the camera on a tile coordinate."""
...
def clear_dijkstra_maps(self) -> None:
"""Clear all cached Dijkstra maps."""
...
def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None:
"""Compute field of view from a position."""
...
def entities_in_radius(self, pos: tuple|Vector, radius: float) -> list[Entity]:
"""Query entities within radius using spatial hash (O(k) where k = nearby entities)."""
...
def find_path(self, start, end, diagonal_cost=1.41, collide=None) -> AStarPath | None:
"""Compute A* path between two points."""
...
def get_dijkstra_map(self, root, diagonal_cost=1.41, collide=None) -> DijkstraMap:
"""Get or create a Dijkstra distance map for a root position."""
...
def is_in_fov(self, pos) -> bool:
"""Check if a cell is in the field of view."""
...
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."""
...
def resize(self, *args, **kwargs) -> Any:
"""resize(width, height) or (size) -> None"""
...
def step(self, n=1, turn_order=None) -> None:
"""Execute n rounds of turn-based entity behavior."""
...
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: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
camera_rotation: Any # Rotation of grid contents around camera center (degrees).
center: Any # Camera center point in pixel coordinates.
center_x: Any # center of the view X-coordinate
center_y: Any # center of the view Y-coordinate
children: Any # UICollection of UIDrawable children (speech bubbles, effects, overlays)
entities: Any # EntityCollection of entities on this grid
fill_color: Any # Background fill color.
fov: Any # FOV algorithm for this grid (mcrfpy.FOV enum). Used by entity.updateVisibility() and layer methods when fov=None.
fov_radius: Any # Default FOV radius for this grid. Used when radius not specified.
global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (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: Any # The underlying grid data object (for multi-view scenarios).
grid_h: Any # Grid height in cells
grid_pos: Any # Position in parent grid's tile coordinates (only when parent is Grid)
grid_size: Any # Grid dimensions (grid_w, grid_h)
grid_w: Any # Grid width in cells
h: Any # visible widget height
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: Any # Currently hovered cell as (x, y) tuple, or None if not hovering.
layers: ColorLayer # List of grid layers (ColorLayer, TileLayer) sorted by z_index
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 elements
on_cell_click: Any # Callback when a grid cell is clicked. Called with (cell_pos: Vector).
on_cell_enter: Any # Callback when mouse enters a grid cell. Called with (cell_pos: Vector).
on_cell_exit: Any # Callback when mouse exits a grid cell. Called with (cell_pos: Vector).
on_click: Any # Callable executed when object is clicked.
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
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: Any # Entity whose perspective to use for FOV rendering (None for omniscient view). Setting an entity automatically enables perspective mode.
perspective_enabled: Any # Whether to use perspective-based FOV rendering. When True with no valid entity, all cells appear undiscovered.
pos: Any # Position of the grid as 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 # Size of the grid as Vector (width, height)
texture: Any # Texture used for tile rendering (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: Any # Auto-created GridView for rendering (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: Any # visible widget width
x: Any # top-left corner X-coordinate
y: Any # top-left corner Y-coordinate
z_index: Any # Z-order for rendering (lower values rendered first).
zoom: Any # Zoom level for rendering.
def add_layer(self, layer: ColorLayer | TileLayer) -> ColorLayer | TileLayer:
"""Add a layer to 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 thresholds in a single pass."""
...
def apply_threshold(self, source: HeightMap, range: tuple, walkable: bool = None, transparent: bool = None) -> Grid:
"""Apply walkable/transparent properties where heightmap values are in range."""
...
def at(self, *args, **kwargs) -> Any: ...
def center_camera(self, pos: tuple = None) -> None:
"""Center the camera on a tile coordinate."""
...
def clear_dijkstra_maps(self) -> None:
"""Clear all cached Dijkstra maps."""
...
def compute_fov(self, pos, radius: int = 0, light_walls: bool = True, algorithm: int = FOV_BASIC) -> None:
"""Compute field of view from a position."""
...
def entities_in_radius(self, pos: tuple|Vector, radius: float) -> list[Entity]:
"""Query entities within radius using spatial hash (O(k) where k = nearby entities)."""
...
def find_path(self, start, end, diagonal_cost=1.41, collide=None) -> AStarPath | None:
"""Compute A* path between two points."""
...
def get_dijkstra_map(self, root, diagonal_cost=1.41, collide=None) -> DijkstraMap:
"""Get or create a Dijkstra distance map for a root position."""
...
def is_in_fov(self, pos) -> bool:
"""Check if a cell is in the field of view."""
...
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."""
...
def resize(self, *args, **kwargs) -> Any:
"""resize(width, height) or (size) -> None"""
...
def step(self, n=1, turn_order=None) -> None:
"""Execute n rounds of turn-based entity behavior."""
...
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: Any # Bounding box as (pos, size) tuple of Vectors. Returns (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: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (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: Any # Position in grid tile coordinates (only when parent is Grid)
grid_size: Any # Size in grid tile coordinates (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: str, action: str).
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
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: Any # Bounding box as (pos, size) tuple of Vectors. Returns (Vector(x, y), Vector(width, height)).
global_bounds: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (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: Any # Position in grid tile coordinates (only when parent is Grid)
grid_size: Any # Size in grid tile coordinates (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 elements
on_click: Any # Callable executed when object is clicked. Function receives (pos: Vector, button: str, action: str).
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
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
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: Any # Uniform size factor
scale_x: Any # Horizontal scale factor
scale_y: Any # Vertical scale factor
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: Any # Which sprite on the texture is shown
texture: Any # Texture object
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: Any # X coordinate of top-left corner
y: Any # Y coordinate of top-left corner
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: Any # Parent Grid or None. Setting manages layer association and handles lazy allocation.
grid_size: Any # Layer dimensions as (width, height) tuple.
name: str # Layer name (str, read-only). Used for Grid.layer(name) lookup.
texture: Any # Texture atlas for tile sprites.
visible: Any # Whether the layer is rendered.
z_index: Any # Layer z-order. Negative values render below entities.
def apply_ranges(self, source, ranges) -> TileLayer:
"""Apply multiple tile assignments in a single pass."""
...
def apply_threshold(self, source, range, tile) -> TileLayer:
"""Set tile index for cells where HeightMap value is within range."""
...
def at(self, pos) -> int:
"""at(x, y) -> int"""
...
def fill(self, index) -> Any:
"""Fill the entire layer with the specified tile index."""
...
def fill_rect(self, pos, size, index) -> Any:
"""Fill a rectangular region with a tile index."""
...
def set(self, pos, index) -> Any:
"""Set the tile index at cell position. Use -1 for no 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: Any # Bounding box as (pos, size) tuple of Vectors. Returns (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: Any # Bounding box as (pos, size) tuple of Vectors in screen coordinates. Returns (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: str, action: str).
on_enter: Any # Callback for mouse enter events. Called with (pos: Vector, button: str, action: str) when mouse enters this element's bounds.
on_exit: Any # Callback for mouse exit events. Called with (pos: Vector, button: str, action: str) when mouse leaves this element's bounds.
on_move: Any # Callback for mouse movement within bounds. Called with (pos: Vector, button: str, action: str) for each mouse movement while inside. Performance note: Called...
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(self, *args, **kwargs) -> Any:
"""click(pos=None, clicks=1, interval=0.0, button='left') - Click at position. Accepts (x,y) tuple, [x,y] list, Vector, or None for current position."""
...
@staticmethod
def doubleClick(self, *args, **kwargs) -> Any:
"""doubleClick(pos=None) - Double click at position. Accepts (x,y) tuple, [x,y] list, Vector, or None for current position."""
...
@staticmethod
def dragRel(self, *args, **kwargs) -> Any:
"""dragRel(offset, duration=0.0, button='left') - Drag mouse relative to current position. Accepts (x,y) tuple, [x,y] list, or Vector."""
...
@staticmethod
def dragTo(self, *args, **kwargs) -> Any:
"""dragTo(pos, duration=0.0, button='left') - Drag mouse to position. Accepts (x,y) tuple, [x,y] list, or Vector."""
...
@staticmethod
def hotkey(self, *args, **kwargs) -> Any:
"""hotkey(*keys) - Press a hotkey combination (e.g., hotkey('ctrl', 'c'))"""
...
@staticmethod
def keyDown(self, *args, **kwargs) -> Any:
"""keyDown(key) - Press and hold a key"""
...
@staticmethod
def keyUp(self, *args, **kwargs) -> Any:
"""keyUp(key) - Release a key"""
...
@staticmethod
def middleClick(self, *args, **kwargs) -> Any:
"""middleClick(pos=None) - Middle click at position. Accepts (x,y) tuple, [x,y] list, Vector, or None for current position."""
...
@staticmethod
def mouseDown(self, *args, **kwargs) -> Any:
"""mouseDown(pos=None, button='left') - Press mouse button at position. Accepts (x,y) tuple, [x,y] list, Vector, or None for current position."""
...
@staticmethod
def mouseUp(self, *args, **kwargs) -> Any:
"""mouseUp(pos=None, button='left') - Release mouse button at position. Accepts (x,y) tuple, [x,y] list, Vector, or None for current position."""
...
@staticmethod
def moveRel(self, *args, **kwargs) -> Any:
"""moveRel(offset, duration=0.0) - Move mouse relative to current position. Accepts (x,y) tuple, [x,y] list, or Vector."""
...
@staticmethod
def moveTo(self, *args, **kwargs) -> Any:
"""moveTo(pos, duration=0.0) - Move mouse to position. Accepts (x,y) tuple, [x,y] list, or Vector."""
...
@staticmethod
def onScreen(self, *args, **kwargs) -> Any:
"""onScreen(pos) - Check if position is within screen bounds. Accepts (x,y) tuple, [x,y] list, or Vector."""
...
@staticmethod
def position(self, *args, **kwargs) -> Any:
"""position() - Get current mouse position as Vector"""
...
@staticmethod
def rightClick(self, *args, **kwargs) -> Any:
"""rightClick(pos=None) - Right click at position. Accepts (x,y) tuple, [x,y] list, Vector, or None for current position."""
...
@staticmethod
def screenshot(self, *args, **kwargs) -> Any:
"""screenshot(filename) - Save a screenshot to the specified file"""
...
@staticmethod
def scroll(self, *args, **kwargs) -> Any:
"""scroll(clicks, pos=None) - Scroll wheel at position. Accepts (x,y) tuple, [x,y] list, Vector, or None for current position."""
...
@staticmethod
def size(self, *args, **kwargs) -> Any:
"""size() - Get screen size as Vector"""
...
@staticmethod
def tripleClick(self, *args, **kwargs) -> Any:
"""tripleClick(pos=None) - Triple click at position. Accepts (x,y) tuple, [x,y] list, Vector, or None for current position."""
...
@staticmethod
def typewrite(self, *args, **kwargs) -> Any:
"""typewrite(message, interval=0.0) - Type text with optional interval between keystrokes"""
...
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
Reference in a new issue View git blame Copy permalink