Directory structure cleanup and organization overhaul

README.md

@@ -3,19 +3,27 @@
 
 A Python-powered 2D game engine for creating roguelike games, built with C++ and SFML.
 
+* Core roguelike logic from libtcod: field of view, pathfinding
+* Animate sprites with multiple frames. Smooth transitions for positions, sizes, zoom, and camera
+* 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.
 
-## Tenets
-
-- **Python & C++ Hand-in-Hand**: Create your game without ever recompiling. Your Python commands create C++ objects, and animations can occur without calling Python at all.
-- **Simple Yet Flexible UI System**: Sprites, Grids, Frames, and Captions with full animation support
-- **Entity-Component Architecture**: Implement your game objects with Python integration
-- **Built-in Roguelike Support**: Dungeon generation, pathfinding, and field-of-view via libtcod (demos still under construction)
-- **Automation API**: PyAutoGUI-inspired event generation framework. All McRogueFace interactions can be performed headlessly via script: for software testing or AI integration
-- **Interactive Development**: Python REPL integration for live game debugging. Use `mcrogueface` like a Python interpreter
-
 ## Quick Start
 
+**Download**: 
+
+- 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
+
 ```bash
 # Clone and build
 git clone <wherever you found this repo>
@@ -49,28 +57,59 @@ mcrfpy.setScene("intro")
 
 ## Documentation
 
+### 📚 Full Documentation Site
+
 For comprehensive documentation, tutorials, and API reference, visit:
 **[https://mcrogueface.github.io](https://mcrogueface.github.io)**
 
-## Requirements
+The documentation site includes:
+
+- **[Quickstart Guide](https://mcrogueface.github.io/quickstart/)** - Get running in 5 minutes
+- **[McRogueFace Does The Entire Roguelike Tutorial](https://mcrogueface.github.io/tutorials/)** - Step-by-step game building
+- **[Complete API Reference](https://mcrogueface.github.io/api/)** - Every function documented
+- **[Cookbook](https://mcrogueface.github.io/cookbook/)** - Ready-to-use code recipes
+- **[C++ Extension Guide](https://mcrogueface.github.io/extending-cpp/)** - For C++ developers: Add engine features
+
+## Build Requirements
 
 - C++17 compiler (GCC 7+ or Clang 5+)
 - CMake 3.14+
 - Python 3.12+
-- SFML 2.5+
+- SFML 2.6
 - Linux or Windows (macOS untested)
 
 ## Project Structure
 
 ```
 McRogueFace/
-├── src/           # C++ engine source
-├── scripts/       # Python game scripts
 ├── assets/        # Sprites, fonts, audio
-├── build/         # Build output directory
+├── 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
+├── src/           # C++ engine source
+│   └─ scripts/    # Python game scripts (copied during build)
 └── tests/         # Automated test suite
+└── tools/         # For the McRogueFace ecosystem: docs generation
 ```
 
+If you are building McRogueFace to implement game logic or scene configuration in C++, you'll have to compile the project.
+
+If you are writing a game in Python using McRogueFace, you only need to rename and zip/distribute the `build` directory.
+
+## Philosophy
+
+- **C++ every frame, Python every tick**: All rendering data is handled in C++. Structure your UI and program animations in Python, and they are rendered without Python. All game logic can be written in Python.
+- **No Compiling Required; Zip And Ship**: Implement your game objects with Python, zip up McRogueFace with your "game.py" to ship
+- **Built-in Roguelike Support**: Dungeon generation, pathfinding, and field-of-view via libtcod 
+- **Hands-Off Testing**: PyAutoGUI-inspired event generation framework. All McRogueFace interactions can be performed headlessly via script: for software testing or AI integration
+- **Interactive Development**: Python REPL integration for live game debugging. Use `mcrogueface` like a Python interpreter
+
 ## Contributing
 
 PRs will be considered! Please include explicit mention that your contribution is your own work and released under the MIT license in the pull request.