From aa3c35bd2ff2f96eb3402e7c67458befa29b9d57 Mon Sep 17 00:00:00 2001 From: StillHammer Date: Thu, 15 Jan 2026 09:26:23 +0700 Subject: [PATCH] docs: Update all documentation to reflect development stage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit COMPREHENSIVE DOCUMENTATION CLEANUP: DEVELOPER_GUIDE.md: - Add prominent warning at top (development-ready, NOT production-ready) - New 'Current Limitations' section with detailed warnings: * Non-deterministic execution * Single-threaded only * Not suitable for networked games * No error recovery, limited optimizations - Change all 'Production Ready' → 'Development Ready' status tags - BgfxRenderer: Phase 8 complete | Experimental - UIModule: Phase 7 complete | Experimental - InputModule: Phase 1-3 complete | Gamepad Phase 2 TODO - Add 'What GroveEngine IS Good For' section (prototyping, learning, AI-assisted dev) - Add Production Roadmap section USER_GUIDE.md: - Add experimental/development warning with link to README Module READMEs: - BgfxRenderer/README.md: Add development stage warning - InputModule/README.md: Clarify Phase 1-3 complete, gamepad TODO - UIModule/README.md: Add experimental warning, clarify thread-safe design is for future All documentation now consistently reflects that GroveEngine is: ✅ Excellent for rapid prototyping and experimentation ⚠️ NOT ready for production games ⚠️ Non-deterministic execution ⚠️ Single-threaded only (for now) Total changes: 5 files, 62 insertions, 13 deletions --- docs/DEVELOPER_GUIDE.md | 63 ++++++++++++++++++++++++++++------ docs/USER_GUIDE.md | 2 ++ modules/BgfxRenderer/README.md | 2 ++ modules/InputModule/README.md | 4 ++- modules/UIModule/README.md | 4 ++- 5 files changed, 62 insertions(+), 13 deletions(-) diff --git a/docs/DEVELOPER_GUIDE.md b/docs/DEVELOPER_GUIDE.md index 25a25a8..e99c18a 100644 --- a/docs/DEVELOPER_GUIDE.md +++ b/docs/DEVELOPER_GUIDE.md @@ -2,18 +2,59 @@ **Comprehensive guide for building applications with GroveEngine** +⚠️ **IMPORTANT**: GroveEngine is currently in **development stage** - suitable for prototyping and experimentation, **not production games**. The engine is non-deterministic and optimized for rapid iteration, not stability. See [Current Limitations](#current-limitations) below. + ## Table of Contents -1. [Getting Started](#getting-started) -2. [Core System](#core-system) -3. [Available Modules](#available-modules) +1. [Current Limitations](#current-limitations) +2. [Getting Started](#getting-started) +3. [Core System](#core-system) +4. [Available Modules](#available-modules) - [BgfxRenderer - 2D Rendering](#bgfxrenderer---2d-rendering) - [UIModule - User Interface](#uimodule---user-interface) - [InputModule - Input Handling](#inputmodule---input-handling) -4. [IIO Topics Reference](#iio-topics-reference) -5. [Complete Application Example](#complete-application-example) -6. [Building Your First Game](#building-your-first-game) -7. [Advanced Topics](#advanced-topics) +5. [IIO Topics Reference](#iio-topics-reference) +6. [Complete Application Example](#complete-application-example) +7. [Building Your First Game](#building-your-first-game) +8. [Advanced Topics](#advanced-topics) + +--- + +## Current Limitations + +⚠️ **GroveEngine is EXPERIMENTAL and NOT production-ready.** Understand these limitations before building with it: + +### Non-Deterministic Execution +- **Module execution order is NOT guaranteed** - modules may run in different orders between frames +- **Not suitable for networked games** - no deterministic replay or synchronization +- **Race conditions possible** - only SequentialModuleSystem is currently implemented (single-threaded) + +### Development Stage +- **Optimized for rapid iteration**, not stability +- **No error recovery** - crashes are not handled gracefully +- **Limited performance optimizations** - no profiling, memory pooling, or SIMD +- **Single-threaded only** - ThreadedModuleSystem and MultithreadedModuleSystem are TODO + +### Module Limitations +- **InputModule**: Mouse and keyboard only (gamepad Phase 2 not implemented) +- **BgfxRenderer**: Basic text rendering only (8x8 bitmap font for debug) +- **UIModule**: Functional but no advanced layout constraints + +### What GroveEngine IS Good For +✅ **Rapid prototyping** - 0.4ms hot-reload for instant iteration +✅ **Learning modular architecture** - clean interface-based design +✅ **AI-assisted development** - 200-300 line modules optimized for Claude Code +✅ **Experimentation** - test game ideas quickly + +### Production Roadmap +To make GroveEngine production-ready, the following is needed: +- Deterministic execution guarantees +- Error recovery and graceful degradation +- Multi-threaded module systems +- Performance profiling and optimization +- Network IO and distributed messaging +- Complete gamepad support +- Advanced text rendering --- @@ -84,7 +125,7 @@ GroveEngine uses a **module-based architecture** with hot-reload support: ### BgfxRenderer - 2D Rendering -**Status:** ✅ Production Ready (Phase 7-8 complete) +**Status:** ✅ Development Ready (Phase 8 complete) | ⚠️ Non-deterministic, experimental Multi-backend 2D renderer using bgfx (DirectX 11/12, OpenGL, Vulkan, Metal). @@ -163,7 +204,7 @@ io->publish("render:camera", std::move(camera)); ### UIModule - User Interface -**Status:** ✅ Production Ready (Phase 7 complete) +**Status:** ✅ Development Ready (Phase 7 complete) | ⚠️ Experimental Complete UI widget system with layout, scrolling, and tooltips. @@ -267,9 +308,9 @@ UIModule publishes render commands to BgfxRenderer via `UIRenderer`: ### InputModule - Input Handling -**Status:** ✅ Production Ready (Phase 1 complete) +**Status:** ✅ Development Ready (Phase 1-3 complete) | ⚠️ Gamepad Phase 2 TODO -Cross-platform input handling with SDL2 backend (mouse, keyboard, gamepad). +Cross-platform input handling with SDL2 backend (mouse, keyboard). #### Features diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md index f3545bb..53984b7 100644 --- a/docs/USER_GUIDE.md +++ b/docs/USER_GUIDE.md @@ -2,6 +2,8 @@ GroveEngine is a C++17 hot-reload module system designed for building modular applications with runtime code replacement capabilities. +⚠️ **IMPORTANT**: GroveEngine is **experimental** and **development-ready**, NOT production-ready. It is non-deterministic and optimized for rapid prototyping. See main [README.md](../README.md#current-status) for full limitations. + ## Table of Contents 1. [Overview](#overview) diff --git a/modules/BgfxRenderer/README.md b/modules/BgfxRenderer/README.md index 14c869a..7995ca3 100644 --- a/modules/BgfxRenderer/README.md +++ b/modules/BgfxRenderer/README.md @@ -1,5 +1,7 @@ # BgfxRenderer Module +⚠️ **Development Stage**: Experimental, non-deterministic. See [main README](../../README.md#current-status) for limitations. + Module de rendu 2D pour GroveEngine, basé sur [bgfx](https://github.com/bkaradzic/bgfx). ## Features diff --git a/modules/InputModule/README.md b/modules/InputModule/README.md index ba9f465..d79cbb1 100644 --- a/modules/InputModule/README.md +++ b/modules/InputModule/README.md @@ -1,6 +1,8 @@ # InputModule -Module de capture et conversion d'événements d'entrée (clavier, souris, gamepad) vers le système IIO de GroveEngine. +⚠️ **Development Stage**: Phase 1-3 complete (mouse, keyboard). Gamepad support is Phase 2 (TODO). See [main README](../../README.md#current-status). + +Module de capture et conversion d'événements d'entrée (clavier, souris) vers le système IIO de GroveEngine. ## Vue d'ensemble diff --git a/modules/UIModule/README.md b/modules/UIModule/README.md index 3c75f6c..1a31c4f 100644 --- a/modules/UIModule/README.md +++ b/modules/UIModule/README.md @@ -1,5 +1,7 @@ # UIModule +⚠️ **Development Stage**: Experimental, part of non-deterministic engine. See [main README](../../README.md#current-status) for limitations. + Complete UI widget system for GroveEngine with layout, scrolling, tooltips, and automatic input handling. ## Features @@ -10,7 +12,7 @@ Complete UI widget system for GroveEngine with layout, scrolling, tooltips, and - **Retained Mode Rendering**: Widgets cache state, reducing IIO traffic by 85%+ - **Layer Management**: UI renders on top of game content (layer 1000+) - **Hot-Reload Support**: Full state preservation across module reloads -- **Thread-Safe**: Designed for multi-threaded production architecture +- **Thread-Safe Design**: Architecture ready for future multi-threaded systems (currently single-threaded only) ## Quick Start