john/McRogueFace
1
0
Fork 0
Code Issues 27 Pull requests Projects Releases Wiki Activity

docs: Fix property extraction and add Scene documentation

Browse source 
Doc generator fixes (tools/generate_dynamic_docs.py):
- Add types.GetSetDescriptorType detection for C++ extension properties
- All 22 classes with properties now have documented Properties sections
- Read-only detection via "read-only" docstring convention

Scene class documentation (src/PySceneObject.h):
- Expanded tp_doc with constructor, properties, lifecycle callbacks
- Documents key advantage: on_key works on ANY scene
- Includes usage examples for basic and subclass patterns

CLAUDE.md additions:
- New section "Adding Documentation for New Python Types"
- Step-by-step guide for tp_doc, PyMethodDef, PyGetSetDef
- Documentation extraction details and troubleshooting

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
John McCardle 2025-12-29 19:48:21 -05:00
commit e64c5c147f
5 changed files with 835 additions and 5 deletions
Download patch file Download diff file Expand all files Collapse all files

119
CLAUDE.md
View file

@ -625,4 +625,123 @@ After modifying C++ inline documentation with MCRF_* macros:
5. **No drift**: Impossible for docs and code to disagree - they're the same file! 5. **No drift**: Impossible for docs and code to disagree - they're the same file!
The macro system ensures complete, consistent documentation across all Python bindings. The macro system ensures complete, consistent documentation across all Python bindings.
### Adding Documentation for New Python Types
When adding a new Python class/type to the engine, follow these steps to ensure it's properly documented:
#### 1. Class Docstring (tp_doc)
In the `PyTypeObject` definition (usually in the header file), set `tp_doc` with a comprehensive docstring:
```cpp
// In PyMyClass.h
.tp_doc = PyDoc_STR(
"MyClass(arg1: type, arg2: type)\n\n"
"Brief description of what this class does.\n\n"
"Args:\n"
" arg1: Description of first argument.\n"
" arg2: Description of second argument.\n\n"
"Properties:\n"
" prop1 (type, read-only): Description of property.\n"
" prop2 (type): Description of writable property.\n\n"
"Example:\n"
" obj = mcrfpy.MyClass('example', 42)\n"
" print(obj.prop1)\n"
),
```
#### 2. Method Documentation (PyMethodDef)
For each method in the `methods[]` array, use the MCRF_* macros:
```cpp
// In PyMyClass.cpp
PyMethodDef PyMyClass::methods[] = {
{"do_something", (PyCFunction)do_something, METH_VARARGS,
MCRF_METHOD(MyClass, do_something,
MCRF_SIG("(value: int)", "bool"),
MCRF_DESC("Does something with the value."),
MCRF_ARGS_START
MCRF_ARG("value", "The value to process")
MCRF_RETURNS("True if successful, False otherwise")
)},
{NULL} // Sentinel
};
```
#### 3. Property Documentation (PyGetSetDef)
For each property in the `getsetters[]` array, include a docstring:
```cpp
// In PyMyClass.cpp
PyGetSetDef PyMyClass::getsetters[] = {
{"property_name", (getter)get_property, (setter)set_property,
"Property description. Include (type, read-only) if not writable.",
NULL},
{NULL} // Sentinel
};
```
**Important for read-only properties:** Include "read-only" in the docstring so the doc generator detects it:
```cpp
{"name", (getter)get_name, NULL, // NULL setter = read-only
"Object name (str, read-only). Unique identifier.",
NULL},
```
#### 4. Register Type in Module
Ensure the type is properly registered in `McRFPy_API.cpp` and its methods/getsetters are assigned:
```cpp
// Set methods and getsetters before PyType_Ready
mcrfpydef::PyMyClassType.tp_methods = PyMyClass::methods;
mcrfpydef::PyMyClassType.tp_getset = PyMyClass::getsetters;
// Then call PyType_Ready and add to module
```
#### 5. Regenerate Documentation
After adding the new type, regenerate all docs:
```bash
make -j4 # Rebuild with new documentation
cd build
./mcrogueface --headless --exec ../tools/generate_dynamic_docs.py
cp docs/API_REFERENCE_DYNAMIC.md ../docs/
cp docs/api_reference_dynamic.html ../docs/
```
#### 6. Update Type Stubs (Optional)
For IDE support, update `stubs/mcrfpy.pyi` with the new class:
```python
class MyClass:
"""Brief description."""
def __init__(self, arg1: str, arg2: int) -> None: ...
@property
def prop1(self) -> str: ...
def do_something(self, value: int) -> bool: ...
```
### Documentation Extraction Details
The doc generator (`tools/generate_dynamic_docs.py`) uses Python introspection:
- **Classes**: Detected via `inspect.isclass()`, docstring from `cls.__doc__`
- **Methods**: Detected via `callable()` check on class attributes
- **Properties**: Detected via `types.GetSetDescriptorType` (C++ extension) or `property` (Python)
- **Read-only detection**: Checks if "read-only" appears in property docstring
If documentation isn't appearing, verify:
1. The type is exported to the `mcrfpy` module
2. Methods/getsetters arrays are properly assigned before `PyType_Ready()`
3. Docstrings don't contain null bytes or invalid UTF-8
---
- Close issues automatically in gitea by adding to the commit message "closes #X", where X is the issue number. This associates the issue closure with the specific commit, so granular commits are preferred. You should only use the MCP tool to close issues directly when discovering that the issue is already complete; when committing changes, always such "closes" (or the opposite, "reopens") references to related issues. If on a feature branch, the issue will be referenced by the commit, and when merged to master, the issue will be actually closed (or reopened). - Close issues automatically in gitea by adding to the commit message "closes #X", where X is the issue number. This associates the issue closure with the specific commit, so granular commits are preferred. You should only use the MCP tool to close issues directly when discovering that the issue is already complete; when committing changes, always such "closes" (or the opposite, "reopens") references to related issues. If on a feature branch, the issue will be referenced by the commit, and when merged to master, the issue will be actually closed (or reopened).

326
docs/API_REFERENCE_DYNAMIC.md
View file

