docs: update API documentation for scene transitions and camera effects

api/config.md

@@ -14,10 +14,10 @@ This document covers global configuration options, build flags, and compile-time
 |-------|-------------|-----------------|
 | `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_NO_DAC_AUDIO` | Disable Internal DAC support on classic ESP32. | Not defined (opt-in) |
+| `PIXELROOT32_NO_I2S_AUDIO` | Disable I2S audio support. | Not defined (opt-in) |
 | `PIXELROOT32_USE_U8G2_DRIVER` | Enable U8G2 display driver support for monochromatic OLEDs. | Disabled |
-| `PIXELROOT32_NO_TFT_ESPI` | Disable default TFT_eSPI driver support. | Enabled |
+| `PIXELROOT32_NO_TFT_ESPI` | Disable default TFT_eSPI driver support. | Not defined (opt-in) |
 
 ## Modular Compilation Flags
 
@@ -27,8 +27,10 @@ This document covers global configuration options, build flags, and compile-time
 | `PIXELROOT32_ENABLE_PHYSICS` | Enable physics system. | `1` |
 | `PIXELROOT32_ENABLE_UI_SYSTEM` | Enable UI system. | `1` |
 | `PIXELROOT32_ENABLE_PARTICLES` | Enable particle system. | `1` |
+| `PIXELROOT32_ENABLE_CAMERA_EFFECTS` | Enable camera effects (shake, punch, offset). | `1` |
+| `PIXELROOT32_ENABLE_SCENE_TRANSITIONS` | Enable scene transition effects (fade, iris). | `1` |
 | `PIXELROOT32_ENABLE_DEBUG_OVERLAY` | Enable FPS/RAM/CPU debug overlay. | Disabled |
-| `PIXELROOT32_ENABLE_TILE_ANIMATIONS` | Enable tile animation system. | `1` |
+| `PIXELROOT32_ENABLE_TILE_ANIMATIONS` | Enable tile animation system. | `0` |
 | `PIXELROOT32_ENABLE_2BPP_SPRITES` | Enable 2bpp sprite support. | Disabled |
 | `PIXELROOT32_ENABLE_4BPP_SPRITES` | Enable 4bpp sprite support. | Disabled |
 | `PIXELROOT32_ENABLE_SCENE_ARENA` | Enable scene memory arena. | Disabled |
@@ -40,10 +42,8 @@ This document covers global configuration options, build flags, and compile-time
 | `PIXELROOT32_TFT_ESPI_LINES_PER_BLOCK` | TFT_eSPI DMA line batch size. | `60` |
 | `PIXELROOT32_TFT_ESPI_LINES_PER_BLOCK_FALLBACK` | Fallback DMA batch size if memory fails. | `30` |
 | `PIXELROOT32_DEBUG_MODE` | Enable unified logging system. | Disabled |
-| `PIXELROOT32_ENABLE_PHYSICS_FIXED_TIMESTEP` | Enable PhysicsScheduler for consistent physics. | `1` |
 | `PIXELROOT32_VELOCITY_DAMPING` | Per-frame velocity damping factor (0.0-1.0). | `0.999` |
 | `PIXELROOT32_MAX_VELOCITY` | Maximum velocity cap in units/s. | `500` |
-| `PIXELROOT32_HAS_FAST_RSQRT` | Enable fast reciprocal square root. | `1` |
 
 ## Memory Savings by Subsystem
 
@@ -104,20 +104,35 @@ build_flags =
 
 | Constant | Default | Description |
 |----------|---------|-------------|
