//! # 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;

/// 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 for convenience.
pub trait AppHandler {
    /// 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. Used for executing draw calls
    /// by iterating Scene entities and calling app.renderer.render(view, mesh, material) per entity.
    /// Must be implemented — called every frame that needs rendering.
    /// Inputs: app — mutable reference to the App facade providing access to all subsystems.
    fn render(&mut self, app: &mut App);
}