//! # AppHandler Trait — User-Defined Game Logic Interface
//!
//! Defines the `AppHandler` trait that users implement to inject their game logic into the render loop.
//! Provides two callback points: `update()` for pre-render logic (physics, input processing) and
//! `render()` for draw call execution. Both methods receive mutable access to the `App` facade so
//! users can modify resources, entities, or other state during each frame iteration.
//!
//! ## Interaction with Other Modules
//! - **app**: The orchestrator calls update() before rendering and render() during the RedrawRequested event.
//!   AppHandler has no direct knowledge of wgpu internals — it operates only through the App facade.
//! - **scene::Scene**: Users typically manipulate app.scene inside these callbacks to add/remove entities.
//! - **pipeline::PipelineCache**: Users may create new Materials via cache.get_or_create() in update().
//!
//! ## Architecture Note
//! Per ARCHI_APP.md, this trait is one half of the "App" facade pattern. It enables a declarative workflow
//! where users define their game logic without touching WGPU directly, while keeping the freedom to build
//! the engine "brick by brick" through direct Context/PipelineCache/Renderer manipulation if needed.

use crate::app::App;
use crate::core::Frame;

/// Trait defining user-provided game logic injected into the render loop at two callback points.
/// Users implement this trait to define what happens per-frame: update (pre-render logic) and
/// render (draw call execution). Default implementations provide empty update and automatic
/// scene rendering for convenience.
pub trait AppHandler {
    /// Called once by `App::run`, right after the window/GPU context are created (winit `resumed`).
    /// Use it to register shaders, build Meshes/Materials, and populate `app.scene` before the loop
    /// starts. Default implementation does nothing.
    /// Inputs: app — mutable reference to the fully-initialized App facade.
    fn setup(&mut self, _app: &mut App) {}
    /// Called once per frame before rendering begins. Used for physics updates, input processing,
    /// entity management, and any other pre-render logic. Default implementation does nothing.
    /// Inputs: _app — mutable reference to the App facade providing access to all subsystems.
    fn update(&mut self, _app: &mut App) {}
    /// Called during each RedrawRequested event after frame acquisition, receiving the current frame.
    /// Used for custom draw call execution. Default implementation renders the whole scene
    /// automatically (`app.render_scene(frame.view())`), so most users don't need to override it.
    /// Advanced users override this method to control drawing manually.
    /// Inputs: app — mutable reference to the App facade; frame — the acquired frame exposing its view.
    fn render(&mut self, app: &mut App, frame: &Frame) {
        app.render_scene(frame.view());
    }
}