Develop

docs/api_reference/core/actor.md

@@ -25,15 +25,15 @@ namespace pixelroot32::core {
 
 ## Constructors
 
-### Actor(float x, float y, int w, int h)
+### Actor(Scalar x, Scalar y, Scalar w, Scalar h)
 
 Creates a new actor with specified position and size.
 
 **Parameters:**
-- `x` (float): Initial X position in world space
-- `y` (float): Initial Y position in world space
-- `w` (int): Actor width in pixels
-- `h` (int): Actor height in pixels
+- `x` (Scalar): Initial X position in world space
+- `y` (Scalar): Initial Y position in world space
+- `w` (Scalar): Actor width in pixels
+- `h` (Scalar): Actor height in pixels
 
 **Notes:**
 - Actor type is automatically set to `EntityType::ACTOR`
@@ -44,8 +44,8 @@ Creates a new actor with specified position and size.
 ```cpp
 class PlayerActor : public pixelroot32::core::Actor {
 public:
-    PlayerActor(float x, float y) 
-        : Actor(x, y, 16, 16) {
+    PlayerActor(Scalar x, Scalar y) 
+        : Actor(x, y, toScalar(16), toScalar(16)) {
         // Set collision layer and mask
         layer = pixelroot32::physics::DefaultLayers::kPlayer;
         mask = pixelroot32::physics::DefaultLayers::kEnemy | 

docs/api_reference/core/engine.md

@@ -25,36 +25,32 @@ namespace pixelroot32::core {
 
 ## Constructors
 
+### Engine(DisplayConfig&& displayConfig, const InputConfig& inputConfig, const AudioConfig& audioConfig)
+
+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)
 
-Creates a new engine instance with custom display, input, and audio configurations.
+Creates a new engine instance by copying configurations. Note that copying DisplayConfig will not copy custom draw surfaces (they are unique_ptr).
 
 **Parameters:**
-- `displayConfig` (const `pixelroot32::graphics::DisplayConfig&`): Configuration settings for the display (width, height, rotation, etc.)
-- `inputConfig` (const `pixelroot32::input::InputConfig&`): Configuration settings for the input system (pins, buttons)
-- `audioConfig` (const `pixelroot32::audio::AudioConfig&`): Configuration settings for the audio system (backend, sample rate, buffer size)
+- `displayConfig` (const `pixelroot32::graphics::DisplayConfig&`): Configuration settings for the display
+- `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"
-#include "input/InputConfig.h"
-#include "audio/AudioConfig.h"
-
-pixelroot32::graphics::DisplayConfig displayConfig;
-displayConfig.logicalWidth = 128;
-displayConfig.logicalHeight = 128;
-
-pixelroot32::input::InputConfig inputConfig;
-// Configure input pins...
 
-pixelroot32::audio::AudioConfig audioConfig;
-audioConfig.backend = pixelroot32::audio::AudioConfig::Backend::ESP32_DAC;
-audioConfig.sampleRate = 11025;
-
-pixelroot32::core::Engine engine(displayConfig, inputConfig, audioConfig);
-engine.init();
-engine.run();
+// Example with move semantics (recommended for custom displays)
+auto displayConfig = PIXELROOT32_CUSTOM_DISPLAY(std::make_unique<MyCustomDriver>().release(), 240, 240);
+pixelroot32::core::Engine engine(std::move(displayConfig), inputConfig, audioConfig);
 ```
 
 ### Engine(const DisplayConfig& displayConfig, const InputConfig& inputConfig)

docs/api_reference/core/entity.md

@@ -25,23 +25,23 @@ namespace pixelroot32::core {
 
 ## Constructors
 
-### Entity(float x, float y, int w, int h, EntityType t)
+### Entity(Scalar x, Scalar y, Scalar w, Scalar h, EntityType t)
 
 Creates a new entity with specified position, size, and type.
 
 **Parameters:**
-- `x` (float): Initial X position in world space
-- `y` (float): Initial Y position in world space
-- `w` (int): Width in pixels
-- `h` (int): Height in pixels
+- `x` (Scalar): Initial X position in world space
+- `y` (Scalar): Initial Y position in world space
+- `w` (Scalar): Width in pixels
+- `h` (Scalar): Height in pixels
 - `t` (`EntityType`): The type of entity (`GENERIC`, `ACTOR`, `UI_ELEMENT`)
 
 **Example:**
 ```cpp
 class MyEntity : public pixelroot32::core::Entity {
 public:
-    MyEntity(float x, float y) 
-        : Entity(x, y, 16, 16, EntityType::GENERIC) {}
+    MyEntity(Scalar x, Scalar y) 
+        : Entity(x, y, toScalar(16), toScalar(16), EntityType::GENERIC) {}
 
     void update(unsigned long deltaTime) override {
         // Update logic
@@ -55,11 +55,11 @@ public:
 
 ## Public Properties
 
-### float x, y
+### Scalar x, y
 
 Position of the entity in world space.
 
-**Type:** `float`
+**Type:** `Scalar`
 
 **Access:** Read-write
 
@@ -70,15 +70,15 @@ Position of the entity in world space.
 
 **Example:**
 ```cpp
-entity->x = 100.0f;
-entity->y = 50.0f;
+entity->x = toScalar(100.0f);
+entity->y = toScalar(50.0f);
 ```
 
-### int width, height
+### Scalar width, height
 
 Dimensions of the entity in pixels.
 
-**Type:** `int`
+**Type:** `Scalar`
 
 **Access:** Read-write
 
@@ -89,8 +89,8 @@ Dimensions of the entity in pixels.
 
 **Example:**
 ```cpp
-entity->width = 32;
-entity->height = 32;
+entity->width = toScalar(32);
+entity->height = toScalar(32);
 ```
 
 ### EntityType type

docs/api_reference/core/global_config.md

@@ -0,0 +1,40 @@
+# Global Configuration
+
+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.
+
+## Platform Macros (Build Flags)
+
+| Macro | Description | Default (ESP32) |
+|-------|-------------|-----------------|
+| `PR32_DEFAULT_AUDIO_CORE` | CPU core assigned to audio tasks. | `0` |
+| `PR32_DEFAULT_MAIN_CORE` | CPU core assigned to the main game loop. | `1` |
+| `PIXELROOT32_NO_DAC_AUDIO` | Disable Internal DAC support on classic ESP32. | Enabled |
+| `PIXELROOT32_NO_I2S_AUDIO` | Disable I2S audio support. | Enabled |
+| `PIXELROOT32_USE_U8G2_DRIVER` | Enable U8G2 display driver support for monochromatic OLEDs. | Disabled |
+| `PIXELROOT32_NO_TFT_ESPI` | Disable default TFT_eSPI driver support. | Enabled |
+
+## Constants
+
+- **`DISPLAY_WIDTH`**
+    The width of the display in pixels. Default is `240`.
+
+- **`DISPLAY_HEIGHT`**
+    The height of the display in pixels. Default is `240`.
+
+- **`int xOffset`**
+    The horizontal offset for the display alignment. Default is `0`.
+
+- **`int yOffset`**
+    The vertical offset for the display alignment. Default is `0`.
+
+- **`PHYSICS_MAX_PAIRS`**
+    Maximum number of simultaneous collision pairs tracked by the solver. Lower values save static DRAM. Default is `128`.
+
+- **`VELOCITY_ITERATIONS`**
+    Number of impulse solver passes per frame. Higher values improve stacking stability but increase CPU load. Default is `2`.
+
+- **`SPATIAL_GRID_CELL_SIZE`**
+    Size of each cell in the broadphase grid (in pixels). Default is `32`.
+
+- **`SPATIAL_GRID_MAX_ENTITIES_PER_CELL`**
+    Maximum entities stored in a single grid cell. Default is `24`.

docs/api_reference/core/physics_actor.md

@@ -27,31 +27,65 @@ namespace pixelroot32::core {
 - Inherits from: `Actor`
 - Inherited by: Your custom physics-enabled actor classes
 
+## Enums
+
+### PhysicsBodyType
+
+Defines the simulation behavior of the actor.
+
+| Value | Description |
+|-------|-------------|
+| `STATIC` | Immovable. Unaffected by gravity/forces. |
+| `KINEMATIC` | Moved by code. Pushes others but isn't pushed. |
+| `RIGID` | Fully simulated. Affected by gravity and forces. |
+
+### CollisionShape
+
+Defines the geometric shape for collision.
+
+| Value | Description |
+|-------|-------------|
+| `AABB` | Axis-Aligned Bounding Box (Default). Fastest. |
+| `CIRCLE` | Circular collider. Smoother for rolling objects. |
+
 ## Constructors
 
-### PhysicsActor(float x, float y, float w, float h)
+### PhysicsActor(Scalar x, Scalar y, Scalar w, Scalar h)
 
 Creates a physics-enabled actor with specified position and size.
 
 **Parameters:**
-- `x` (float): Initial X position in world space
-- `y` (float): Initial Y position in world space
-- `w` (float): Actor width in pixels
-- `h` (float): Actor height in pixels
+- `x` (Scalar): Initial X position in world space
+- `y` (Scalar): Initial Y position in world space
+- `w` (Scalar): Actor width in pixels
+- `h` (Scalar): Actor height in pixels
 
 **Notes:**
 - Velocity starts at (0, 0)
 - Restitution defaults to 1.0 (perfect bounce)
+- `bounce` flag defaults to `true` (enabled)
 - Friction defaults to 0.0 (no friction)
 - No world limits by default
 
+**Properties:**
+
+### bool bounce
+
+Controls whether the actor reflects velocity upon collision.
+
+- `true` (default): The actor will bounce off other actors and world boundaries based on the coefficient of restitution.
+- `false`: The actor will stop (velocity becomes 0) upon collision with a static object or world boundary.
+
+**Important:** For a bounce to occur between two objects, **BOTH** objects must have `bounce = true`. If a ball (`bounce=true`) hits a wall (`bounce=false`), the wall will absorb the impact and the ball will stop.
+
 **Example:**
 ```cpp
 class BallActor : public pixelroot32::core::PhysicsActor {
 public:
-    BallActor(float x, float y) 
-        : PhysicsActor(x, y, 8.0f, 8.0f) {
+    BallActor(Scalar x, Scalar y) 
+        : PhysicsActor(x, y, toScalar(8.0f), toScalar(8.0f)) {
         // Set physics properties
+        bounce = true;         // Enable bouncing
         setRestitution(0.8f);  // 80% bounce
         setFriction(0.1f);     // Small friction
         setWorldSize(128, 128); // World bounds
@@ -80,11 +114,11 @@ public:
 
 ## Protected Properties
 
-### float vx, vy
+### Scalar vx, vy
 
 Horizontal and vertical velocity components.
 
-**Type:** `float`
+**Type:** `Scalar`
 
 **Access:** Protected (use `setVelocity()` to modify)
 
@@ -97,7 +131,28 @@ Horizontal and vertical velocity components.
 
 ## Public Methods
 
-### void setVelocity(float x, float y)
+### void setBodyType(PhysicsBodyType type)
+
+Configures the actor's simulation behavior.
+
+**Parameters:**
+- `type` (`PhysicsBodyType`): The body type (`STATIC`, `KINEMATIC`, `RIGID`).
+
+### void setCollisionShape(CollisionShape shape)
+
+Sets the geometric shape used for collisions.
+
+**Parameters:**
+- `shape` (`CollisionShape`): The shape (`AABB`, `CIRCLE`).
+
+### void setGravityScale(Scalar scale)
+
+Sets the gravity multiplier for this actor (only for `RIGID` bodies).
+
+**Parameters:**
+- `scale` (`Scalar`): Multiplier (default 1.0). Set to 0.0 to disable gravity.
+
+### void setVelocity(Scalar x, Scalar y)
 
 Sets the linear velocity of the actor.
 
@@ -310,7 +365,7 @@ void onWorldCollision() override {
 
 ### void update(unsigned long deltaTime) override
 
-Updates the actor state. Applies physics integration and checks for world boundary collisions.
+Updates the actor state. Applies physics integration (velocity/forces).
 
 **Parameters:**
 - `deltaTime` (unsigned long): Time elapsed since the last frame in milliseconds
@@ -320,10 +375,9 @@ Updates the actor state. Applies physics integration and checks for world bounda
 
 **Notes:**
 - Called automatically by `Scene` if `isEnabled` is `true`
-- Applies velocity to position
-- Applies friction to velocity
-- Resolves world boundary collisions
-- Override to add custom update logic, but call `PhysicsActor::update(deltaTime)` first
+- Applies forces to velocity
+- **Important**: Position integration is now handled by `CollisionSystem` for `RigidActor`s. `PhysicsActor::update` mainly handles velocity integration and timer updates.
+- Override to add custom update logic, but call `PhysicsActor::update(deltaTime)` first to ensure physics run.
 
 **Example:**
 ```cpp

docs/api_reference/core/platform_capabilities.md

@@ -0,0 +1,44 @@
+# PlatformCapabilities
+
+**Namespace:** `pixelroot32::platforms`
+
+A structure that holds detected hardware capabilities, used to optimize task pinning and threading.
+
+## Members
+
+- **`bool hasDualCore`**
+    True if the hardware has more than one CPU core.
+
+- **`int coreCount`**
+    Total number of CPU cores detected.
+
+- **`int audioCoreId`**
+    Recommended CPU core for audio tasks.
+
+- **`int mainCoreId`**
+    Recommended CPU core for the main game loop.
+
+- **`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.
+
+## Debug Statistics Overlay
+
+When the engine is built with the preprocessor define **`PIXELROOT32_ENABLE_DEBUG_OVERLAY`**, the engine draws a technical overlay with real-time metrics.
+
+- **Metrics Included**:
+  - **FPS**: Frames per second (green).
+  - **RAM**: Memory used in KB (cyan). ESP32 specific.
+  - **CPU**: Estimated processor load percentage based on frame processing time (yellow).
+
+- **Behavior**: The metrics are drawn in the top-right area of the screen, fixed and independent of the camera.
+
+- **Performance**: Values are recalculated and formatted only every **16 frames** (`DEBUG_UPDATE_INTERVAL`); the cached strings are drawn every frame. This ensures minimal overhead while providing useful development data.
+
+- **Usage**: Add to your build flags, e.g. in `platformio.ini`:  
+  `build_flags = -D PIXELROOT32_ENABLE_DEBUG_OVERLAY`  
+  This flag is also available in `EngineConfig.h`.