Cow<'_, T>, Arc<Mutex<T>>, Generics & Traits in Rust game programming

use std::borrow::Cow;

/// A material can share a base shader config or own an overridden copy.
#[derive(Clone)]
pub struct ShaderParams {
    pub base_color:  [f32; 4],
    pub roughness:   f32,
    pub metallic:    f32,
    pub emissive:    [f32; 3],
}

#[derive(Clone)]
pub struct Material<'a> {
    // Borrowed = shared with the asset cache, no allocation.
    // Owned    = this entity has its own overridden parameters.
    params: Cow<'a, ShaderParams>,
    name:   Cow<'a, str>,
}

impl<'a> Material<'a> {
    /// Create a material that borrows from the asset cache.
    pub fn from_cache(params: &'a ShaderParams, name: &'a str) -> Self {
        Material {
            params: Cow::Borrowed(params),
            name:   Cow::Borrowed(name),
        }
    }

    /// Override roughness — clones params lazily only at this point.
    pub fn set_roughness(&mut self, value: f32) {
        self.params.to_mut().roughness = value;
        // ^^ If Borrowed, clones once and becomes Owned. Subsequent
        //    calls to to_mut() reuse the existing owned allocation.
    }

    pub fn params(&self) -> &ShaderParams {
        &self.params   // Deref works for both variants transparently
    }
}

// ── Usage ─────────────────────────────────────────────────────
fn spawn_enemy_variants(base: &ShaderParams) {
    // 100 enemies share one ShaderParams allocation:
    let base_materials: Vec<Material> = (0..100)
        .map(|_| Material::from_cache(base, "enemy_standard"))
        .collect();

    // Only the boss gets a private clone — triggered on set_roughness:
    let mut boss_mat = Material::from_cache(base, "enemy_boss");
    boss_mat.set_roughness(0.02); // clone happens here, once
}

use std::sync::{Arc, Mutex};
use std::thread;

#[derive(Default)]
pub struct AudioState {
    pub master_volume: f32,
    pub active_sounds: Vec<SoundHandle>,
    pub listener_pos:  [f32; 3],
}

pub struct AudioSystem {
    // The Arc lets us clone the "pointer" cheaply for each thread.
    state: Arc<Mutex<AudioState>>,
}

impl AudioSystem {
    pub fn new() -> Self {
        AudioSystem {
            state: Arc::new(Mutex::new(AudioState::default())),
        }
    }

    /// Hand a cheap Arc clone to the audio mixing thread.
    pub fn spawn_mixer_thread(&self) -> thread::JoinHandle<()> {
        let state = Arc::clone(&self.state);  // increments ref-count atomically

        thread::spawn(move || {
            loop {
                let audio = state.lock().unwrap();
                // ^^ Blocks until the lock is free; returns a MutexGuard.
                //    The guard releases the lock automatically when dropped.
                mix_and_output(&audio.active_sounds, audio.master_volume);
                // Lock is released here when `audio` goes out of scope.
            }
        })
    }

    /// Gameplay thread adjusts volume — takes lock briefly, then releases.
    pub fn set_master_volume(&self, vol: f32) {
        let mut audio = self.state.lock().unwrap();
        audio.master_volume = vol.clamp(0.0, 1.0);
    }

    /// Physics thread updates listener position each frame.
    pub fn update_listener(&self, pos: [f32; 3]) {
        self.state.lock().unwrap().listener_pos = pos;
    }
}

fn mix_and_output(_sounds: &[SoundHandle], _vol: f32) { /* ... */ }

/// Minimize lock hold time: snapshot state, then process outside the lock.
fn process_audio_frame(state: &Arc<Mutex<AudioState>>) {
    // ① Critical section: take only what we need
    let (sounds, volume) = {
        let audio = state.lock().unwrap();
        (audio.active_sounds.clone(), audio.master_volume)
        // lock drops here — other threads unblocked immediately
    };

    // ② Heavy processing with no lock held
    mix_and_output(&sounds, volume);  // can take milliseconds — that's fine
}

/// RwLock variant — multiple readers, exclusive writer.
use std::sync::RwLock;

pub struct AssetCache {
    // Readers: any number of threads loading assets simultaneously.
    // Writer: only the loader thread when inserting a new asset.
    entries: Arc<RwLock<HashMap<AssetId, LoadedAsset>>>,
}

impl AssetCache {
    pub fn get(&self, id: AssetId) -> Option<Arc<LoadedAsset>> {
        self.entries.read().unwrap().get(&id).cloned()
        // ^^ read lock: many threads can call get() concurrently
    }

    pub fn insert(&self, id: AssetId, asset: LoadedAsset) {
        self.entries.write().unwrap().insert(id, asset);
        // ^^ write lock: exclusive, blocks all readers until done
    }
}

use std::time::Duration;

/// Core trait every game system must implement.
pub trait System {
    /// Called once before the first frame.
    fn init(&mut self);

    /// Called every frame with the elapsed delta time.
    fn update(&mut self, dt: Duration);

    /// Arbitrary name for debugging and profiling.
    fn name(&self) -> &str;
}

/// A system that can optionally draw debug information.
pub trait Debuggable: System {
    fn draw_debug(&self, ctx: &mut DebugCtx);
}

// ── Concrete systems ───────────────────────────────────────────
pub struct PhysicsSystem { gravity: f32 }
pub struct RenderSystem  { vsync: bool    }
pub struct AudioSystem   { sample_rate: u32 }

