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

Squashed commit of the following: [alpha_presentable]

Browse source 
Author: John McCardle <mccardle.john@gmail.com>
Co-Authored-By: Claude <noreply@anthropic.com>

commit dc47f2474c7b2642d368f9772894aed857527807
    the UIEntity rant

commit 673ca8e1b089ea670257fc04ae1a676ed95a40ed
    I forget when these tests were written, but I want them in the squash merge

commit 70c71565c684fa96e222179271ecb13a156d80ad
    Fix UI object segfault by switching from managed to manual weakref management

    The UI types (Frame, Caption, Sprite, Grid, Entity) were using
    Py_TPFLAGS_MANAGED_WEAKREF while also trying to manually create weakrefs
    for the PythonObjectCache. This is fundamentally incompatible - when
    Python manages weakrefs internally, PyWeakref_NewRef() cannot access the
    weakref list properly, causing segfaults.

    Changed all UI types to use manual weakref management (like PyTimer):
    - Restored weakreflist field in all UI type structures
    - Removed Py_TPFLAGS_MANAGED_WEAKREF from all UI type flags
    - Added tp_weaklistoffset for all UI types in module initialization
    - Initialize weakreflist=NULL in tp_new and init methods
    - Call PyObject_ClearWeakRefs() in dealloc functions

    This allows the PythonObjectCache to continue working correctly,
    maintaining Python object identity for C++ objects across the boundary.

    Fixes segfault when creating UI objects (e.g., Caption, Grid) that was
    preventing tutorial scripts from running.

This is the bulk of the required behavior for Issue #126.
that issure isn't ready for closure yet; several other sub-issues left.
    closes #110
    mention issue #109 - resolves some __init__ related nuisances

commit 3dce3ec539ae99e32d869007bf3f49d03e4e2f89
    Refactor timer system for cleaner architecture and enhanced functionality

    Major improvements to the timer system:
    - Unified all timer logic in the Timer class (C++)
    - Removed PyTimerCallable subclass, now using PyCallable directly
    - Timer objects are now passed to callbacks as first argument
    - Added 'once' parameter for one-shot timers that auto-stop
    - Implemented proper PythonObjectCache integration with weakref support

    API enhancements:
    - New callback signature: callback(timer, runtime) instead of just (runtime)
    - Timer objects expose: name, interval, remaining, paused, active, once properties
    - Methods: pause(), resume(), cancel(), restart()
    - Comprehensive documentation with examples
    - Enhanced repr showing timer state (active/paused/once/remaining time)

    This cleanup follows the UIEntity/PyUIEntity pattern and makes the timer
    system more Pythonic while maintaining backward compatibility through
    the legacy setTimer/delTimer API.

    closes #121

commit 145834cfc31b8dabc4cb3591b9cb4ed99fc8b964
    Implement Python object cache to preserve derived types in collections

    Add a global cache system that maintains weak references to Python objects,
    ensuring that derived Python classes maintain their identity when stored in
    and retrieved from C++ collections.

    Key changes:
    - Add PythonObjectCache singleton with serial number system
    - Each cacheable object (UIDrawable, UIEntity, Timer, Animation) gets unique ID
    - Cache stores weak references to prevent circular reference memory leaks
    - Update all UI type definitions to support weak references (Py_TPFLAGS_MANAGED_WEAKREF)
    - Enable subclassing for all UI types (Py_TPFLAGS_BASETYPE)
    - Collections check cache before creating new Python wrappers
    - Register objects in cache during __init__ methods
    - Clean up cache entries in C++ destructors

    This ensures that Python code like:
    ```python
    class MyFrame(mcrfpy.Frame):
        def __init__(self):
            super().__init__()
            self.custom_data = "preserved"

    frame = MyFrame()
    scene.ui.append(frame)
    retrieved = scene.ui[0]  # Same MyFrame instance with custom_data intact
    ```

    Works correctly, with retrieved maintaining the derived type and custom attributes.

    Closes #112

commit c5e7e8e298
    Update test demos for new Python API and entity system

    - Update all text input demos to use new Entity constructor signature
    - Fix pathfinding showcase to work with new entity position handling
    - Remove entity_waypoints tracking in favor of simplified movement
    - Delete obsolete exhaustive_api_demo.py (superseded by newer demos)
    - Adjust entity creation calls to match Entity((x, y), texture, sprite_index) pattern

commit 6d29652ae7
    Update animation demo suite with crash fixes and improvements

    - Add warnings about AnimationManager segfault bug in sizzle_reel_final.py
    - Create sizzle_reel_final_fixed.py that works around the crash by hiding objects instead of removing them
    - Increase font sizes for better visibility in demos
    - Extend demo durations for better showcase of animations
    - Remove debug prints from animation_sizzle_reel_working.py
    - Minor cleanup and improvements to all animation demos

commit a010e5fa96
    Update game scripts for new Python API

    - Convert entity position access from tuple to x/y properties
    - Update caption size property to font_size
    - Fix grid boundary checks to use grid_size instead of exceptions
    - Clean up demo timer on menu exit to prevent callbacks

    These changes adapt the game scripts to work with the new standardized
    Python API constructors and property names.

