From a4217b49d7dc0e1ae088a3c3f73e474ba42eced0 Mon Sep 17 00:00:00 2001 From: John McCardle Date: Wed, 21 Jan 2026 21:34:13 -0500 Subject: [PATCH] README.md updates: closes #168 --- README.md | 132 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 88 insertions(+), 44 deletions(-) diff --git a/README.md b/README.md index 153ed5d..f608e37 100644 --- a/README.md +++ b/README.md @@ -8,33 +8,64 @@ A Python-powered 2D game engine for creating roguelike games, built with C++ and * Simple GUI element system allows keyboard and mouse input, composition * No compilation or installation necessary. The runtime is a full Python environment; "Zip And Ship" -![ Image ]() - -**Pre-Alpha Release Demo**: my 7DRL 2025 entry *"Crypt of Sokoban"* - a prototype with buttons, boulders, enemies, and items. +📖 **[Full Documentation & Tutorials](https://mcrogueface.github.io/)** - Quickstart guide, API reference, and cookbook ## Quick Start -**Download**: +**Download** the [latest release](https://github.com/jmccardle/McRogueFace/releases/latest): +- **Windows**: `McRogueFace-*-Win.zip` +- **Linux**: `McRogueFace-*-Linux.tar.bz2` -- The entire McRogueFace visual framework: - - **Sprite**: an image file or one sprite from a shared sprite sheet - - **Caption**: load a font, display text - - **Frame**: A rectangle; put other things on it to move or manage GUIs as modules - - **Grid**: A 2D array of tiles with zoom + position control - - **Entity**: Lives on a Grid, displays a sprite, and can have a perspective or move along a path - - **Animation**: Change any property on any of the above over time +Extract and run `mcrogueface` (or `mcrogueface.exe` on Windows) to see the demo game. -```bash -# Clone and build -git clone -cd McRogueFace -make +### Your First Game -# Run the example game -cd build -./mcrogueface +Create `scripts/game.py` (or edit the existing one): + +```python +import mcrfpy + +# Create and activate a scene +scene = mcrfpy.Scene("game") +scene.activate() + +# Load a sprite sheet +texture = mcrfpy.Texture("assets/kenney_tinydungeon.png", 16, 16) + +# Create a tile grid +grid = mcrfpy.Grid(grid_size=(20, 15), texture=texture, pos=(50, 50), size=(640, 480)) +grid.zoom = 2.0 +scene.children.append(grid) + +# Add a player entity +player = mcrfpy.Entity(pos=(10, 7), texture=texture, sprite_index=84) +grid.entities.append(player) + +# Handle keyboard input +def on_key(key, state): + if state != "start": + return + x, y = int(player.x), int(player.y) + if key == "W": y -= 1 + elif key == "S": y += 1 + elif key == "A": x -= 1 + elif key == "D": x += 1 + player.x, player.y = x, y + +scene.on_key = on_key ``` +Run `mcrogueface` and you have a movable character! + +### Visual Framework + +- **Sprite**: Single image or sprite from a shared sheet +- **Caption**: Text rendering with fonts +- **Frame**: Container rectangle for composing UIs +- **Grid**: 2D tile array with zoom and camera control +- **Entity**: Grid-based game object with sprite and pathfinding +- **Animation**: Interpolate any property over time with easing + ## Building from Source For most users, pre-built releases are available. If you need to build from source: @@ -72,24 +103,38 @@ cd McRogueFace - **Windows**: Supported (see build guide for details) - **macOS**: Untested -## Example: Creating a Simple Scene +## Example: Main Menu with Buttons ```python import mcrfpy -# Create a new scene -intro = mcrfpy.Scene("intro") +# Create a scene +scene = mcrfpy.Scene("menu") -# Add a text caption -caption = mcrfpy.Caption((50, 50), "Welcome to McRogueFace!") -caption.size = 48 -caption.fill_color = (255, 255, 255) +# Add a background frame +bg = mcrfpy.Frame(pos=(0, 0), size=(1024, 768), + fill_color=mcrfpy.Color(20, 20, 40)) +scene.children.append(bg) -# Add to scene -intro.children.append(caption) +# Add a title +title = mcrfpy.Caption(pos=(312, 100), text="My Roguelike", + fill_color=mcrfpy.Color(255, 255, 100)) +title.font_size = 48 +scene.children.append(title) -# Switch to the scene -intro.activate() +# Create a button +button = mcrfpy.Frame(pos=(362, 300), size=(300, 80), + fill_color=mcrfpy.Color(50, 150, 50)) +button_text = mcrfpy.Caption(pos=(90, 25), text="Start Game") +button.children.append(button_text) + +def on_click(x, y, btn): + print("Game starting!") + +button.on_click = on_click +scene.children.append(button) + +scene.activate() ``` ## Documentation @@ -121,28 +166,27 @@ In the repository root: - C++17 compiler (GCC 7+ or Clang 5+) - CMake 3.14+ -- Python 3.12+ +- Python 3.14 (embedded) - SFML 2.6 - Linux or Windows (macOS untested) +See [BUILD_FROM_SOURCE.md](BUILD_FROM_SOURCE.md) for detailed compilation instructions. + ## Project Structure ``` McRogueFace/ ├── assets/ # Sprites, fonts, audio -├── build/ # Build output directory: zip + ship -│ ├─ (*)assets/ # (copied location of assets) -│ ├─ (*)scripts/ # (copied location of src/scripts) -│ └─ lib/ # SFML, TCOD libraries, Python + standard library / modules -├── deps/ # Python, SFML, and libtcod imports can be tossed in here to build -│ └─ platform/ # windows, linux subdirectories for OS-specific cpython config -├── docs/ # generated HTML, markdown docs -│ └─ stubs/ # .pyi files for editor integration -├── modules/ # git submodules, to build all of McRogueFace's dependencies from source +├── build/ # Build output: this is what you distribute +│ ├── assets/ # (copied from assets/) +│ ├── scripts/ # (copied from src/scripts/) +│ └── lib/ # Python stdlib and extension modules +├── docs/ # Generated HTML, markdown API docs ├── src/ # C++ engine source -│ └─ scripts/ # Python game scripts (copied during build) -└── tests/ # Automated test suite -└── tools/ # For the McRogueFace ecosystem: docs generation +│ └── scripts/ # Python game scripts +├── stubs/ # .pyi type stubs for IDE integration +├── tests/ # Automated test suite +└── tools/ # Documentation generation scripts ``` If you are building McRogueFace to implement game logic or scene configuration in C++, you'll have to compile the project. @@ -177,6 +221,6 @@ This project is licensed under the MIT License - see LICENSE file for details. ## Acknowledgments -- Developed for 7-Day Roguelike 2023, 2024, 2025 - here's to many more +- Developed for 7-Day Roguelike 2023, 2024, 2025, 2026 - here's to many more - Built with [SFML](https://www.sfml-dev.org/), [libtcod](https://github.com/libtcod/libtcod), and Python - Inspired by David Churchill's COMP4300 game engine lectures