-| `DISPLAY_WIDTH` | `240` | The logical width of the display in pixels. |
-| `DISPLAY_HEIGHT` | `240` | The logical height of the display in pixels. |
-| `xOffset` / `yOffset` | `0` | Coordinate offsets for hardware alignment. |
+| `DISPLAY_WIDTH` | `LOGICAL_WIDTH` | Deprecated alias for `LOGICAL_WIDTH`. |
+| `DISPLAY_HEIGHT` | `LOGICAL_HEIGHT` | Deprecated alias for `LOGICAL_HEIGHT`. |
+| `PHYSICAL_DISPLAY_WIDTH` | `240` | Actual hardware display width in pixels. |
+| `PHYSICAL_DISPLAY_HEIGHT` | `240` | Actual hardware display height in pixels. |
+| `LOGICAL_WIDTH` | `PHYSICAL_DISPLAY_WIDTH` | Internal rendering width. Engine scales to physical. |
+| `LOGICAL_HEIGHT` | `PHYSICAL_DISPLAY_HEIGHT` | Internal rendering height. Engine scales to physical. |
+| `DISPLAY_ROTATION` | `0` | Display rotation (0, 90, 180, 270). |
+| `X_OFF_SET` | `0` | Horizontal coordinate offset for hardware alignment. |
+| `Y_OFF_SET` | `0` | Vertical coordinate offset for hardware alignment. |
+| `MAX_SCENES` | `8` | Maximum number of scenes in the scene stack. |
+| `MAX_LAYERS` | `4` | Maximum number of layers per scene. |
+| `MAX_ENTITIES` | `64` | Maximum entities per scene. |
+| `MAX_TILESET_SIZE` | `256` | Maximum number of tiles in a tileset. |
+| `MAX_BACKGROUND_PALETTE_SLOTS` | `8` | Background palette slots for multi-palette tilemaps (2bpp/4bpp). |
+| `MAX_SPRITE_PALETTE_SLOTS` | `8` | Sprite palette slots for multi-palette sprites (2bpp/4bpp). |
+| `PHYSICS_MAX_ENTITIES` | `64` | Maximum entities in the physics system. |
 | `PHYSICS_MAX_PAIRS` | `128` | Maximum collision pairs considered in broadphase. |
 | `PHYSICS_MAX_CONTACTS` | `128` | Maximum simultaneous contacts in the physics solver. |
-| `VELOCITY_ITERATIONS` | `2` | Number of impulse solver passes per frame. |
+| `PIXELROOT32_VELOCITY_ITERATIONS` | `2` | Number of impulse solver passes per frame. |
 | `SPATIAL_GRID_CELL_SIZE` | `32` | Size of each cell in the broadphase grid (pixels). |
 | `SPATIAL_GRID_MAX_ENTITIES_PER_CELL` | `24` | (Legacy) max entities per cell. |
 | `SPATIAL_GRID_MAX_STATIC_PER_CELL` | `12` | Max static actors per grid cell. |
 | `SPATIAL_GRID_MAX_DYNAMIC_PER_CELL` | `12` | Max dynamic actors per grid cell. |
+| `PR32_HAS_FPU_MACRO` | Auto-detected | Set to `1` if target has hardware FPU (ESP32, ESP32-S3, ESP32-P4, native). Undefined for C-series. |
+| `PR32_FORCE_FIXED` | Undefined | User override: undefines `PR32_HAS_FPU_MACRO` to force Fixed16 math. |
 
 ## Custom Scene Limits
 
-The engine defines default limits in `platforms/EngineConfig.h`: `MAX_LAYERS` (default 3) and `MAX_ENTITIES` (default 32). These are guarded with `#ifndef`, so you can override them from your project without modifying the engine.
+The engine defines default limits in `platforms/EngineConfig.h`: `MAX_LAYERS` (default 4) and `MAX_ENTITIES` (default 64). These are guarded with `#ifndef`, so you can override them from your project without modifying the engine.
 
 **Compiler flags (recommended)**
 

api/core.md

@@ -5,6 +5,7 @@
 > - `include/core/Entity.h`
 > - `include/core/Scene.h`
 > - `include/core/SceneManager.h`
+> - `include/graphics/TransitionEffect.h`
 > - `include/platforms/PlatformCapabilities.h`
 > - `include/graphics/DisplayConfig.h`
 
@@ -16,7 +17,13 @@ This document covers the core engine classes, entity system, and scene managemen
 
 ### Engine
 
-The main engine class that manages the game loop and core subsystems. Each iteration calls **`update()`**; **`draw()`** and **`present()`** run only when **`SceneManager::aggregateShouldRedrawFramebuffer()`** is `true` (any stacked scene may request a pass). 
+The main engine class that manages the game loop and core subsystems. Each iteration calls **`update()`**; **`draw()`** and **`present()`** run only when **`SceneManager::aggregateShouldRedrawFramebuffer()`** is `true` (any stacked scene may request a pass).
+
+**Scene Transitions** (`PIXELROOT32_ENABLE_SCENE_TRANSITIONS=1`):
+- `triggerTransition(type, durationMs, dir)`: Initiate Fade or Iris transition
+- `isTransitioning()`: Check if transition is active
+- Transition effects are managed by `TransitionEffect` class (see Graphics Module)
+- Input is blocked during transitions to prevent ghost inputs
 
 ### Entity
 