commit 9c8d6c4591
    Fix click event z-order handling in PyScene

    Changed click detection to properly respect z-index by:
    - Sorting ui_elements in-place when needed (same as render order)
    - Using reverse iterators to check highest z-index elements first
    - This ensures top-most elements receive clicks before lower ones

commit dcd1b0ca33
    Add roguelike tutorial implementation files

    Implement Parts 0-2 of the classic roguelike tutorial adapted for McRogueFace:
    - Part 0: Basic grid setup and tile rendering
    - Part 1: Drawing '@' symbol and basic movement
    - Part 1b: Variant with sprite-based player
    - Part 2: Entity system and NPC implementation with three movement variants:
      - part_2.py: Standard implementation
      - part_2-naive.py: Naive movement approach
      - part_2-onemovequeued.py: Queued movement system

    Includes tutorial assets:
    - tutorial2.png: Tileset for dungeon tiles
    - tutorial_hero.png: Player sprite sheet

commit 6813fb5129
    Standardize Python API constructors and remove PyArgHelpers

    - Remove PyArgHelpers.h and all macro-based argument parsing
    - Convert all UI class constructors to use PyArg_ParseTupleAndKeywords
    - Standardize constructor signatures across UICaption, UIEntity, UIFrame, UIGrid, and UISprite
    - Replace PYARGHELPER_SINGLE/MULTI macros with explicit argument parsing
    - Improve error messages and argument validation
    - Maintain backward compatibility with existing Python code

    This change improves code maintainability and consistency across the Python API.