@ -1,6 +1,6 @@
# McRogueFace API Reference # McRogueFace API Reference
*Generated on 2025-12-28 14:29:42* *Generated on 2025-12-29 14:24:58*
*This documentation was dynamically generated from the compiled module.* *This documentation was dynamically generated from the compiled module.*
@ -289,6 +289,13 @@ Note:
Animation object for animating UI properties Animation object for animating UI properties
**Properties:**
- `duration` *(read-only)*: Animation duration in seconds (float, read-only). Total time for the animation to complete.
- `elapsed` *(read-only)*: Elapsed time in seconds (float, read-only). Time since the animation started.
- `is_complete` *(read-only)*: Whether animation is complete (bool, read-only). True when elapsed >= duration or complete() was called.
- `is_delta` *(read-only)*: Whether animation uses delta mode (bool, read-only). In delta mode, the target value is added to the starting value.
- `property` *(read-only)*: Target property name (str, read-only). The property being animated (e.g., 'pos', 'opacity', 'sprite_index').
**Methods:** **Methods:**
#### `complete() -> None` #### `complete() -> None`
@ -376,6 +383,28 @@ Attributes:
name (str): Element name name (str): Element name
**Properties:**
- `bounds`: Bounding rectangle (x, y, width, height) in local coordinates.
- `center`: Center position of the arc
- `color`: Arc color
- `end_angle`: Ending angle in degrees
- `global_bounds`: Bounding rectangle (x, y, width, height) in screen coordinates.
- `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
- `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
- `name`: Name for finding this element.
- `on_click`: Callable executed when arc is clicked.
- `on_enter`: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.
- `on_exit`: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `parent`: 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`: Position as a Vector (same as center).
- `radius`: Arc radius in pixels
- `start_angle`: Starting angle in degrees
- `thickness`: Line thickness
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `z_index`: Z-order for rendering (lower values rendered first).
**Methods:** **Methods:**
#### `get_bounds() -> tuple` #### `get_bounds() -> tuple`
@ -447,6 +476,29 @@ Attributes:
name (str): Element name name (str): Element name
w, h (float): Read-only computed size based on text and font w, h (float): Read-only computed size based on text and font
**Properties:**
- `bounds`: Bounding rectangle (x, y, width, height) in local coordinates.
- `fill_color`: Fill color of the text
- `font_size`: Font size (integer) in points
- `global_bounds`: Bounding rectangle (x, y, width, height) in screen coordinates.
- `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
- `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
- `name`: Name for finding elements
- `on_click`: Callable executed when object is clicked. Function receives (x, y) coordinates of click.
- `on_enter`: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.
- `on_exit`: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `outline`: Thickness of the border
- `outline_color`: Outline color of the text
- `parent`: 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`: (x, y) vector
- `text`: The text displayed
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `x`: X coordinate of top-left corner
- `y`: Y coordinate of top-left corner
- `z_index`: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
**Methods:** **Methods:**
#### `get_bounds() -> tuple` #### `get_bounds() -> tuple`
@ -511,6 +563,27 @@ Attributes:
name (str): Element name name (str): Element name
**Properties:**
- `bounds`: Bounding rectangle (x, y, width, height) in local coordinates.
- `center`: Center position of the circle
- `fill_color`: Fill color of the circle
- `global_bounds`: Bounding rectangle (x, y, width, height) in screen coordinates.
- `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
- `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
- `name`: Name for finding this element.
- `on_click`: Callable executed when circle is clicked.
- `on_enter`: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.
- `on_exit`: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `outline`: Outline thickness (0 for no outline)
- `outline_color`: Outline color of the circle
- `parent`: 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`: Position as a Vector (same as center).
- `radius`: Circle radius in pixels
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `z_index`: Z-order for rendering (lower values rendered first).
**Methods:** **Methods:**
#### `get_bounds() -> tuple` #### `get_bounds() -> tuple`
@ -545,6 +618,12 @@ Note:
SFML Color Object SFML Color Object
**Properties:**
- `a`: Alpha component (0-255, where 0=transparent, 255=opaque). Automatically clamped to valid range.
- `b`: Blue component (0-255). Automatically clamped to valid range.
- `g`: Green component (0-255). Automatically clamped to valid range.
- `r`: Red component (0-255). Automatically clamped to valid range.
**Methods:** **Methods:**
#### `from_hex(hex_string: str) -> Color` #### `from_hex(hex_string: str) -> Color`
@ -600,6 +679,11 @@ Methods:
set(x, y, color): Set color at cell position set(x, y, color): Set color at cell position
fill(color): Fill entire layer with color fill(color): Fill entire layer with color
**Properties:**
- `grid_size`: Layer dimensions as (width, height) tuple.
- `visible`: Whether the layer is rendered.
- `z_index`: Layer z-order. Negative values render below entities.
**Methods:** **Methods:**
#### `apply_perspective(entity, visible=None, discovered=None, unknown=None)` #### `apply_perspective(entity, visible=None, discovered=None, unknown=None)`
@ -644,6 +728,12 @@ Call this after the entity moves to update the visibility layer.
Base class for all drawable UI elements Base class for all drawable UI elements
**Properties:**
- `on_click`: Callable executed when object is clicked. Function receives (x, y) coordinates of click.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `z_index`: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
**Methods:** **Methods:**
#### `get_bounds() -> tuple` #### `get_bounds() -> tuple`
@ -703,6 +793,19 @@ Attributes:
opacity (float): Opacity value opacity (float): Opacity value
name (str): Element name name (str): Element name
**Properties:**
- `draw_pos`: Entity position (graphically)
- `grid`: Grid this entity belongs to. Get: Returns the Grid or None. Set: Assign a Grid to move entity, or None to remove from grid.
- `gridstate`: Grid point states for the entity
- `name`: Name for finding elements
- `opacity`: Opacity (0.0 = transparent, 1.0 = opaque)
- `pos`: Entity position (integer grid coordinates)
- `sprite_index`: Sprite index on the texture on the display
- `sprite_number`: Sprite index (DEPRECATED: use sprite_index instead)
- `visible`: Visibility flag
- `x`: Entity x position
- `y`: Entity y position
**Methods:** **Methods:**
#### `at(...)` #### `at(...)`
@ -810,6 +913,12 @@ Remove first occurrence of entity. Raises ValueError if not found.
*Inherits from: IntEnum* *Inherits from: IntEnum*
**Properties:**
- `denominator`: the denominator of a rational number in lowest terms
- `imag`: the imaginary part of a complex number
- `numerator`: the numerator of a rational number in lowest terms
- `real`: the real part of a complex number
**Methods:** **Methods:**
#### `as_integer_ratio(...)` #### `as_integer_ratio(...)`
@ -887,6 +996,10 @@ Return an array of bytes representing an integer.
SFML Font Object SFML Font Object
**Properties:**
- `family` *(read-only)*: Font family name (str, read-only). Retrieved from font metadata.
- `source` *(read-only)*: Source filename path (str, read-only). The path used to load this font.
**Methods:** **Methods:**
### Frame ### Frame
@ -933,6 +1046,32 @@ Attributes:
clip_children (bool): Whether to clip children to frame bounds clip_children (bool): Whether to clip children to frame bounds
cache_subtree (bool): Cache subtree rendering to texture cache_subtree (bool): Cache subtree rendering to texture
**Properties:**
- `bounds`: Bounding rectangle (x, y, width, height) in local coordinates.
- `cache_subtree`: #144: Cache subtree rendering to texture for performance
- `children`: UICollection of objects on top of this one
- `clip_children`: Whether to clip children to frame bounds
- `fill_color`: Fill color of the rectangle
- `global_bounds`: Bounding rectangle (x, y, width, height) in screen coordinates.
- `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
- `h`: height of the rectangle
- `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
- `name`: Name for finding elements
- `on_click`: Callable executed when object is clicked. Function receives (x, y) coordinates of click.
- `on_enter`: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.
- `on_exit`: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `outline`: Thickness of the border
- `outline_color`: Outline color of the rectangle
- `parent`: 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`: Position as a Vector
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `w`: width of the rectangle
- `x`: X coordinate of top-left corner
- `y`: Y coordinate of top-left corner
- `z_index`: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
**Methods:** **Methods:**
#### `get_bounds() -> tuple` #### `get_bounds() -> tuple`
@ -1015,6 +1154,48 @@ Attributes:
z_index (int): Rendering order z_index (int): Rendering order
name (str): Element name name (str): Element name
**Properties:**
- `bounds`: Bounding rectangle (x, y, width, height) in local coordinates.
- `center`: Grid coordinate at the center of the Grid's view (pan)
- `center_x`: center of the view X-coordinate
- `center_y`: center of the view Y-coordinate
- `children`: UICollection of UIDrawable children (speech bubbles, effects, overlays)
- `entities`: EntityCollection of entities on this grid
- `fill_color`: Background fill color of the grid
- `fov`: FOV algorithm for this grid (mcrfpy.FOV enum). Used by entity.updateVisibility() and layer methods when fov=None.
- `fov_radius`: Default FOV radius for this grid. Used when radius not specified.
- `global_bounds`: Bounding rectangle (x, y, width, height) in screen coordinates.
- `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
- `grid_size`: Grid dimensions (grid_x, grid_y)
- `grid_x`: Grid x dimension
- `grid_y`: Grid y dimension
- `h`: visible widget height
- `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
- `hovered_cell`: Currently hovered cell as (x, y) tuple, or None if not hovering.
- `layers`: List of grid layers (ColorLayer, TileLayer) sorted by z_index
- `name`: Name for finding elements
- `on_cell_click`: Callback when a grid cell is clicked. Called with (cell_x, cell_y).
- `on_cell_enter`: Callback when mouse enters a grid cell. Called with (cell_x, cell_y).
- `on_cell_exit`: Callback when mouse exits a grid cell. Called with (cell_x, cell_y).
- `on_click`: Callable executed when object is clicked. Function receives (x, y) coordinates of click.
- `on_enter`: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.
- `on_exit`: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `parent`: Parent drawable. Get: Returns the parent Frame/Grid if nested, or None if at scene level. Set: Assign a Frame/Grid to reparent, or None to remove from parent.
- `perspective`: Entity whose perspective to use for FOV rendering (None for omniscient view). Setting an entity automatically enables perspective mode.
- `perspective_enabled`: Whether to use perspective-based FOV rendering. When True with no valid entity, all cells appear undiscovered.
- `pos`: Position of the grid as Vector
- `position`: Position of the grid (x, y)
- `size`: Size of the grid (width, height)
- `texture`: Texture of the grid
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `w`: visible widget width
- `x`: top-left corner X-coordinate
- `y`: top-left corner Y-coordinate
- `z_index`: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
- `zoom`: zoom factor for displaying the Grid
**Methods:** **Methods:**
#### `add_layer(type: str, z_index: int = -1, texture: Texture = None) -> ColorLayer | TileLayer` #### `add_layer(type: str, z_index: int = -1, texture: Texture = None) -> ColorLayer | TileLayer`
@ -1165,12 +1346,22 @@ Note:
UIGridPoint object UIGridPoint object
**Properties:**
- `entities` *(read-only)*: List of entities at this grid cell (read-only)
- `transparent`: Is the GridPoint transparent
- `walkable`: Is the GridPoint walkable
**Methods:** **Methods:**
### GridPointState ### GridPointState
UIGridPointState object UIGridPointState object
**Properties:**
- `discovered`: Has the GridPointState been discovered
- `point`: GridPoint at this position (None if not discovered)
- `visible`: Is the GridPointState visible
**Methods:** **Methods:**
### Line ### Line
@ -1205,6 +1396,26 @@ Attributes:
name (str): Element name name (str): Element name
**Properties:**
- `bounds`: Bounding rectangle (x, y, width, height) in local coordinates.
- `color`: Line color as a Color object.
- `end`: Ending point of the line as a Vector.
- `global_bounds`: Bounding rectangle (x, y, width, height) in screen coordinates.
- `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
- `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
- `name`: Name for finding this element.
- `on_click`: Callable executed when line is clicked.
- `on_enter`: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.
- `on_exit`: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `parent`: 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`: Position as a Vector (midpoint of line).
- `start`: Starting point of the line as a Vector.
- `thickness`: Line thickness in pixels.
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `z_index`: Z-order for rendering (lower values rendered first).
**Methods:** **Methods:**
#### `get_bounds() -> tuple` #### `get_bounds() -> tuple`
@ -1237,7 +1448,56 @@ Note:
### Scene ### Scene
Base class for object-oriented scenes Scene(name: str)
Object-oriented scene management with lifecycle callbacks.
This is the recommended approach for scene management, replacing module-level
functions like createScene(), setScene(), and sceneUI(). Key advantage: you can
set on_key handlers on ANY scene, not just the currently active one.
Args:
name: Unique identifier for this scene. Used for scene transitions.
Properties:
name (str, read-only): Scene's unique identifier.
active (bool, read-only): Whether this scene is currently displayed.
children (UICollection, read-only): UI elements in this scene. Modify to add/remove elements.
on_key (callable): Keyboard handler. Set on ANY scene, regardless of which is active!
pos (Vector): Position offset for all UI elements.
visible (bool): Whether the scene renders.
opacity (float): Scene transparency (0.0-1.0).
Lifecycle Callbacks (override in subclass):
on_enter(): Called when scene becomes active via activate().
on_exit(): Called when scene is deactivated (another scene activates).
on_keypress(key: str, action: str): Called for keyboard events. Alternative to on_key property.
update(dt: float): Called every frame with delta time in seconds.
on_resize(width: int, height: int): Called when window is resized.
Example:
# Basic usage (replacing module functions):
scene = mcrfpy.Scene('main_menu')
scene.children.append(mcrfpy.Caption(text='Welcome', pos=(100, 100)))
scene.on_key = lambda key, action: print(f'Key: {key}')
scene.activate() # Switch to this scene
# Subclassing for lifecycle:
class GameScene(mcrfpy.Scene):
def on_enter(self):
print('Game started!')
def update(self, dt):
self.player.move(dt)
**Properties:**
- `active` *(read-only)*: Whether this scene is currently active (bool, read-only). Only one scene can be active at a time.
- `children` *(read-only)*: UI element collection for this scene (UICollection, read-only). Use to add, remove, or iterate over UI elements. Changes are reflected immediately.
- `name` *(read-only)*: Scene name (str, read-only). Unique identifier for this scene.
- `on_key`: Keyboard event handler (callable or None). Function receives (key: str, action: str) for keyboard events. Set to None to remove the handler.
- `opacity`: Scene opacity (0.0-1.0). Applied to all UI elements during rendering.
- `pos`: Scene position offset (Vector). Applied to all UI elements during rendering.
- `visible`: Scene visibility (bool). If False, scene is not rendered.
**Methods:** **Methods:**
@ -1299,6 +1559,30 @@ Attributes:
name (str): Element name name (str): Element name
w, h (float): Read-only computed size based on texture and scale w, h (float): Read-only computed size based on texture and scale
**Properties:**
- `bounds`: Bounding rectangle (x, y, width, height) in local coordinates.
- `global_bounds`: Bounding rectangle (x, y, width, height) in screen coordinates.
- `global_position` *(read-only)*: Global screen position (read-only). Calculates absolute position by walking up the parent chain.
- `hovered` *(read-only)*: Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.
- `name`: Name for finding elements
- `on_click`: Callable executed when object is clicked. Function receives (x, y) coordinates of click.
- `on_enter`: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element's bounds.
- `on_exit`: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element's bounds.
- `on_move`: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.
- `opacity`: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].
- `parent`: 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`: Position as a Vector
- `scale`: Uniform size factor
- `scale_x`: Horizontal scale factor
- `scale_y`: Vertical scale factor
- `sprite_index`: Which sprite on the texture is shown
- `sprite_number`: Sprite index (DEPRECATED: use sprite_index instead)
- `texture`: Texture object
- `visible`: Whether the object is visible (bool). Invisible objects are not rendered or clickable.
- `x`: X coordinate of top-left corner
- `y`: Y coordinate of top-left corner
- `z_index`: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.
**Methods:** **Methods:**
#### `get_bounds() -> tuple` #### `get_bounds() -> tuple`
@ -1333,6 +1617,14 @@ Note:
SFML Texture Object SFML Texture Object
**Properties:**
- `sheet_height` *(read-only)*: Number of sprite rows in the texture sheet (int, read-only). Calculated as texture_height / sprite_height.
- `sheet_width` *(read-only)*: Number of sprite columns in the texture sheet (int, read-only). Calculated as texture_width / sprite_width.
- `source` *(read-only)*: Source filename path (str, read-only). The path used to load this texture.
- `sprite_count` *(read-only)*: Total number of sprites in the texture sheet (int, read-only). Equals sheet_width * sheet_height.
- `sprite_height` *(read-only)*: Height of each sprite in pixels (int, read-only). Specified during texture initialization.
- `sprite_width` *(read-only)*: Width of each sprite in pixels (int, read-only). Specified during texture initialization.
**Methods:** **Methods:**
### TileLayer ### TileLayer
@ -1357,6 +1649,12 @@ Methods:
set(x, y, index): Set tile index at cell position set(x, y, index): Set tile index at cell position
fill(index): Fill entire layer with tile index fill(index): Fill entire layer with tile index
**Properties:**
- `grid_size`: Layer dimensions as (width, height) tuple.
- `texture`: Texture atlas for tile sprites.
- `visible`: Whether the layer is rendered.
- `z_index`: Layer z-order. Negative values render below entities.
**Methods:** **Methods:**
#### `at(x, y) -> int` #### `at(x, y) -> int`
@ -1412,6 +1710,15 @@ Example:
timer.resume() # Resume timer timer.resume() # Resume timer
timer.once = True # Make it one-shot timer.once = True # Make it one-shot
**Properties:**
- `active` *(read-only)*: Whether the timer is active and not paused (bool, read-only). False if cancelled or paused.
- `callback`: The callback function to be called when timer fires (callable). Can be changed while timer is running.
- `interval`: Timer interval in milliseconds (int). Must be positive. Can be changed while timer is running.
- `name` *(read-only)*: Timer name (str, read-only). Unique identifier for this timer.
- `once`: Whether the timer stops after firing once (bool). If False, timer repeats indefinitely.
- `paused` *(read-only)*: Whether the timer is paused (bool, read-only). Paused timers preserve their remaining time.
- `remaining` *(read-only)*: Time remaining until next trigger in milliseconds (int, read-only). Preserved when timer is paused.
**Methods:** **Methods:**
#### `cancel() -> None` #### `cancel() -> None`
@ -1508,6 +1815,11 @@ Iterator for a collection of UI objects
SFML Vector Object SFML Vector Object
**Properties:**
- `int` *(read-only)*: Integer tuple (floor of x and y) for use as dict keys. Read-only.
- `x`: X coordinate of the vector (float)
- `y`: Y coordinate of the vector (float)
**Methods:** **Methods:**
#### `angle() -> float` #### `angle() -> float`
@ -1574,6 +1886,16 @@ Note:
Window singleton for accessing and modifying the game window properties Window singleton for accessing and modifying the game window properties
**Properties:**
- `framerate_limit`: Frame rate limit in FPS (int, 0 for unlimited). Caps maximum frame rate.
- `fullscreen`: Window fullscreen state (bool). Setting this recreates the window.
- `game_resolution`: Fixed game resolution as (width, height) tuple. Enables resolution-independent rendering with scaling.
- `resolution`: Window resolution as (width, height) tuple. Setting this recreates the window.
- `scaling_mode`: Viewport scaling mode (str): 'center' (no scaling), 'stretch' (fill window), or 'fit' (maintain aspect ratio).
- `title`: Window title string (str). Displayed in the window title bar.
- `visible`: Window visibility state (bool). Hidden windows still process events.
- `vsync`: Vertical sync enabled state (bool). Prevents screen tearing but may limit framerate.
**Methods:** **Methods:**
#### `center() -> None` #### `center() -> None`

