Refactor/modular engine build

.gitignore

@@ -0,0 +1 @@
+site/

docs/api_reference/core/engine.md

@@ -30,54 +30,63 @@ namespace pixelroot32::core {
 Creates a new engine instance with custom display, input, and audio configurations. Uses move semantics for DisplayConfig to transfer ownership of resources (like custom draw surfaces).
 
 **Parameters:**
+
 - `displayConfig` (`pixelroot32::graphics::DisplayConfig&&`): Configuration settings for the display (r-value reference)
 - `inputConfig` (const `pixelroot32::input::InputConfig&`): Configuration settings for the input system
 - `audioConfig` (const `pixelroot32::audio::AudioConfig&`): Configuration settings for the audio system
 
-### Engine(const DisplayConfig& displayConfig, const InputConfig& inputConfig, const AudioConfig& audioConfig)
+### Engine(DisplayConfig&& displayConfig, const InputConfig& inputConfig, const AudioConfig& audioConfig)
 
-Creates a new engine instance by copying configurations. Note that copying DisplayConfig will not copy custom draw surfaces (they are unique_ptr).
+Creates a new engine instance with custom display, input, and audio configurations. Uses move semantics for DisplayConfig to transfer ownership of resources (like custom draw surfaces).
 
 **Parameters:**
-- `displayConfig` (const `pixelroot32::graphics::DisplayConfig&`): Configuration settings for the display
+
+- `displayConfig` (`pixelroot32::graphics::DisplayConfig&&`): Configuration settings for the display (r-value reference)
 - `inputConfig` (const `pixelroot32::input::InputConfig&`): Configuration settings for the input system
 - `audioConfig` (const `pixelroot32::audio::AudioConfig&`): Configuration settings for the audio system
 
 **Example:**
+
 ```cpp
 #include "core/Engine.h"
 #include "graphics/DisplayConfig.h"
 
 // Example with move semantics (recommended for custom displays)
-auto displayConfig = PIXELROOT32_CUSTOM_DISPLAY(std::make_unique<MyCustomDriver>().release(), 240, 240);
+auto displayConfig = PIXELROOT32_CUSTOM_DISPLAY(new MyCustomDriver(), 240, 240);
 pixelroot32::core::Engine engine(std::move(displayConfig), inputConfig, audioConfig);
 ```
 
-### Engine(const DisplayConfig& displayConfig, const InputConfig& inputConfig)
+### Engine(DisplayConfig&& displayConfig, const InputConfig& inputConfig)
 
 Creates a new engine instance with custom display and input configurations, using default audio settings.
 
 **Parameters:**
-- `displayConfig` (const `pixelroot32::graphics::DisplayConfig&`): Configuration settings for the display
+
+- `displayConfig` (`pixelroot32::graphics::DisplayConfig&&`): Configuration settings for the display (r-value reference)
 - `inputConfig` (const `pixelroot32::input::InputConfig&`): Configuration settings for the input system
 
 **Example:**
+
 ```cpp
-pixelroot32::core::Engine engine(displayConfig, inputConfig);
+auto displayConfig = /* ... */;
+pixelroot32::core::Engine engine(std::move(displayConfig), inputConfig);
 engine.init();
 engine.run();
 ```
 
-### Engine(const DisplayConfig& displayConfig)
+### Engine(DisplayConfig&& displayConfig)
 
 Creates a new engine instance with custom display configuration and default input/audio settings.
 
 **Parameters:**
-- `displayConfig` (const `pixelroot32::graphics::DisplayConfig&`): Configuration settings for the display
+
+- `displayConfig` (`pixelroot32::graphics::DisplayConfig&&`): Configuration settings for the display (r-value reference)
 
 **Example:**
+
 ```cpp
-pixelroot32::core::Engine engine(displayConfig);
+auto displayConfig = /* ... */;
+pixelroot32::core::Engine engine(std::move(displayConfig));
 engine.init();
 engine.run();
 ```
@@ -89,14 +98,17 @@ engine.run();
 Initializes the engine subsystems. This method must be called before `run()`.
 
 **Returns:**
+
 - `void`
 
 **Notes:**
+
 - Initializes the Renderer, InputManager, and sets up the initial state
 - Must be called after construction and before `run()`
 - Safe to call multiple times (idempotent)
 
 **Example:**
+
 ```cpp
 Engine engine(displayConfig);
 engine.init();  // Initialize subsystems
@@ -109,15 +121,18 @@ engine.run();   // Start game loop
 Starts the main game loop. This method contains the infinite loop that calls `update()` and `draw()` repeatedly until the application exits.
 
 **Returns:**
+
 - `void`
 
 **Notes:**
+
 - This method blocks until the application exits
 - Handles frame timing and delta time calculation automatically
 - Calls `update()` and `draw()` once per frame
 - Do not call this method multiple times
 
 **Example:**
+
 ```cpp
 Engine engine(displayConfig);
 engine.init();
@@ -130,14 +145,17 @@ engine.run();  // Blocks here, runs game loop
 Gets the time elapsed since the last frame.
 
 **Returns:**
+
 - `unsigned long`: The delta time in milliseconds
 
 **Performance Notes:**
+
 - Very fast (inline accessor)
 - Safe to call every frame
 - Use this value to make movement frame-rate independent
 
 **Example:**
+
 ```cpp
 void update(unsigned long deltaTime) override {
     auto& engine = getEngine();
@@ -154,15 +172,18 @@ void update(unsigned long deltaTime) override {
 Sets the current active scene to be updated and rendered.
 
 **Parameters:**
+
 - `newScene` (`Scene*`): Pointer to the new Scene to become active. Can be `nullptr` to clear the current scene.
 
 **Notes:**
+
 - The previous scene is replaced (not pushed onto a stack)
 - Use `SceneManager` for push/pop operations if needed
 - The scene's `init()` method will be called automatically
 - Safe to call during the game loop
 
 **Example:**
+
 ```cpp
 class MainMenuScene : public pixelroot32::core::Scene {
     // ...
@@ -181,18 +202,21 @@ engine.setScene(&menuScene);  // Start with menu
 engine.run();
 ```
 
-### Scene* getCurrentScene() const
+### std::optional<Scene*> getCurrentScene() const
 
-Retrieves the currently active scene.
+Retrieves the currently active scene, or std::nullopt if no scene is active.
 
 **Returns:**
-- `Scene*`: Pointer to the current Scene, or `nullptr` if none is set
+
+- `std::optional<Scene*>`: Optional containing pointer to the current Scene, or std::nullopt if none is set
 
 **Example:**
+
 ```cpp
-auto* currentScene = engine.getCurrentScene();
-if (currentScene) {
+auto currentScene = engine.getCurrentScene();
+if (currentScene.has_value()) {
     // Scene is active
+    Scene* scene = currentScene.value();
 }
 ```
 
@@ -201,9 +225,11 @@ if (currentScene) {
 Replaces the current renderer instance.
 
 **Parameters:**
+
 - `newRenderer` (`pixelroot32::graphics::Renderer&`): Reference to the new Renderer to use
 
 **Notes:**
+
 - Advanced usage: typically not needed unless implementing custom renderer
 - The renderer must be properly initialized before use
 - Use with caution: may break existing rendering code
@@ -213,9 +239,11 @@ Replaces the current renderer instance.
 Provides access to the Renderer subsystem.
 
 **Returns:**
+
 - `pixelroot32::graphics::Renderer&`: Reference to the current Renderer
 
 **Example:**
+
 ```cpp
 void draw(pixelroot32::graphics::Renderer& renderer) override {
     auto& engineRenderer = engine.getRenderer();
@@ -228,9 +256,11 @@ void draw(pixelroot32::graphics::Renderer& renderer) override {
 Provides access to the InputManager subsystem.
 
 **Returns:**
+
 - `pixelroot32::input::InputManager&`: Reference to the InputManager
 
 **Example:**
+
 ```cpp
 void update(unsigned long deltaTime) override {
     auto& input = engine.getInputManager();
@@ -245,9 +275,13 @@ void update(unsigned long deltaTime) override {
 Provides access to the AudioEngine subsystem.
 
 **Returns:**
+
 - `pixelroot32::audio::AudioEngine&`: Reference to the AudioEngine
 
+**Note:** Only available if `PIXELROOT32_ENABLE_AUDIO=1`
+
 **Example:**
+
 ```cpp
 void playSound() {
     auto& audio = engine.getAudioEngine();
@@ -264,13 +298,17 @@ void playSound() {
 Provides access to the MusicPlayer subsystem.
 
 **Returns:**
+
 - `pixelroot32::audio::MusicPlayer&`: Reference to the MusicPlayer
 
+**Note:** Only available if `PIXELROOT32_ENABLE_AUDIO=1`
+
 **Example:**
+
 ```cpp
 void playMusic() {
     auto& music = engine.getMusicPlayer();
-    music.playTrack(myMusicTrack);
+    music.play(myMusicTrack);
 }
 ```
 
@@ -279,9 +317,11 @@ void playMusic() {
 Returns the detected hardware capabilities for the current platform (core count, recommended pinning, etc.).
 
 **Returns:**
+
 - `const PlatformCapabilities&`: Reference to the detected capabilities.
 
 **Example:**
+
 ```cpp
 const auto& caps = engine.getPlatformCapabilities();
 if (caps.hasDualCore) {
@@ -300,6 +340,7 @@ A structure that holds detected hardware capabilities, used to optimize task pin
 - **`int audioPriority`**: Recommended priority for audio tasks.
 
 Static Methods:
+
 - **`static PlatformCapabilities detect()`**: Automatically detects hardware capabilities based on the platform and configuration. It respects the defaults defined in `platforms/PlatformDefaults.h` and any compile-time overrides.
 
 ## Optional: Debug Statistics Overlay
@@ -313,8 +354,8 @@ When the engine is built with the preprocessor define **`PIXELROOT32_ENABLE_DEBU
 - **CPU**: Estimated processor load percentage (Yellow).
 
 !!! note "Platform Differences & CPU Metric"
-    The **CPU Load** metric is an estimation based on the processing time vs. a 60 FPS target (16.6ms). 
-    
+    The **CPU Load** metric is an estimation based on the processing time vs. a 60 FPS target (16.6ms).
+
     *   **On ESP32**: This is a realistic representation of how much time the CPU is spending on engine logic within its power limits.
     *   **On Native (PC)**: This metric may frequently show **100%** or high values even if your PC is idle. This happens because the native loop is synchronized with the monitor's VSYNC (via SDL2), which often causes the frame time to exceed 16.6ms (e.g., 33ms for 30 FPS). This is a result of the operating system's scheduling and SDL's synchronization, not actual hardware saturation.
 

docs/api_reference/core/global_config.md

@@ -2,6 +2,8 @@
 
 The engine's behavior can be customized using `platforms/PlatformDefaults.h` and `platforms/EngineConfig.h`, or via compile-time build flags. This allows for fine-tuning performance and hardware support without modifying the core engine code.
 
+For detailed platform-specific capabilities and limitations, see [Platform Compatibility Guide](../../manual/optimization/platform_compatibility.md).
+
 ## Platform Macros (Build Flags)
 
 | Macro | Description | Default (ESP32) |
@@ -13,6 +15,24 @@ The engine's behavior can be customized using `platforms/PlatformDefaults.h` and
 | `PIXELROOT32_USE_U8G2_DRIVER` | Enable U8G2 display driver support for monochromatic OLEDs. | Disabled |
 | `PIXELROOT32_NO_TFT_ESPI` | Disable default TFT_eSPI driver support. | Enabled |
 
+### Modular Compilation Flags
+
+| Macro | Description | Default |
+|-------|-------------|---------|
+| `PIXELROOT32_ENABLE_AUDIO` | Enable audio subsystem (AudioEngine + MusicPlayer). | `1` |
+| `PIXELROOT32_ENABLE_PHYSICS` | Enable physics system (CollisionSystem). | `1` |
+| `PIXELROOT32_ENABLE_UI_SYSTEM` | Enable UI system (UIButton, UILabel, etc.). | `1` |
+| `PIXELROOT32_ENABLE_PARTICLES` | Enable particle system. | `1` |
+
+**Usage in platformio.ini:**
+```ini
+[esp32_arcade]
+extends = base_esp32, profile_arcade
+build_flags = 
+    ${base_esp32.build_flags}
+    ${profile_arcade.build_flags}
+```
+
 ## Constants
 
 - **`DISPLAY_WIDTH`**
@@ -38,3 +58,9 @@ The engine's behavior can be customized using `platforms/PlatformDefaults.h` and
 
 - **`SPATIAL_GRID_MAX_ENTITIES_PER_CELL`**
     Maximum entities stored in a single grid cell. Default is `24`.
+
+## See Also
+
+- [Platform Compatibility Guide](../../manual/optimization/platform_compatibility.md)
+- [Performance Tuning](../../manual/optimization/performance_tuning.md)
+- [Engine](engine.md)