commit 6f67fbb51e
    Fix animation callback crashes from iterator invalidation (#119)

    Resolved segfaults caused by creating new animations from within
    animation callbacks. The issue was iterator invalidation in
    AnimationManager::update() when callbacks modified the active
    animations vector.

    Changes:
    - Add deferred animation queue to AnimationManager
    - New animations created during update are queued and added after
    - Set isUpdating flag to track when in update loop
    - Properly handle Animation destructor during callback execution
    - Add clearCallback() method for safe cleanup scenarios

    This fixes the "free(): invalid pointer" and "malloc(): unaligned
    fastbin chunk detected" errors that occurred with rapid animation
    creation in callbacks.

commit eb88c7b3aa
    Add animation completion callbacks (#119)

    Implement callbacks that fire when animations complete, enabling direct
    causality between animation end and game state changes. This eliminates
    race conditions from parallel timer workarounds.

    - Add optional callback parameter to Animation constructor
    - Callbacks execute synchronously when animation completes
    - Proper Python reference counting with GIL safety
    - Callbacks receive (anim, target) parameters (currently None)
    - Exception handling prevents crashes from Python errors

    Example usage:
    ```python
    def on_complete(anim, target):
        player_moving = False

    anim = mcrfpy.Animation("x", 300.0, 1.0, "easeOut", callback=on_complete)
    anim.start(player)
    ```

    closes #119

commit 9fb428dd01
    Update ROADMAP with GitHub issue numbers (#111-#125)

    Added issue numbers from GitHub tracker to roadmap items:
    - #111: Grid Click Events Broken in Headless
    - #112: Object Splitting Bug (Python type preservation)
    - #113: Batch Operations for Grid
    - #114: CellView API
    - #115: SpatialHash Implementation
    - #116: Dirty Flag System
    - #117: Memory Pool for Entities
    - #118: Scene as Drawable
    - #119: Animation Completion Callbacks
    - #120: Animation Property Locking
    - #121: Timer Object System
    - #122: Parent-Child UI System
    - #123: Grid Subgrid System
    - #124: Grid Point Animation
    - #125: GitHub Issues Automation

    Also updated existing references:
    - #101/#110: Constructor standardization
    - #109: Vector class indexing

    Note: Tutorial-specific items and Python-implementable features
    (input queue, collision reservation) are not tracked as engine issues.

commit 062e4dadc4
    Fix animation segfaults with RAII weak_ptr implementation

    Resolved two critical segmentation faults in AnimationManager:
    1. Race condition when creating multiple animations in timer callbacks
    2. Exit crash when animations outlive their target objects

    Changes:
    - Replace raw pointers with std::weak_ptr for automatic target invalidation
    - Add Animation::complete() to jump animations to final value
    - Add Animation::hasValidTarget() to check if target still exists
    - Update AnimationManager to auto-remove invalid animations
    - Add AnimationManager::clear() call to GameEngine::cleanup()
    - Update Python bindings to pass shared_ptr instead of raw pointers

    This ensures animations can never reference destroyed objects, following
    proper RAII principles. Tested with sizzle_reel_final.py and stress
    tests creating/destroying hundreds of animated objects.

commit 98fc49a978
    Directory structure cleanup and organization overhaul
This commit is contained in:
John McCardle 2025-07-15 21:30:49 -04:00
commit f4343e1e82
163 changed files with 12812 additions and 5441 deletions
Download patch file Download diff file Expand all files Collapse all files

960
tools/generate_complete_api_docs.py Normal file
View file

@ -0,0 +1,960 @@
#!/usr/bin/env python3
"""Generate COMPLETE HTML API reference documentation for McRogueFace with NO missing methods."""
import os
import sys
import datetime
import html
from pathlib import Path
import mcrfpy
def escape_html(text: str) -> str:
"""Escape HTML special characters."""
return html.escape(text) if text else ""
def get_complete_method_documentation():
"""Return complete documentation for ALL methods across all classes."""
return {
# Base Drawable methods (inherited by all UI elements)
'Drawable': {
'get_bounds': {
'signature': 'get_bounds()',
'description': 'Get the bounding rectangle of this drawable element.',
'returns': 'tuple: (x, y, width, height) representing the element\'s bounds',
'note': 'The bounds are in screen coordinates and account for current position and size.'
},
'move': {
'signature': 'move(dx, dy)',
'description': 'Move the element by a relative offset.',
'args': [
('dx', 'float', 'Horizontal offset in pixels'),
('dy', 'float', 'Vertical offset in pixels')
],
'note': 'This modifies the x and y position properties by the given amounts.'
},
'resize': {
'signature': 'resize(width, height)',
'description': 'Resize the element to new dimensions.',
'args': [
('width', 'float', 'New width in pixels'),
('height', 'float', 'New height in pixels')
],
'note': 'For Caption and Sprite, this may not change actual size if determined by content.'
}
},
# Entity-specific methods
'Entity': {
'at': {
'signature': 'at(x, y)',
'description': 'Check if this entity is at the specified grid coordinates.',
'args': [
('x', 'int', 'Grid x coordinate to check'),
('y', 'int', 'Grid y coordinate to check')
],
'returns': 'bool: True if entity is at position (x, y), False otherwise'
},
'die': {
'signature': 'die()',
'description': 'Remove this entity from its parent grid.',
'note': 'The entity object remains valid but is no longer rendered or updated.'
},
'index': {
'signature': 'index()',
'description': 'Get the index of this entity in its parent grid\'s entity list.',
'returns': 'int: Index position, or -1 if not in a grid'
}
},
# Grid-specific methods
'Grid': {
'at': {
'signature': 'at(x, y)',
'description': 'Get the GridPoint at the specified grid coordinates.',
'args': [
('x', 'int', 'Grid x coordinate'),
('y', 'int', 'Grid y coordinate')
],
'returns': 'GridPoint or None: The grid point at (x, y), or None if out of bounds'
}
},
# Collection methods
'EntityCollection': {
'append': {
'signature': 'append(entity)',
'description': 'Add an entity to the end of the collection.',
'args': [('entity', 'Entity', 'The entity to add')]
},
'remove': {
'signature': 'remove(entity)',
'description': 'Remove the first occurrence of an entity from the collection.',
'args': [('entity', 'Entity', 'The entity to remove')],
'raises': 'ValueError: If entity is not in collection'
},
'extend': {
'signature': 'extend(iterable)',
'description': 'Add all entities from an iterable to the collection.',
'args': [('iterable', 'Iterable[Entity]', 'Entities to add')]
},
'count': {
'signature': 'count(entity)',
'description': 'Count the number of occurrences of an entity in the collection.',
'args': [('entity', 'Entity', 'The entity to count')],
'returns': 'int: Number of times entity appears in collection'
},
'index': {
'signature': 'index(entity)',
'description': 'Find the index of the first occurrence of an entity.',
'args': [('entity', 'Entity', 'The entity to find')],
'returns': 'int: Index of entity in collection',
'raises': 'ValueError: If entity is not in collection'
}
},
'UICollection': {
'append': {
'signature': 'append(drawable)',
'description': 'Add a drawable element to the end of the collection.',
'args': [('drawable', 'UIDrawable', 'The drawable element to add')]
},
'remove': {
'signature': 'remove(drawable)',
'description': 'Remove the first occurrence of a drawable from the collection.',
'args': [('drawable', 'UIDrawable', 'The drawable to remove')],
'raises': 'ValueError: If drawable is not in collection'
},
'extend': {
'signature': 'extend(iterable)',
'description': 'Add all drawables from an iterable to the collection.',
'args': [('iterable', 'Iterable[UIDrawable]', 'Drawables to add')]
},
'count': {
'signature': 'count(drawable)',
'description': 'Count the number of occurrences of a drawable in the collection.',
'args': [('drawable', 'UIDrawable', 'The drawable to count')],
'returns': 'int: Number of times drawable appears in collection'
},
'index': {
'signature': 'index(drawable)',
'description': 'Find the index of the first occurrence of a drawable.',
'args': [('drawable', 'UIDrawable', 'The drawable to find')],
'returns': 'int: Index of drawable in collection',
'raises': 'ValueError: If drawable is not in collection'
}
},
# Animation methods
'Animation': {
'get_current_value': {
'signature': 'get_current_value()',
'description': 'Get the current interpolated value of the animation.',
'returns': 'float: Current animation value between start and end'
},
'start': {
'signature': 'start(target)',
'description': 'Start the animation on a target UI element.',
'args': [('target', 'UIDrawable', 'The UI element to animate')],
'note': 'The target must have the property specified in the animation constructor.'
},
'update': {
'signature': 'update(delta_time)',
'description': 'Update the animation by the given time delta.',
'args': [('delta_time', 'float', 'Time elapsed since last update in seconds')],
'returns': 'bool: True if animation is still running, False if finished'
}
},
# Color methods
'Color': {
'from_hex': {
'signature': 'from_hex(hex_string)',
'description': 'Create a Color from a hexadecimal color string.',
'args': [('hex_string', 'str', 'Hex color string (e.g., "#FF0000" or "FF0000")')],
'returns': 'Color: New Color object from hex string',
'example': 'red = Color.from_hex("#FF0000")'
},
'to_hex': {
'signature': 'to_hex()',
'description': 'Convert this Color to a hexadecimal string.',
'returns': 'str: Hex color string in format "#RRGGBB"',
'example': 'hex_str = color.to_hex() # Returns "#FF0000"'
},
'lerp': {
'signature': 'lerp(other, t)',
'description': 'Linearly interpolate between this color and another.',
'args': [
('other', 'Color', 'The color to interpolate towards'),
('t', 'float', 'Interpolation factor from 0.0 to 1.0')
],
'returns': 'Color: New interpolated Color object',
'example': 'mixed = red.lerp(blue, 0.5) # 50% between red and blue'
}
},
# Vector methods
'Vector': {
'magnitude': {
'signature': 'magnitude()',
'description': 'Calculate the length/magnitude of this vector.',
'returns': 'float: The magnitude of the vector',
'example': 'length = vector.magnitude()'
},
'magnitude_squared': {
'signature': 'magnitude_squared()',
'description': 'Calculate the squared magnitude of this vector.',
'returns': 'float: The squared magnitude (faster than magnitude())',
'note': 'Use this for comparisons to avoid expensive square root calculation.'
},
'normalize': {
'signature': 'normalize()',
'description': 'Return a unit vector in the same direction.',
'returns': 'Vector: New normalized vector with magnitude 1.0',
'raises': 'ValueError: If vector has zero magnitude'
},
'dot': {
'signature': 'dot(other)',
'description': 'Calculate the dot product with another vector.',
'args': [('other', 'Vector', 'The other vector')],
'returns': 'float: Dot product of the two vectors'
},
'distance_to': {
'signature': 'distance_to(other)',
'description': 'Calculate the distance to another vector.',
'args': [('other', 'Vector', 'The other vector')],
'returns': 'float: Distance between the two vectors'
},
'angle': {
'signature': 'angle()',
'description': 'Get the angle of this vector in radians.',
'returns': 'float: Angle in radians from positive x-axis'
},
'copy': {
'signature': 'copy()',
'description': 'Create a copy of this vector.',
'returns': 'Vector: New Vector object with same x and y values'
}
},
# Scene methods
'Scene': {
'activate': {
'signature': 'activate()',
'description': 'Make this scene the active scene.',
'note': 'Equivalent to calling setScene() with this scene\'s name.'
},
'get_ui': {
'signature': 'get_ui()',
'description': 'Get the UI element collection for this scene.',
'returns': 'UICollection: Collection of all UI elements in this scene'
},
'keypress': {
'signature': 'keypress(handler)',
'description': 'Register a keyboard handler function for this scene.',
'args': [('handler', 'callable', 'Function that takes (key_name: str, is_pressed: bool)')],
'note': 'Alternative to overriding the on_keypress method.'
},
'register_keyboard': {
'signature': 'register_keyboard(callable)',
'description': 'Register a keyboard event handler function for the scene.',
'args': [('callable', 'callable', 'Function that takes (key: str, action: str) parameters')],
'note': 'Alternative to overriding the on_keypress method when subclassing Scene objects.',
'example': '''def handle_keyboard(key, action):
print(f"Key '{key}' was {action}")
if key == "q" and action == "press":
# Handle quit
pass
scene.register_keyboard(handle_keyboard)'''
}
},
# Timer methods
'Timer': {
'pause': {
'signature': 'pause()',
'description': 'Pause the timer, stopping its callback execution.',
'note': 'Use resume() to continue the timer from where it was paused.'
},
'resume': {
'signature': 'resume()',
'description': 'Resume a paused timer.',
'note': 'Has no effect if timer is not paused.'
},
'cancel': {
'signature': 'cancel()',
'description': 'Cancel the timer and remove it from the system.',
'note': 'After cancelling, the timer object cannot be reused.'
},
'restart': {
'signature': 'restart()',
'description': 'Restart the timer from the beginning.',
'note': 'Resets the timer\'s internal clock to zero.'
}
},
# Window methods
'Window': {
'get': {
'signature': 'get()',
'description': 'Get the Window singleton instance.',
'returns': 'Window: The singleton window object',
'note': 'This is a static method that returns the same instance every time.'
},
'center': {
'signature': 'center()',
'description': 'Center the window on the screen.',
'note': 'Only works if the window is not fullscreen.'
},
'screenshot': {
'signature': 'screenshot(filename)',
'description': 'Take a screenshot and save it to a file.',
'args': [('filename', 'str', 'Path where to save the screenshot')],
'note': 'Supports PNG, JPG, and BMP formats based on file extension.'
}
}
}
def get_complete_function_documentation():
"""Return complete documentation for ALL module functions."""
return {
# Scene Management
'createScene': {
'signature': 'createScene(name: str) -> None',
'description': 'Create a new empty scene with the given name.',
'args': [('name', 'str', 'Unique name for the new scene')],
'raises': 'ValueError: If a scene with this name already exists',
'note': 'The scene is created but not made active. Use setScene() to switch to it.',
'example': 'mcrfpy.createScene("game_over")'
},
'setScene': {
'signature': 'setScene(scene: str, transition: str = None, duration: float = 0.0) -> None',
'description': 'Switch to a different scene with optional transition effect.',
'args': [
('scene', 'str', 'Name of the scene to switch to'),
('transition', 'str', 'Transition type: "fade", "slide_left", "slide_right", "slide_up", "slide_down"'),
('duration', 'float', 'Transition duration in seconds (default: 0.0 for instant)')
],
'raises': 'KeyError: If the scene doesn\'t exist',
'example': 'mcrfpy.setScene("game", "fade", 0.5)'
},
'currentScene': {
'signature': 'currentScene() -> str',
'description': 'Get the name of the currently active scene.',
'returns': 'str: Name of the current scene',
'example': 'scene_name = mcrfpy.currentScene()'
},
'sceneUI': {
'signature': 'sceneUI(scene: str = None) -> UICollection',
'description': 'Get all UI elements for a scene.',
'args': [('scene', 'str', 'Scene name. If None, uses current scene')],
'returns': 'UICollection: All UI elements in the scene',
'raises': 'KeyError: If the specified scene doesn\'t exist',
'example': 'ui_elements = mcrfpy.sceneUI("game")'
},
'keypressScene': {
'signature': 'keypressScene(handler: callable) -> None',
'description': 'Set the keyboard event handler for the current scene.',
'args': [('handler', 'callable', 'Function that receives (key_name: str, is_pressed: bool)')],
'example': '''def on_key(key, pressed):
if key == "SPACE" and pressed:
player.jump()
mcrfpy.keypressScene(on_key)'''
},
# Audio Functions
'createSoundBuffer': {
'signature': 'createSoundBuffer(filename: str) -> int',
'description': 'Load a sound effect from a file and return its buffer ID.',
'args': [('filename', 'str', 'Path to the sound file (WAV, OGG, FLAC)')],
'returns': 'int: Buffer ID for use with playSound()',
'raises': 'RuntimeError: If the file cannot be loaded',
'example': 'jump_sound = mcrfpy.createSoundBuffer("assets/jump.wav")'
},
'loadMusic': {
'signature': 'loadMusic(filename: str, loop: bool = True) -> None',
'description': 'Load and immediately play background music from a file.',
'args': [
('filename', 'str', 'Path to the music file (WAV, OGG, FLAC)'),
('loop', 'bool', 'Whether to loop the music (default: True)')
],
'note': 'Only one music track can play at a time. Loading new music stops the current track.',
'example': 'mcrfpy.loadMusic("assets/background.ogg", True)'
},
'playSound': {
'signature': 'playSound(buffer_id: int) -> None',
'description': 'Play a sound effect using a previously loaded buffer.',
'args': [('buffer_id', 'int', 'Sound buffer ID returned by createSoundBuffer()')],
'raises': 'RuntimeError: If the buffer ID is invalid',
'example': 'mcrfpy.playSound(jump_sound)'
},
'getMusicVolume': {
'signature': 'getMusicVolume() -> int',
'description': 'Get the current music volume level.',
'returns': 'int: Current volume (0-100)',
'example': 'current_volume = mcrfpy.getMusicVolume()'
},
'getSoundVolume': {
'signature': 'getSoundVolume() -> int',
'description': 'Get the current sound effects volume level.',
'returns': 'int: Current volume (0-100)',
'example': 'current_volume = mcrfpy.getSoundVolume()'
},
'setMusicVolume': {
'signature': 'setMusicVolume(volume: int) -> None',
'description': 'Set the global music volume.',
'args': [('volume', 'int', 'Volume level from 0 (silent) to 100 (full volume)')],
'example': 'mcrfpy.setMusicVolume(50) # Set to 50% volume'
},
'setSoundVolume': {
'signature': 'setSoundVolume(volume: int) -> None',
'description': 'Set the global sound effects volume.',
'args': [('volume', 'int', 'Volume level from 0 (silent) to 100 (full volume)')],
'example': 'mcrfpy.setSoundVolume(75) # Set to 75% volume'
},
# UI Utilities
'find': {
'signature': 'find(name: str, scene: str = None) -> UIDrawable | None',
'description': 'Find the first UI element with the specified name.',
'args': [
('name', 'str', 'Exact name to search for'),
('scene', 'str', 'Scene to search in (default: current scene)')
],
'returns': 'UIDrawable or None: The found element, or None if not found',
'note': 'Searches scene UI elements and entities within grids.',
'example': 'button = mcrfpy.find("start_button")'
},
'findAll': {
'signature': 'findAll(pattern: str, scene: str = None) -> list',
'description': 'Find all UI elements matching a name pattern.',
'args': [
('pattern', 'str', 'Name pattern with optional wildcards (* matches any characters)'),
('scene', 'str', 'Scene to search in (default: current scene)')
],
'returns': 'list: All matching UI elements and entities',
'example': 'enemies = mcrfpy.findAll("enemy_*")'
},
# System Functions
'exit': {
'signature': 'exit() -> None',
'description': 'Cleanly shut down the game engine and exit the application.',
'note': 'This immediately closes the window and terminates the program.',
'example': 'mcrfpy.exit()'
},
'getMetrics': {
'signature': 'getMetrics() -> dict',
'description': 'Get current performance metrics.',
'returns': '''dict: Performance data with keys:
- frame_time: Last frame duration in seconds
- avg_frame_time: Average frame time
- fps: Frames per second
- draw_calls: Number of draw calls
- ui_elements: Total UI element count
- visible_elements: Visible element count
- current_frame: Frame counter
- runtime: Total runtime in seconds''',
'example': 'metrics = mcrfpy.getMetrics()'
},
'setTimer': {
'signature': 'setTimer(name: str, handler: callable, interval: int) -> None',
'description': 'Create or update a recurring timer.',
'args': [
('name', 'str', 'Unique identifier for the timer'),
('handler', 'callable', 'Function called with (runtime: float) parameter'),
('interval', 'int', 'Time between calls in milliseconds')
],
'note': 'If a timer with this name exists, it will be replaced.',
'example': '''def update_score(runtime):
score += 1
mcrfpy.setTimer("score_update", update_score, 1000)'''
},
'delTimer': {
'signature': 'delTimer(name: str) -> None',
'description': 'Stop and remove a timer.',
'args': [('name', 'str', 'Timer identifier to remove')],
'note': 'No error is raised if the timer doesn\'t exist.',
'example': 'mcrfpy.delTimer("score_update")'
},
'setScale': {
'signature': 'setScale(multiplier: float) -> None',
'description': 'Scale the game window size.',
'args': [('multiplier', 'float', 'Scale factor (e.g., 2.0 for double size)')],
'note': 'The internal resolution remains 1024x768, but the window is scaled.',
'example': 'mcrfpy.setScale(2.0) # Double the window size'
}
}
def get_complete_property_documentation():
"""Return complete documentation for ALL properties."""
return {
'Animation': {
'property': 'str: Name of the property being animated (e.g., "x", "y", "scale")',
'duration': 'float: Total duration of the animation in seconds',
'elapsed_time': 'float: Time elapsed since animation started (read-only)',
'current_value': 'float: Current interpolated value of the animation (read-only)',
'is_running': 'bool: True if animation is currently running (read-only)',
'is_finished': 'bool: True if animation has completed (read-only)'
},
'GridPoint': {
'x': 'int: Grid x coordinate of this point',
'y': 'int: Grid y coordinate of this point',
'texture_index': 'int: Index of the texture/sprite to display at this point',
'solid': 'bool: Whether this point blocks movement',
'transparent': 'bool: Whether this point allows light/vision through',
'color': 'Color: Color tint applied to the texture at this point'
},
'GridPointState': {
'visible': 'bool: Whether this point is currently visible to the player',
'discovered': 'bool: Whether this point has been discovered/explored',
'custom_flags': 'int: Bitfield for custom game-specific flags'
}
}
def generate_complete_html_documentation():
"""Generate complete HTML documentation with NO missing methods."""
# Get all documentation data
method_docs = get_complete_method_documentation()
function_docs = get_complete_function_documentation()
property_docs = get_complete_property_documentation()
html_parts = []
# HTML header with enhanced styling
html_parts.append('''<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>McRogueFace API Reference - Complete Documentation</title>
<style>
body {
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
line-height: 1.6;
color: #333;
max-width: 1200px;
margin: 0 auto;
padding: 20px;
background: #f8f9fa;
}
.container {
background: white;
padding: 30px;
border-radius: 8px;
box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}
h1 {
color: #2c3e50;
border-bottom: 3px solid #3498db;
padding-bottom: 15px;
margin-bottom: 30px;
}
h2 {
color: #34495e;
border-bottom: 2px solid #ecf0f1;
padding-bottom: 10px;
margin-top: 40px;
}
h3 {
color: #2c3e50;
margin-top: 30px;
}
h4 {
color: #34495e;
margin-top: 20px;
font-size: 1.1em;
}
h5 {
color: #555;
margin-top: 15px;
font-size: 1em;
}
code {
background: #f4f4f4;
padding: 2px 6px;
border-radius: 3px;
font-family: "SF Mono", Monaco, "Cascadia Code", "Roboto Mono", Consolas, monospace;
font-size: 0.9em;
}
pre {
background: #f8f8f8;
border: 1px solid #e1e4e8;
border-radius: 6px;
padding: 16px;
overflow-x: auto;
margin: 15px 0;
}
pre code {
background: none;
padding: 0;
font-size: 0.875em;
line-height: 1.45;
}
.class-name {
color: #8e44ad;
font-weight: bold;
}
.property {
color: #27ae60;
font-weight: 600;
}
.method {
color: #2980b9;
font-weight: 600;
}
.function-signature {
color: #d73a49;
font-weight: 600;
}
.method-section {
margin: 20px 0;
padding: 15px;
background: #f8f9fa;
border-radius: 6px;
border-left: 4px solid #3498db;
}
.arg-list {
margin: 10px 0;
}
.arg-item {
margin: 8px 0;
padding: 8px;
background: #fff;
border-radius: 4px;
border: 1px solid #e1e4e8;
}
.arg-name {
color: #d73a49;
font-weight: 600;
}
.arg-type {
color: #6f42c1;
font-style: italic;
}
.returns {
background: #e8f5e8;
padding: 10px;
border-radius: 4px;
border-left: 4px solid #28a745;
margin: 10px 0;
}
.note {
background: #fff3cd;
padding: 10px;
border-radius: 4px;
border-left: 4px solid #ffc107;
margin: 10px 0;
}
.example {
background: #e7f3ff;
padding: 15px;
border-radius: 4px;
border-left: 4px solid #0366d6;
margin: 15px 0;
}
.toc {
background: #f8f9fa;
border: 1px solid #e1e4e8;
border-radius: 6px;
padding: 20px;
margin: 20px 0;
}
.toc ul {
list-style: none;
padding-left: 0;
}
.toc li {
margin: 8px 0;
}
.toc a {
color: #3498db;
text-decoration: none;
font-weight: 500;
}
.toc a:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div class="container">
''')
# Title and overview
html_parts.append('<h1>McRogueFace API Reference - Complete Documentation</h1>')
html_parts.append(f'<p><em>Generated on {datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")}</em></p>')
# Table of contents
html_parts.append('<div class="toc">')
html_parts.append('<h2>Table of Contents</h2>')
html_parts.append('<ul>')
html_parts.append('<li><a href="#functions">Functions</a></li>')
html_parts.append('<li><a href="#classes">Classes</a></li>')
html_parts.append('<li><a href="#automation">Automation Module</a></li>')
html_parts.append('</ul>')
html_parts.append('</div>')
# Functions section
html_parts.append('<h2 id="functions">Functions</h2>')
# Group functions by category
categories = {
'Scene Management': ['createScene', 'setScene', 'currentScene', 'sceneUI', 'keypressScene'],
'Audio': ['createSoundBuffer', 'loadMusic', 'playSound', 'getMusicVolume', 'getSoundVolume', 'setMusicVolume', 'setSoundVolume'],
'UI Utilities': ['find', 'findAll'],
'System': ['exit', 'getMetrics', 'setTimer', 'delTimer', 'setScale']
}
for category, functions in categories.items():
html_parts.append(f'<h3>{category}</h3>')
for func_name in functions:
if func_name in function_docs:
html_parts.append(format_function_html(func_name, function_docs[func_name]))
# Classes section
html_parts.append('<h2 id="classes">Classes</h2>')
# Get all classes from mcrfpy
classes = []
for name in sorted(dir(mcrfpy)):
if not name.startswith('_'):
obj = getattr(mcrfpy, name)
if isinstance(obj, type):
classes.append((name, obj))
# Generate class documentation
for class_name, cls in classes:
html_parts.append(format_class_html_complete(class_name, cls, method_docs, property_docs))
# Automation section
if hasattr(mcrfpy, 'automation'):
html_parts.append('<h2 id="automation">Automation Module</h2>')
html_parts.append('<p>The <code>mcrfpy.automation</code> module provides testing and automation capabilities.</p>')
automation = mcrfpy.automation
for name in sorted(dir(automation)):
if not name.startswith('_'):
obj = getattr(automation, name)
if callable(obj):
html_parts.append(f'<div class="method-section">')
html_parts.append(f'<h4><code class="function-signature">automation.{name}</code></h4>')
if obj.__doc__:
doc_parts = obj.__doc__.split(' - ')
if len(doc_parts) > 1:
html_parts.append(f'<p>{escape_html(doc_parts[1])}</p>')
else:
html_parts.append(f'<p>{escape_html(obj.__doc__)}</p>')
html_parts.append('</div>')
html_parts.append('</div>')
html_parts.append('</body>')
html_parts.append('</html>')
return '\n'.join(html_parts)
def format_function_html(func_name, func_doc):
"""Format a function with complete documentation."""
html_parts = []
html_parts.append('<div class="method-section">')
html_parts.append(f'<h4><code class="function-signature">{func_doc["signature"]}</code></h4>')
html_parts.append(f'<p>{escape_html(func_doc["description"])}</p>')
# Arguments
if 'args' in func_doc:
html_parts.append('<div class="arg-list">')
html_parts.append('<h5>Arguments:</h5>')
for arg in func_doc['args']:
html_parts.append('<div class="arg-item">')
html_parts.append(f'<span class="arg-name">{arg[0]}</span> ')
html_parts.append(f'<span class="arg-type">({arg[1]})</span>: ')
html_parts.append(f'{escape_html(arg[2])}')
html_parts.append('</div>')
html_parts.append('</div>')
# Returns
if 'returns' in func_doc:
html_parts.append('<div class="returns">')
html_parts.append(f'<strong>Returns:</strong> {escape_html(func_doc["returns"])}')
html_parts.append('</div>')
# Raises
if 'raises' in func_doc:
html_parts.append('<div class="note">')
html_parts.append(f'<strong>Raises:</strong> {escape_html(func_doc["raises"])}')
html_parts.append('</div>')
# Note
if 'note' in func_doc:
html_parts.append('<div class="note">')
html_parts.append(f'<strong>Note:</strong> {escape_html(func_doc["note"])}')
html_parts.append('</div>')
# Example
if 'example' in func_doc:
html_parts.append('<div class="example">')
html_parts.append('<h5>Example:</h5>')
html_parts.append('<pre><code>')
html_parts.append(escape_html(func_doc['example']))
html_parts.append('</code></pre>')
html_parts.append('</div>')
html_parts.append('</div>')
return '\n'.join(html_parts)
def format_class_html_complete(class_name, cls, method_docs, property_docs):
"""Format a class with complete documentation."""
html_parts = []
html_parts.append('<div class="method-section">')
html_parts.append(f'<h3><span class="class-name">{class_name}</span></h3>')
# Class description
if cls.__doc__:
html_parts.append(f'<p>{escape_html(cls.__doc__)}</p>')
# Properties
if class_name in property_docs:
html_parts.append('<h4>Properties:</h4>')
for prop_name, prop_desc in property_docs[class_name].items():
html_parts.append(f'<div class="arg-item">')
html_parts.append(f'<span class="property">{prop_name}</span>: {escape_html(prop_desc)}')
html_parts.append('</div>')
# Methods
methods_to_document = []
# Add inherited methods for UI classes
if any(base.__name__ == 'Drawable' for base in cls.__bases__ if hasattr(base, '__name__')):
methods_to_document.extend(['get_bounds', 'move', 'resize'])
# Add class-specific methods
if class_name in method_docs:
methods_to_document.extend(method_docs[class_name].keys())
# Add methods from introspection
for attr_name in dir(cls):
if not attr_name.startswith('_') and callable(getattr(cls, attr_name)):
if attr_name not in methods_to_document:
methods_to_document.append(attr_name)
if methods_to_document:
html_parts.append('<h4>Methods:</h4>')
for method_name in set(methods_to_document):
# Get method documentation
method_doc = None
if class_name in method_docs and method_name in method_docs[class_name]:
method_doc = method_docs[class_name][method_name]
elif method_name in method_docs.get('Drawable', {}):
method_doc = method_docs['Drawable'][method_name]
if method_doc:
html_parts.append(format_method_html(method_name, method_doc))
else:
# Basic method with no documentation
html_parts.append(f'<div class="arg-item">')
html_parts.append(f'<span class="method">{method_name}(...)</span>')
html_parts.append('</div>')
html_parts.append('</div>')
return '\n'.join(html_parts)
def format_method_html(method_name, method_doc):
"""Format a method with complete documentation."""
html_parts = []
html_parts.append('<div style="margin-left: 20px; margin-bottom: 15px;">')
html_parts.append(f'<h5><code class="method">{method_doc["signature"]}</code></h5>')
html_parts.append(f'<p>{escape_html(method_doc["description"])}</p>')
# Arguments
if 'args' in method_doc:
for arg in method_doc['args']:
html_parts.append(f'<div style="margin-left: 20px;">')
html_parts.append(f'<span class="arg-name">{arg[0]}</span> ')
html_parts.append(f'<span class="arg-type">({arg[1]})</span>: ')
html_parts.append(f'{escape_html(arg[2])}')
html_parts.append('</div>')
# Returns
if 'returns' in method_doc:
html_parts.append(f'<div style="margin-left: 20px; color: #28a745;">')
html_parts.append(f'<strong>Returns:</strong> {escape_html(method_doc["returns"])}')
html_parts.append('</div>')
# Note
if 'note' in method_doc:
html_parts.append(f'<div style="margin-left: 20px; color: #856404;">')
html_parts.append(f'<strong>Note:</strong> {escape_html(method_doc["note"])}')
html_parts.append('</div>')
# Example
if 'example' in method_doc:
html_parts.append(f'<div style="margin-left: 20px;">')
html_parts.append('<strong>Example:</strong>')
html_parts.append('<pre><code>')
html_parts.append(escape_html(method_doc['example']))
html_parts.append('</code></pre>')
html_parts.append('</div>')
html_parts.append('</div>')
return '\n'.join(html_parts)
def main():
"""Generate complete HTML documentation with zero missing methods."""
print("Generating COMPLETE HTML API documentation...")
# Generate HTML
html_content = generate_complete_html_documentation()
# Write to file
output_path = Path("docs/api_reference_complete.html")
output_path.parent.mkdir(exist_ok=True)
with open(output_path, 'w', encoding='utf-8') as f:
f.write(html_content)
print(f"✓ Generated {output_path}")
print(f" File size: {len(html_content):,} bytes")
# Count "..." instances
ellipsis_count = html_content.count('...')
print(f" Ellipsis instances: {ellipsis_count}")
if ellipsis_count == 0:
print("✅ SUCCESS: No missing documentation found!")
else:
print(f"❌ WARNING: {ellipsis_count} methods still need documentation")
if __name__ == '__main__':
main()