impl System for PhysicsSystem {
    fn init(&mut self)              { println!("Physics init, g={}", self.gravity) }
    fn update(&mut self, _dt: Duration) { /* integrate forces */ }
    fn name(&self) -> &str            { "PhysicsSystem" }
}

impl System for RenderSystem {
    fn init(&mut self)              { /* init GPU context */ }
    fn update(&mut self, _dt: Duration) { /* submit draw calls */ }
    fn name(&self) -> &str            { "RenderSystem" }
}

// ── Generic engine scheduler ───────────────────────────────────
/// Homogeneous list: all items must share the same *concrete* type.
/// For heterogeneous lists, use Vec<Box<dyn System>> instead.
pub fn run_systems<S: System>(systems: &mut [S], dt: Duration) {
    for system in systems.iter_mut() {
        system.update(dt);
    }
    // The compiler generates a specialized version of this function
    // for each concrete S — zero vtable overhead.
}

/// Heterogeneous scheduler: holds any type implementing System.
pub struct Scheduler {
    systems: Vec<Box<dyn System>>,
}

impl Scheduler {
    pub fn new() -> Self {
        Scheduler { systems: Vec::new() }
    }

    /// Generic add: any System impl is accepted, boxed transparently.
    pub fn add<S: System + 'static>(&mut self, system: S) {
        self.systems.push(Box::new(system));
    }

    pub fn init_all(&mut self) {
        for s in &mut self.systems { s.init(); }
    }

    pub fn update_all(&mut self, dt: Duration) {
        for s in &mut self.systems { s.update(dt); }
    }

    /// Profile: measure how long each system takes per frame.
    pub fn update_with_timing(&mut self, dt: Duration) {
        for s in &mut self.systems {
            let t0 = std::time::Instant::now();
            s.update(dt);
            println!("{}: {:.2}ms", s.name(), t0.elapsed().as_secs_f64() * 1000.0);
        }
    }
}

// ── Using the scheduler ────────────────────────────────────────
fn main() {
    let mut sched = Scheduler::new();
    sched.add(PhysicsSystem { gravity: -9.81 });
    sched.add(RenderSystem  { vsync: true    });
    sched.add(AudioSystem   { sample_rate: 44100 });
    sched.init_all();

    // Game loop:
    loop {
        sched.update_all(Duration::from_millis(16));
    }
}

/// A renderer backend defines its own opaque handle types.
pub trait RendererBackend {
    type TextureHandle: Copy + 'static;
    type BufferHandle:  Copy + 'static;
    type ShaderHandle:  Copy + 'static;

    fn create_texture(&mut self, desc: &TextureDesc) -> Self::TextureHandle;
    fn create_buffer (&mut self, desc: &BufferDesc)  -> Self::BufferHandle;
    fn submit_frame  (&mut self);
}

/// Generic scene renderer works with ANY backend.
pub struct SceneRenderer<B: RendererBackend> {
    backend: B,
    // Handle types are inferred from B — no casting, no type erasure.
    textures: Vec<B::TextureHandle>,
}

impl<B: RendererBackend> SceneRenderer<B> {
    pub fn load_texture(&mut self, desc: &TextureDesc) -> B::TextureHandle {
        let handle = self.backend.create_texture(desc);
        self.textures.push(handle);
        handle
    }
}

// Plug in Vulkan, Metal, WebGPU — same SceneRenderer code, zero changes.
type VkRenderer  = SceneRenderer<VulkanBackend>;
type WgpuRenderer = SceneRenderer<WgpuBackend>;

use std::{
    borrow::Cow,
    collections::HashMap,
    sync::{Arc, RwLock},
};

/// Any loadable asset type just needs to implement this trait.
pub trait Asset: Clone + Send + Sync + 'static {
    fn asset_type() -> &'static str;
}

#[derive(Clone)] pub struct Texture  { pub data: Vec<u8> }
#[derive(Clone)] pub struct AudioClip { pub pcm:  Vec<f32> }

impl Asset for Texture  { fn asset_type() -> &'static str { "texture"  } }
impl Asset for AudioClip { fn asset_type() -> &'static str { "audioclip" } }

/// Thread-safe cache for any Asset type.
pub struct AssetCache<A: Asset> {
    // Arc: shared across loader + gameplay threads.
    // RwLock: many concurrent readers, exclusive writer.
    inner: Arc<RwLock<HashMap<String, Arc<A>>>>,
}

impl<A: Asset> AssetCache<A> {
    pub fn new() -> Self {
        AssetCache { inner: Arc::new(RwLock::new(HashMap::new())) }
    }

    /// Returns a CoW: Borrowed if cached, triggers load + insert otherwise.
    pub fn get_or_load(&self, path: &str) -> Arc<A> {
        // Fast path: read lock, no writers blocked.
        if let Some(asset) = self.inner.read().unwrap().get(path) {
            return Arc::clone(asset);
        }
        // Slow path: load and insert under write lock.
        let loaded = Arc::new(load_from_disk::<A>(path));
        self.inner.write().unwrap()
            .insert(path.to_owned(), Arc::clone(&loaded));
        loaded
    }

    pub fn clone_handle(&self) -> Arc<RwLock<HashMap<String, Arc<A>>>> {
        Arc::clone(&self.inner)
    }
}

/// A material that borrows from the cache or owns an override — CoW!
pub struct SpriteMaterial<'a> {
    pub texture_path: Cow<'a, str>,
    pub tint:         [f32; 4],
}

fn load_from_disk<A: Asset>(_path: &str) -> A { unimplemented!() }