@@ -50,6 +57,14 @@ build_flags =
 
 Manages the stack of active scenes. Allows for scene transitions (replacing) and stacking (push/pop), useful for pausing or menus. `aggregateShouldRedrawFramebuffer()` ensures that menus don't suppress background scenes that still need drawing.
 
+**Transition Support** (`PIXELROOT32_ENABLE_SCENE_TRANSITIONS=1`):
+- `transitionToScene(scene, type, durationMs, dir)`: Begin transition to new scene
+- `isTransitioning()`: Check if transition is active
+- `updateTransitions(deltaTime)`: Update transition state machine
+- `drawTransitionOverlay(renderer)`: Render transition effect overlay
+- State machine: `Idle → FadingOut → SceneSwap → FadingIn → Idle`
+- Input blocked during `FadingOut` and `FadingIn` states
+
 ### SceneArena (Memory Management)
 
 An optional memory arena for zero-allocation scenes (enabled via `PIXELROOT32_ENABLE_SCENE_ARENA`). Pre-allocates a fixed memory block for temporary data or entity storage, avoiding heap fragmentation on embedded devices.
@@ -100,6 +115,7 @@ The metrics are drawn in the top-right area of the screen, fixed and independent
 - `Scene` → `include/core/Scene.h`
 - `SceneManager` → `include/core/SceneManager.h`
 - `SceneArena` → `include/core/Scene.h`
+- `TransitionEffect` → `include/graphics/TransitionEffect.h`
 - `PlatformCapabilities` → `include/platforms/PlatformCapabilities.h`
 - `DisplayConfig` → `include/graphics/DisplayConfig.h`
 

api/generated/audio/AudioConfig.md

@@ -19,14 +19,3 @@ Configuration for the Audio subsystem.
 ## Methods
 
 ### `: backend(backend), sampleRate(sampleRate), blockSize(blockSize)`
-
-**Description:**
-
-Constructs an AudioConfig with platform-adaptive block size.
-
-**Parameters:**
-
-- `backend`: Pointer to the audio backend implementation. May be nullptr for headless configs.
-- `sampleRate`: Desired sample rate in Hz (default 22050 for retro feel).
-- `blockSize`: Audio block size in samples. Defaults to 256 on FPU platforms, 128 on no-FPU platforms.
-       Must be a multiple of 128 for I2S DMA alignment.

api/generated/audio/DefaultAudioScheduler.md

@@ -28,7 +28,39 @@ For platforms with a dedicated audio task (e.g., FreeRTOS on ESP32),
 
 ## Methods
 
-### `bool isMusicPlaying() const`
+### `void init(AudioBackend* backend, int sampleRate, const pixelroot32::platforms::PlatformCapabilities& caps, int blockSize = 256)`
+
+### `void submitCommand(const AudioCommand& cmd)`
+
+**Description:**
+
+Enqueues a command to the ApuCore. @param cmd The command to submit.
+
+**Parameters:**
+
+- `cmd`: The command to submit.
+
+### `void start()`
+
+**Description:**
+
+Marks scheduler as running. Starts audio generation context.
+
+### `void stop()`
+
+**Description:**
+
+Marks scheduler as stopped. Silences all voices.
+
+### `bool isIndependent() const`
+
+**Description:**
+
+Returns false (no dedicated audio thread). @return false.
+
+**Returns:** false.
+
+### `void generateSamples(int16_t* stream, int length)`
 
 **Description:**
 
@@ -38,6 +70,8 @@ Generates samples via ApuCore. @param stream Output buffer. @param length Sample
 
 - `stream`: Output buffer.
 
+### `bool isMusicPlaying() const`
+
 ### `bool isMusicPaused() const`
 
 ### `ApuCore& getApuCore()`

api/generated/core/Actor.md

@@ -31,28 +31,66 @@ enemies, and projectiles.
 
 ### `: Entity(x, y, w, h, EntityType::ACTOR)`
 
+### `: Entity(pos, w, h, EntityType::ACTOR)`
+
+### `void setCollisionLayer(pixelroot32::physics::CollisionLayer l)`
+
 **Description:**
 
-Constructor using Scalar coordinates.
+Sets the collision layer this actor belongs to.
 
-### `: Entity(pos, w, h, EntityType::ACTOR)`
+**Parameters:**
+
+- `l`: The collision layer.
+
+### `void setCollisionMask(pixelroot32::physics::CollisionLayer m)`
 
 **Description:**
 
-Constructor using Vector2 position.
+Sets the collision mask defining which layers this actor interacts with.
 