348
docs/api_reference_dynamic.html
View file

@ -108,7 +108,7 @@
<body> <body>
<div class="container"> <div class="container">
<h1>McRogueFace API Reference</h1> <h1>McRogueFace API Reference</h1>
<p><em>Generated on 2025-12-28 14:29:42</em></p> <p><em>Generated on 2025-12-29 14:23:40</em></p>
<p><em>This documentation was dynamically generated from the compiled module.</em></p> <p><em>This documentation was dynamically generated from the compiled module.</em></p>
<div class="toc"> <div class="toc">
@ -410,6 +410,14 @@ Note:</p>
<div class="method-section"> <div class="method-section">
<h3 id="Animation"><span class="class-name">Animation</span></h3> <h3 id="Animation"><span class="class-name">Animation</span></h3>
<p>Animation object for animating UI properties</p> <p>Animation object for animating UI properties</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>duration</span> (read-only): Animation duration in seconds (float, read-only). Total time for the animation to complete.</li>
<li><span class='property-name'>elapsed</span> (read-only): Elapsed time in seconds (float, read-only). Time since the animation started.</li>
<li><span class='property-name'>is_complete</span> (read-only): Whether animation is complete (bool, read-only). True when elapsed &gt;= duration or complete() was called.</li>
<li><span class='property-name'>is_delta</span> (read-only): Whether animation uses delta mode (bool, read-only). In delta mode, the target value is added to the starting value.</li>
<li><span class='property-name'>property</span> (read-only): Target property name (str, read-only). The property being animated (e.g., &#x27;pos&#x27;, &#x27;opacity&#x27;, &#x27;sprite_index&#x27;).</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -495,6 +503,29 @@ Attributes:
z_index (int): Rendering order z_index (int): Rendering order
name (str): Element name name (str): Element name
</p> </p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
<li><span class='property-name'>center</span>: Center position of the arc</li>
<li><span class='property-name'>color</span>: Arc color</li>
<li><span class='property-name'>end_angle</span>: Ending angle in degrees</li>
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>name</span>: Name for finding this element.</li>
<li><span class='property-name'>on_click</span>: Callable executed when arc is clicked.</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector (same as center).</li>
<li><span class='property-name'>radius</span>: Arc radius in pixels</li>
<li><span class='property-name'>start_angle</span>: Starting angle in degrees</li>
<li><span class='property-name'>thickness</span>: Line thickness</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -567,6 +598,30 @@ Attributes:
z_index (int): Rendering order z_index (int): Rendering order
name (str): Element name name (str): Element name
w, h (float): Read-only computed size based on text and font</p> w, h (float): Read-only computed size based on text and font</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
<li><span class='property-name'>fill_color</span>: Fill color of the text</li>
<li><span class='property-name'>font_size</span>: Font size (integer) in points</li>
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (x, y) coordinates of click.</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>outline</span>: Thickness of the border</li>
<li><span class='property-name'>outline_color</span>: Outline color of the text</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: (x, y) vector</li>
<li><span class='property-name'>text</span>: The text displayed</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>x</span>: X coordinate of top-left corner</li>
<li><span class='property-name'>y</span>: Y coordinate of top-left corner</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -632,6 +687,28 @@ Attributes:
z_index (int): Rendering order z_index (int): Rendering order
name (str): Element name name (str): Element name
</p> </p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
<li><span class='property-name'>center</span>: Center position of the circle</li>
<li><span class='property-name'>fill_color</span>: Fill color of the circle</li>
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>name</span>: Name for finding this element.</li>
<li><span class='property-name'>on_click</span>: Callable executed when circle is clicked.</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>outline</span>: Outline thickness (0 for no outline)</li>
<li><span class='property-name'>outline_color</span>: Outline color of the circle</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector (same as center).</li>
<li><span class='property-name'>radius</span>: Circle radius in pixels</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -668,6 +745,13 @@ Note:</p>
<div class="method-section"> <div class="method-section">
<h3 id="Color"><span class="class-name">Color</span></h3> <h3 id="Color"><span class="class-name">Color</span></h3>
<p>SFML Color Object</p> <p>SFML Color Object</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>a</span>: Alpha component (0-255, where 0=transparent, 255=opaque). Automatically clamped to valid range.</li>
<li><span class='property-name'>b</span>: Blue component (0-255). Automatically clamped to valid range.</li>
<li><span class='property-name'>g</span>: Green component (0-255). Automatically clamped to valid range.</li>
<li><span class='property-name'>r</span>: Red component (0-255). Automatically clamped to valid range.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -722,6 +806,12 @@ Methods:
at(x, y): Get color at cell position at(x, y): Get color at cell position
set(x, y, color): Set color at cell position set(x, y, color): Set color at cell position
fill(color): Fill entire layer with color</p> fill(color): Fill entire layer with color</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>grid_size</span>: Layer dimensions as (width, height) tuple.</li>
<li><span class='property-name'>visible</span>: Whether the layer is rendered.</li>
<li><span class='property-name'>z_index</span>: Layer z-order. Negative values render below entities.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -774,6 +864,13 @@ Call this after the entity moves to update the visibility layer.</p>
<div class="method-section"> <div class="method-section">
<h3 id="Drawable"><span class="class-name">Drawable</span></h3> <h3 id="Drawable"><span class="class-name">Drawable</span></h3>
<p>Base class for all drawable UI elements</p> <p>Base class for all drawable UI elements</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (x, y) coordinates of click.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -835,6 +932,20 @@ Attributes:
visible (bool): Visibility state visible (bool): Visibility state
opacity (float): Opacity value opacity (float): Opacity value
name (str): Element name</p> name (str): Element name</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>draw_pos</span>: Entity position (graphically)</li>
<li><span class='property-name'>grid</span>: Grid this entity belongs to. Get: Returns the Grid or None. Set: Assign a Grid to move entity, or None to remove from grid.</li>
<li><span class='property-name'>gridstate</span>: Grid point states for the entity</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>opacity</span>: Opacity (0.0 = transparent, 1.0 = opaque)</li>
<li><span class='property-name'>pos</span>: Entity position (integer grid coordinates)</li>
<li><span class='property-name'>sprite_index</span>: Sprite index on the texture on the display</li>
<li><span class='property-name'>sprite_number</span>: Sprite index (DEPRECATED: use sprite_index instead)</li>
<li><span class='property-name'>visible</span>: Visibility flag</li>
<li><span class='property-name'>x</span>: Entity x position</li>
<li><span class='property-name'>y</span>: Entity y position</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -956,6 +1067,13 @@ when the entity moves if it has a grid with perspective set.</p>
<div class="method-section"> <div class="method-section">
<h3 id="FOV"><span class="class-name">FOV</span></h3> <h3 id="FOV"><span class="class-name">FOV</span></h3>
<p><em>Inherits from: IntEnum</em></p> <p><em>Inherits from: IntEnum</em></p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>denominator</span>: the denominator of a rational number in lowest terms</li>
<li><span class='property-name'>imag</span>: the imaginary part of a complex number</li>
<li><span class='property-name'>numerator</span>: the numerator of a rational number in lowest terms</li>
<li><span class='property-name'>real</span>: the real part of a complex number</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -1040,6 +1158,11 @@ Also known as the population count.
<div class="method-section"> <div class="method-section">
<h3 id="Font"><span class="class-name">Font</span></h3> <h3 id="Font"><span class="class-name">Font</span></h3>
<p>SFML Font Object</p> <p>SFML Font Object</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>family</span> (read-only): Font family name (str, read-only). Retrieved from font metadata.</li>
<li><span class='property-name'>source</span> (read-only): Source filename path (str, read-only). The path used to load this font.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
</div> </div>
@ -1085,6 +1208,33 @@ Attributes:
name (str): Element name name (str): Element name
clip_children (bool): Whether to clip children to frame bounds clip_children (bool): Whether to clip children to frame bounds
cache_subtree (bool): Cache subtree rendering to texture</p> cache_subtree (bool): Cache subtree rendering to texture</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
<li><span class='property-name'>cache_subtree</span>: #144: Cache subtree rendering to texture for performance</li>
<li><span class='property-name'>children</span>: UICollection of objects on top of this one</li>
<li><span class='property-name'>clip_children</span>: Whether to clip children to frame bounds</li>
<li><span class='property-name'>fill_color</span>: Fill color of the rectangle</li>
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>h</span>: height of the rectangle</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (x, y) coordinates of click.</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>outline</span>: Thickness of the border</li>
<li><span class='property-name'>outline_color</span>: Outline color of the rectangle</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span>: width of the rectangle</li>
<li><span class='property-name'>x</span>: X coordinate of top-left corner</li>
<li><span class='property-name'>y</span>: Y coordinate of top-left corner</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -1168,6 +1318,49 @@ Attributes:
opacity (float): Opacity value opacity (float): Opacity value
z_index (int): Rendering order z_index (int): Rendering order
name (str): Element name</p> name (str): Element name</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
<li><span class='property-name'>center</span>: Grid coordinate at the center of the Grid&#x27;s view (pan)</li>
<li><span class='property-name'>center_x</span>: center of the view X-coordinate</li>
<li><span class='property-name'>center_y</span>: center of the view Y-coordinate</li>
<li><span class='property-name'>children</span>: UICollection of UIDrawable children (speech bubbles, effects, overlays)</li>
<li><span class='property-name'>entities</span>: EntityCollection of entities on this grid</li>
<li><span class='property-name'>fill_color</span>: Background fill color of the grid</li>
<li><span class='property-name'>fov</span>: FOV algorithm for this grid (mcrfpy.FOV enum). Used by entity.updateVisibility() and layer methods when fov=None.</li>
<li><span class='property-name'>fov_radius</span>: Default FOV radius for this grid. Used when radius not specified.</li>
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>grid_size</span>: Grid dimensions (grid_x, grid_y)</li>
<li><span class='property-name'>grid_x</span>: Grid x dimension</li>
<li><span class='property-name'>grid_y</span>: Grid y dimension</li>
<li><span class='property-name'>h</span>: visible widget height</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>hovered_cell</span>: Currently hovered cell as (x, y) tuple, or None if not hovering.</li>
<li><span class='property-name'>layers</span>: List of grid layers (ColorLayer, TileLayer) sorted by z_index</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>on_cell_click</span>: Callback when a grid cell is clicked. Called with (cell_x, cell_y).</li>
<li><span class='property-name'>on_cell_enter</span>: Callback when mouse enters a grid cell. Called with (cell_x, cell_y).</li>
<li><span class='property-name'>on_cell_exit</span>: Callback when mouse exits a grid cell. Called with (cell_x, cell_y).</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (x, y) coordinates of click.</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>perspective</span>: Entity whose perspective to use for FOV rendering (None for omniscient view). Setting an entity automatically enables perspective mode.</li>
<li><span class='property-name'>perspective_enabled</span>: Whether to use perspective-based FOV rendering. When True with no valid entity, all cells appear undiscovered.</li>
<li><span class='property-name'>pos</span>: Position of the grid as Vector</li>
<li><span class='property-name'>position</span>: Position of the grid (x, y)</li>
<li><span class='property-name'>size</span>: Size of the grid (width, height)</li>
<li><span class='property-name'>texture</span>: Texture of the grid</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>w</span>: visible widget width</li>
<li><span class='property-name'>x</span>: top-left corner X-coordinate</li>
<li><span class='property-name'>y</span>: top-left corner Y-coordinate</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
<li><span class='property-name'>zoom</span>: zoom factor for displaying the Grid</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -1325,12 +1518,24 @@ Note:</p>
<div class="method-section"> <div class="method-section">
<h3 id="GridPoint"><span class="class-name">GridPoint</span></h3> <h3 id="GridPoint"><span class="class-name">GridPoint</span></h3>
<p>UIGridPoint object</p> <p>UIGridPoint object</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>entities</span> (read-only): List of entities at this grid cell (read-only)</li>
<li><span class='property-name'>transparent</span>: Is the GridPoint transparent</li>
<li><span class='property-name'>walkable</span>: Is the GridPoint walkable</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
</div> </div>
<div class="method-section"> <div class="method-section">
<h3 id="GridPointState"><span class="class-name">GridPointState</span></h3> <h3 id="GridPointState"><span class="class-name">GridPointState</span></h3>
<p>UIGridPointState object</p> <p>UIGridPointState object</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>discovered</span>: Has the GridPointState been discovered</li>
<li><span class='property-name'>point</span>: GridPoint at this position (None if not discovered)</li>
<li><span class='property-name'>visible</span>: Is the GridPointState visible</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
</div> </div>
@ -1364,6 +1569,27 @@ Attributes:
z_index (int): Rendering order z_index (int): Rendering order
name (str): Element name name (str): Element name
</p> </p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
<li><span class='property-name'>color</span>: Line color as a Color object.</li>
<li><span class='property-name'>end</span>: Ending point of the line as a Vector.</li>
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>name</span>: Name for finding this element.</li>
<li><span class='property-name'>on_click</span>: Callable executed when line is clicked.</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector (midpoint of line).</li>
<li><span class='property-name'>start</span>: Starting point of the line as a Vector.</li>
<li><span class='property-name'>thickness</span>: Line thickness in pixels.</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first).</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -1399,7 +1625,57 @@ Note:</p>
<div class="method-section"> <div class="method-section">
<h3 id="Scene"><span class="class-name">Scene</span></h3> <h3 id="Scene"><span class="class-name">Scene</span></h3>
<p>Base class for object-oriented scenes</p> <p>Scene(name: str)
Object-oriented scene management with lifecycle callbacks.
This is the recommended approach for scene management, replacing module-level
functions like createScene(), setScene(), and sceneUI(). Key advantage: you can
set on_key handlers on ANY scene, not just the currently active one.
Args:
name: Unique identifier for this scene. Used for scene transitions.
Properties:
name (str, read-only): Scene&#x27;s unique identifier.
active (bool, read-only): Whether this scene is currently displayed.
children (UICollection, read-only): UI elements in this scene. Modify to add/remove elements.
on_key (callable): Keyboard handler. Set on ANY scene, regardless of which is active!
pos (Vector): Position offset for all UI elements.
visible (bool): Whether the scene renders.
opacity (float): Scene transparency (0.0-1.0).
Lifecycle Callbacks (override in subclass):
on_enter(): Called when scene becomes active via activate().
on_exit(): Called when scene is deactivated (another scene activates).
on_keypress(key: str, action: str): Called for keyboard events. Alternative to on_key property.
update(dt: float): Called every frame with delta time in seconds.
on_resize(width: int, height: int): Called when window is resized.
Example:
# Basic usage (replacing module functions):
scene = mcrfpy.Scene(&#x27;main_menu&#x27;)
scene.children.append(mcrfpy.Caption(text=&#x27;Welcome&#x27;, pos=(100, 100)))
scene.on_key = lambda key, action: print(f&#x27;Key: {key}&#x27;)
scene.activate() # Switch to this scene
# Subclassing for lifecycle:
class GameScene(mcrfpy.Scene):
def on_enter(self):
print(&#x27;Game started!&#x27;)
def update(self, dt):
self.player.move(dt)
</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>active</span> (read-only): Whether this scene is currently active (bool, read-only). Only one scene can be active at a time.</li>
<li><span class='property-name'>children</span> (read-only): UI element collection for this scene (UICollection, read-only). Use to add, remove, or iterate over UI elements. Changes are reflected immediately.</li>
<li><span class='property-name'>name</span> (read-only): Scene name (str, read-only). Unique identifier for this scene.</li>
<li><span class='property-name'>on_key</span>: Keyboard event handler (callable or None). Function receives (key: str, action: str) for keyboard events. Set to None to remove the handler.</li>
<li><span class='property-name'>opacity</span>: Scene opacity (0.0-1.0). Applied to all UI elements during rendering.</li>
<li><span class='property-name'>pos</span>: Scene position offset (Vector). Applied to all UI elements during rendering.</li>
<li><span class='property-name'>visible</span>: Scene visibility (bool). If False, scene is not rendered.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -1459,6 +1735,31 @@ Attributes:
z_index (int): Rendering order z_index (int): Rendering order
name (str): Element name name (str): Element name
w, h (float): Read-only computed size based on texture and scale</p> w, h (float): Read-only computed size based on texture and scale</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>bounds</span>: Bounding rectangle (x, y, width, height) in local coordinates.</li>
<li><span class='property-name'>global_bounds</span>: Bounding rectangle (x, y, width, height) in screen coordinates.</li>
<li><span class='property-name'>global_position</span> (read-only): Global screen position (read-only). Calculates absolute position by walking up the parent chain.</li>
<li><span class='property-name'>hovered</span> (read-only): Whether mouse is currently over this element (read-only). Updated automatically by the engine during mouse movement.</li>
<li><span class='property-name'>name</span>: Name for finding elements</li>
<li><span class='property-name'>on_click</span>: Callable executed when object is clicked. Function receives (x, y) coordinates of click.</li>
<li><span class='property-name'>on_enter</span>: Callback for mouse enter events. Called with (x, y, button, action) when mouse enters this element&#x27;s bounds.</li>
<li><span class='property-name'>on_exit</span>: Callback for mouse exit events. Called with (x, y, button, action) when mouse leaves this element&#x27;s bounds.</li>
<li><span class='property-name'>on_move</span>: Callback for mouse movement within bounds. Called with (x, y, button, action) for each mouse movement while inside. Performance note: Called frequently during movement - keep handlers fast.</li>
<li><span class='property-name'>opacity</span>: Opacity level (0.0 = transparent, 1.0 = opaque). Automatically clamped to valid range [0.0, 1.0].</li>
<li><span class='property-name'>parent</span>: 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.</li>
<li><span class='property-name'>pos</span>: Position as a Vector</li>
<li><span class='property-name'>scale</span>: Uniform size factor</li>
<li><span class='property-name'>scale_x</span>: Horizontal scale factor</li>
<li><span class='property-name'>scale_y</span>: Vertical scale factor</li>
<li><span class='property-name'>sprite_index</span>: Which sprite on the texture is shown</li>
<li><span class='property-name'>sprite_number</span>: Sprite index (DEPRECATED: use sprite_index instead)</li>
<li><span class='property-name'>texture</span>: Texture object</li>
<li><span class='property-name'>visible</span>: Whether the object is visible (bool). Invisible objects are not rendered or clickable.</li>
<li><span class='property-name'>x</span>: X coordinate of top-left corner</li>
<li><span class='property-name'>y</span>: Y coordinate of top-left corner</li>
<li><span class='property-name'>z_index</span>: Z-order for rendering (lower values rendered first). Automatically triggers scene resort when changed.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -1495,6 +1796,15 @@ Note:</p>
<div class="method-section"> <div class="method-section">
<h3 id="Texture"><span class="class-name">Texture</span></h3> <h3 id="Texture"><span class="class-name">Texture</span></h3>
<p>SFML Texture Object</p> <p>SFML Texture Object</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>sheet_height</span> (read-only): Number of sprite rows in the texture sheet (int, read-only). Calculated as texture_height / sprite_height.</li>
<li><span class='property-name'>sheet_width</span> (read-only): Number of sprite columns in the texture sheet (int, read-only). Calculated as texture_width / sprite_width.</li>
<li><span class='property-name'>source</span> (read-only): Source filename path (str, read-only). The path used to load this texture.</li>
<li><span class='property-name'>sprite_count</span> (read-only): Total number of sprites in the texture sheet (int, read-only). Equals sheet_width * sheet_height.</li>
<li><span class='property-name'>sprite_height</span> (read-only): Height of each sprite in pixels (int, read-only). Specified during texture initialization.</li>
<li><span class='property-name'>sprite_width</span> (read-only): Width of each sprite in pixels (int, read-only). Specified during texture initialization.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
</div> </div>
@ -1519,6 +1829,13 @@ Methods:
at(x, y): Get tile index at cell position at(x, y): Get tile index at cell position
set(x, y, index): Set tile index at cell position set(x, y, index): Set tile index at cell position
fill(index): Fill entire layer with tile index</p> fill(index): Fill entire layer with tile index</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>grid_size</span>: Layer dimensions as (width, height) tuple.</li>
<li><span class='property-name'>texture</span>: Texture atlas for tile sprites.</li>
<li><span class='property-name'>visible</span>: Whether the layer is rendered.</li>
<li><span class='property-name'>z_index</span>: Layer z-order. Negative values render below entities.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -1578,6 +1895,16 @@ Example:
timer.pause() # Pause timer timer.pause() # Pause timer
timer.resume() # Resume timer timer.resume() # Resume timer
timer.once = True # Make it one-shot</p> timer.once = True # Make it one-shot</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>active</span> (read-only): Whether the timer is active and not paused (bool, read-only). False if cancelled or paused.</li>
<li><span class='property-name'>callback</span>: The callback function to be called when timer fires (callable). Can be changed while timer is running.</li>
<li><span class='property-name'>interval</span>: Timer interval in milliseconds (int). Must be positive. Can be changed while timer is running.</li>
<li><span class='property-name'>name</span> (read-only): Timer name (str, read-only). Unique identifier for this timer.</li>
<li><span class='property-name'>once</span>: Whether the timer stops after firing once (bool). If False, timer repeats indefinitely.</li>
<li><span class='property-name'>paused</span> (read-only): Whether the timer is paused (bool, read-only). Paused timers preserve their remaining time.</li>
<li><span class='property-name'>remaining</span> (read-only): Time remaining until next trigger in milliseconds (int, read-only). Preserved when timer is paused.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -1681,6 +2008,12 @@ Use name-based .find() for stable element access.</p>
<div class="method-section"> <div class="method-section">
<h3 id="Vector"><span class="class-name">Vector</span></h3> <h3 id="Vector"><span class="class-name">Vector</span></h3>
<p>SFML Vector Object</p> <p>SFML Vector Object</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>int</span> (read-only): Integer tuple (floor of x and y) for use as dict keys. Read-only.</li>
<li><span class='property-name'>x</span>: X coordinate of the vector (float)</li>
<li><span class='property-name'>y</span>: Y coordinate of the vector (float)</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">
@ -1747,6 +2080,17 @@ Note:</p>
<div class="method-section"> <div class="method-section">
<h3 id="Window"><span class="class-name">Window</span></h3> <h3 id="Window"><span class="class-name">Window</span></h3>
<p>Window singleton for accessing and modifying the game window properties</p> <p>Window singleton for accessing and modifying the game window properties</p>
<h4>Properties:</h4>
<ul>
<li><span class='property-name'>framerate_limit</span>: Frame rate limit in FPS (int, 0 for unlimited). Caps maximum frame rate.</li>
<li><span class='property-name'>fullscreen</span>: Window fullscreen state (bool). Setting this recreates the window.</li>
<li><span class='property-name'>game_resolution</span>: Fixed game resolution as (width, height) tuple. Enables resolution-independent rendering with scaling.</li>
<li><span class='property-name'>resolution</span>: Window resolution as (width, height) tuple. Setting this recreates the window.</li>
<li><span class='property-name'>scaling_mode</span>: Viewport scaling mode (str): &#x27;center&#x27; (no scaling), &#x27;stretch&#x27; (fill window), or &#x27;fit&#x27; (maintain aspect ratio).</li>
<li><span class='property-name'>title</span>: Window title string (str). Displayed in the window title bar.</li>
<li><span class='property-name'>visible</span>: Window visibility state (bool). Hidden windows still process events.</li>
<li><span class='property-name'>vsync</span>: Vertical sync enabled state (bool). Prevents screen tearing but may limit framerate.</li>
</ul>
<h4>Methods:</h4> <h4>Methods:</h4>
<div style="margin-left: 20px; margin-bottom: 15px;"> <div style="margin-left: 20px; margin-bottom: 15px;">

36
src/PySceneObject.h
View file

@ -53,7 +53,41 @@ namespace mcrfpydef {
.tp_dealloc = (destructor)PySceneClass::__dealloc, .tp_dealloc = (destructor)PySceneClass::__dealloc,
.tp_repr = (reprfunc)PySceneClass::__repr__, .tp_repr = (reprfunc)PySceneClass::__repr__,
.tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, // Allow subclassing .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE, // Allow subclassing
.tp_doc = PyDoc_STR("Base class for object-oriented scenes"), .tp_doc = PyDoc_STR(
"Scene(name: str)\n\n"
"Object-oriented scene management with lifecycle callbacks.\n\n"
"This is the recommended approach for scene management, replacing module-level\n"
"functions like createScene(), setScene(), and sceneUI(). Key advantage: you can\n"
"set on_key handlers on ANY scene, not just the currently active one.\n\n"
"Args:\n"
" name: Unique identifier for this scene. Used for scene transitions.\n\n"
"Properties:\n"
" name (str, read-only): Scene's unique identifier.\n"
" active (bool, read-only): Whether this scene is currently displayed.\n"
" children (UICollection, read-only): UI elements in this scene. Modify to add/remove elements.\n"
" on_key (callable): Keyboard handler. Set on ANY scene, regardless of which is active!\n"
" pos (Vector): Position offset for all UI elements.\n"
" visible (bool): Whether the scene renders.\n"
" opacity (float): Scene transparency (0.0-1.0).\n\n"
"Lifecycle Callbacks (override in subclass):\n"
" on_enter(): Called when scene becomes active via activate().\n"
" on_exit(): Called when scene is deactivated (another scene activates).\n"
" on_keypress(key: str, action: str): Called for keyboard events. Alternative to on_key property.\n"
" update(dt: float): Called every frame with delta time in seconds.\n"
" on_resize(width: int, height: int): Called when window is resized.\n\n"
"Example:\n"
" # Basic usage (replacing module functions):\n"
" scene = mcrfpy.Scene('main_menu')\n"
" scene.children.append(mcrfpy.Caption(text='Welcome', pos=(100, 100)))\n"
" scene.on_key = lambda key, action: print(f'Key: {key}')\n"
" scene.activate() # Switch to this scene\n\n"
" # Subclassing for lifecycle:\n"
" class GameScene(mcrfpy.Scene):\n"
" def on_enter(self):\n"
" print('Game started!')\n"
" def update(self, dt):\n"
" self.player.move(dt)\n"
),
.tp_methods = nullptr, // Set in McRFPy_API.cpp .tp_methods = nullptr, // Set in McRFPy_API.cpp
.tp_getset = nullptr, // Set in McRFPy_API.cpp .tp_getset = nullptr, // Set in McRFPy_API.cpp
.tp_init = (initproc)PySceneClass::__init__, .tp_init = (initproc)PySceneClass::__init__,

11
tools/generate_dynamic_docs.py
View file

@ -10,6 +10,7 @@ import inspect
import datetime import datetime
import html import html
import re import re
import types
from pathlib import Path from pathlib import Path
def transform_doc_links(docstring, format='html', base_url=''): def transform_doc_links(docstring, format='html', base_url=''):
@ -214,11 +215,21 @@ def get_all_classes():
"parsed": parse_docstring(method_doc) "parsed": parse_docstring(method_doc)
} }
elif isinstance(attr, property): elif isinstance(attr, property):
# Pure Python property
prop_doc = (attr.fget.__doc__ if attr.fget else "") or "" prop_doc = (attr.fget.__doc__ if attr.fget else "") or ""
class_info["properties"][attr_name] = { class_info["properties"][attr_name] = {
"doc": prop_doc, "doc": prop_doc,
"readonly": attr.fset is None "readonly": attr.fset is None
} }
elif isinstance(attr, (types.GetSetDescriptorType, types.MemberDescriptorType)):
# C++ extension property (PyGetSetDef or PyMemberDef)
prop_doc = attr.__doc__ or ""
# Check if docstring indicates read-only (convention: "read-only" in description)
readonly = "read-only" in prop_doc.lower()
class_info["properties"][attr_name] = {
"doc": prop_doc,
"readonly": readonly
}
except: except:
pass pass