-### `void setCollisionLayer(pixelroot32::physics::CollisionLayer l)`
+**Parameters:**
 
-### `void setCollisionMask(pixelroot32::physics::CollisionLayer m)`
+- `m`: The collision mask.
 
 ### `void update(unsigned long deltaTime)`
 
+**Description:**
+
+Updates the actor's state.
+
+**Parameters:**
+
+- `deltaTime`: Time elapsed since last update in milliseconds.
+
 ### `bool isInLayer(uint16_t targetLayer) const`
 
+**Description:**
+
+Checks if the actor belongs to a specific collision layer.
+
+**Parameters:**
+
+- `targetLayer`: The layer bitmask to check.
+
+**Returns:** true if the actor is in the specified layer.
+
 ### `virtual Rect getHitBox()`
 
+**Description:**
+
+Gets the axis-aligned bounding box (hitbox) for this actor.
+
+**Returns:** The Rect representing the hitbox.
+
 ### `virtual bool isPhysicsBody() const`
 
+**Description:**
+
+Checks if this actor is a physics-driven body (e.g., RigidActor).
+
+**Returns:** true if it is a physics body, false otherwise.
+
 ### `virtual void onCollision(Actor* other)`
 
 **Description:**

api/generated/core/Engine.md

@@ -65,6 +65,40 @@ Sets the current active scene.
 
 - `newScene`: Pointer to the new Scene to become active.
 
+### `void triggerTransition(Scene* newScene, pixelroot32::graphics::TransitionType type, unsigned long durationMs)`
+
+**Description:**
+
+Start a visual scene transition (Fade, Iris, or DiagonalWipe).
+
+**Parameters:**
+
+- `newScene`: The target scene to transition to.
+- `type`: TransitionType::Fade, TransitionType::Iris, or TransitionType::DiagonalWipe.
+- `durationMs`: Duration of each phase (Out and In) in ms.
+
+Delegates to SceneManager::transitionToScene(). Ignored if a
+transition is already in progress.
+
+### `void triggerTransition(Scene* newScene, pixelroot32::graphics::TransitionType type, unsigned long durationMs, int irisOutCx, int irisOutCy, int irisInCx, int irisInCy)`
+
+**Description:**
+
+Start a visual scene transition with direction-specific iris centers.
+
+**Parameters:**
+
+- `newScene`: The target scene to transition to.
+- `type`: TransitionType::Fade, TransitionType::Iris, or TransitionType::DiagonalWipe.
+- `durationMs`: Duration of each phase (Out and In) in ms.
+- `irisOutCx`: Iris center X for Out (closing) phase.
+- `irisOutCy`: Iris center Y for Out (closing) phase.
+- `irisInCx`: Iris center X for In (opening) phase.
+- `irisInCy`: Iris center Y for In (opening) phase.
+
+Delegates to SceneManager::transitionToScene() with centers.
+Only meaningful for Iris transitions — Fade ignores centers.
+
 ### `std::optional<Scene*> getCurrentScene() const`
 
 **Description:**

api/generated/core/Entity.md

@@ -65,38 +65,10 @@ Sets the render layer.
 
 ### `: position(pos), width(w), height(h), type(t)`
 
-**Description:**
-
-Constructor.
-
-**Parameters:**
-
-- `position`: Initial position.
-- `w`: Width.
-- `h`: Height.
-- `t`: EntityType.
-
 ### `: position(x, y), width(w), height(h), type(t)`
 
-**Description:**
-
-Constructor.
-
-**Parameters:**
-
-- `x`: Initial X position.
-- `y`: Initial Y position.
-- `w`: Width.
-- `h`: Height.
-- `t`: EntityType.
-
 ### `: position(pixelroot32::math::toScalar(x), pixelroot32::math::toScalar(y)), width(w), height(h), type(t)`
 
-**Description:**
-
-Constructor with float coordinates for convenience.
-Only enabled if Scalar is NOT float to avoid ambiguity.
-
 ### `virtual void update(unsigned long deltaTime)`
 
 **Description:**

api/generated/core/LimitRect.md

@@ -15,15 +15,4 @@ Values of -1 indicate no limit on that side.
 
 ### `int width() const`
 
-**Description:**
-
-Constructs a new LimitRect.
-
-**Parameters:**
-
-- `l`: Left limit.
-- `t`: Top limit.
-- `r`: Right limit.
-- `b`: Bottom limit.
-
 ### `int height() const`