concinnity-dev 0.19.119

//! `AssetHotReloadState` (the debug-owned reload catalog + in-flight decode
//! handles + live watcher) plus the off-thread decode result types, the ECS
//! side-effect bundle, and `run_frame`, the per-frame entry the debug drive
//! calls. Built from `HotReloadSources` (captured in the lib at init).

use concinnity_core::animation::skeleton;
use concinnity_core::components::SkeletonJoint;
use concinnity_core::components::Story;
use concinnity_core::gfx::mesh_payload;
use concinnity_core::gfx::render_types::SkinnedIndex;
use concinnity_core::render::backend::RenderBackend;
use concinnity_engine::live_edit::hot_reload_sources::*;
use concinnity_engine::live_edit::parked::PushedFogSettings;
use std::sync::{Arc, Mutex};

use super::decode::{poll_pending_assets, poll_pending_envmap, reload_assets};
use super::passes::{reload_procedural_meshes, reload_stories, reload_volumetric_fog};
use super::report::ReloadReport;
use super::sdf::SdfReload;
use super::shader::ShaderReload;
use super::signals::ReloadSignals;
use super::watcher::spawn_watcher;

// A worker result still in flight: the receiving end of the channel a
// background reload thread sends its decoded payload on, `None` when idle.
type Inflight<T> = Mutex<Option<std::sync::mpsc::Receiver<T>>>;

// One decoded `Texture` ready for the render thread to push through the
// `update_texture_slot` backend call. Computed off-thread by the
// `cn-asset-reload` worker so the (sometimes seconds-long) decode never blocks
// the render loop.
#[derive(Debug)]
pub(crate) struct DecodedTexture {
    pub slot: usize,
    pub width: u32,
    pub height: u32,
    pub pixels: Vec<u8>,
    // Source path retained for error logging when the GPU upload fails.
    pub source: String,
}

// One decoded `ColorLut` ready for the render thread to push through
// `update_color_lut`.
#[derive(Debug)]
pub(crate) struct DecodedColorLut {
    pub size: u32,
    pub data: Vec<u8>,
    pub source: String,
}

// One decoded static `Mesh`, ready for the render thread to dispatch into
// either an in-place [`concinnity_core::render::backend::RenderBackend::update_mesh_geometry`]
// per draw slot or a queued
// [`concinnity_core::render::backend::RenderBackend::rebuild_static_geometry`] when any
// LOD slice's size changed. `entry_idx` indexes into
// `state.meshes.entries` so the applier can look up `draw_indices` for
// fan-out to every `Prop` that shares the mesh.
#[derive(Debug)]
pub(crate) struct DecodedMesh {
    pub entry_idx: usize,
    pub vertices: Vec<mesh_payload::Vertex>,
    pub indices: Vec<u16>,
    pub lod_alternates: Vec<(f32, Vec<u16>)>,
}

// One decoded `SkinnedMesh`, ready for the render thread to dispatch into
// `update_skinned_mesh_geometry`. `entry_idx` indexes into
// `state.skinned_meshes.entries` so the applier can look up the slot's
// init-time `vertex_base` / `vertex_count` / `index_count` / `joint_count`
// and reject shape changes that need a pipeline rebuild.
#[derive(Debug)]
pub(crate) struct DecodedSkinnedMesh {
    pub entry_idx: usize,
    pub vertices: Vec<mesh_payload::SkinnedVertex>,
    pub indices: Vec<u16>,
    pub skeleton: Vec<SkeletonJoint>,
}

// Output of one off-thread decode pass: every captured source the worker
// successfully re-read from disk plus a count of the ones that failed (logged
// individually as they happened). The render thread drains this in
// [`poll_pending_assets`] and dispatches each item through the matching
// backend call.
#[derive(Debug, Default)]
pub(crate) struct DecodedAssetBatch {
    pub textures: Vec<DecodedTexture>,
    pub color_lut: Option<DecodedColorLut>,
    pub meshes: Vec<DecodedMesh>,
    pub skinned_meshes: Vec<DecodedSkinnedMesh>,
    // Number of source entries that failed to decode (logged per-entry in
    // the worker; tallied here so the apply pass can include them in the
    // summary line).
    pub decode_failures: usize,
}

// Shared `cn debug`-only state: the source map, the optional LUT entry, the
// reload signals `run_frame` takes at frame start, and the live watcher handle.
pub(crate) struct AssetHotReloadState {
    pub map: TextureSourceMap,
    // Singleton `ColorLut`, when the world declared one with a `source` path.
    // Reloaded alongside the texture map by [`reload_assets`].
    pub color_lut: Option<ColorLutSource>,
    // Singleton `EnvironmentMap`, when the world declared one with a
    // `source` path (procedural `generator` declarations are skipped).
    // Reloaded alongside the texture map by [`reload_assets`].
    pub environment_map: Option<EnvironmentMapSource>,
    // File-backed `Mesh` assets, one entry per Mesh asset (an entry may map
    // to many draw slots when several `Prop`s share the same Mesh).
    pub meshes: MeshSourceMap,
    // File-backed `SkinnedMesh` assets, one entry per skinned draw slot.
    // Each entry carries the slot's vertex region + joint count so the
    // reload helper can reject size-changing reloads and skeleton-shape
    // changes before pushing to the backend.
    pub skinned_meshes: SkinnedMeshSourceMap,
    // `ProceduralMesh` assets whose generator args can be re-applied from a
    // live `world.jsonl`. No file watcher of their own: the trigger is the
    // world.jsonl reload signal.
    pub procedural_meshes: ProceduralMeshSourceMap,
    // Every world `Shader`'s files, the compiles in flight, and the overrides
    // shared with the streaming pump. The asset watcher marks the Shaders a
    // save touches (separate from the texture / mesh / LUT batch path so a
    // shader save does not also kick a 43-texture re-decode).
    pub shaders: ShaderReload,
    // Every SdfVolume's field and the compiles in flight, marked by the same
    // watcher branch as the Shaders.
    pub sdf_fields: SdfReload,
    // Path to the world.jsonl the renderer was initialized from, when
    // known. Used both as a watch-dir source (its parent directory joins
    // the texture / model / HDRI / LUT dirs) and as the file the
    // `world.jsonl` reload pass re-reads from disk. `None` when init came
    // from a stream / blob and no on-disk path exists to watch.
    pub world_jsonl_path: Option<String>,
    // The driver's reload signals, raised by the `notify` watcher and the
    // `reload-assets` debug tool call and taken by [`run_frame`].
    pub signals: Arc<ReloadSignals>,
    // In-flight EnvironmentMap convolution. `Some(receiver)` while a
    // worker thread is computing the irradiance + prefilter payload;
    // [`poll_pending_envmap`] picks the result up on a later frame and
    // pushes it through `backend.update_environment_map`. The convolution
    // is CPU-bound and takes seconds at default sizes: running it on the
    // render thread previously stalled the frame loop, so the reload now
    // spawns a worker and the render thread keeps drawing while it runs.
    // `Mutex` for interior mutability behind the `&AssetHotReloadState`
    // access pattern; contention is none in practice (single-threaded
    // reads from the render thread).
    pub env_map_inflight: Inflight<Result<Vec<u8>, String>>,
    // In-flight texture + ColorLut + Mesh + SkinnedMesh decode batch.
    // `Some(receiver)` while a `cn-asset-reload` worker is re-decoding
    // every captured source from disk; [`poll_pending_assets`] picks the
    // batch up on a later frame and pushes each entry through the matching
    // backend `update_*` call. Decoding 43 textures + 14 meshes from a
    // shared 43 MB `.glb` used to take ~3 s on the render thread; with the
    // worker the render loop keeps drawing while the decode runs and only
    // stalls for the (fast) GPU upload pass.
    pub asset_batch_inflight: Inflight<DecodedAssetBatch>,
    // The compiled args of every `Story` the last story-reload pass handed
    // over, keyed by asset name. Lets the pass skip stories whose graphs
    // did not change, so a save of one story's `.md` never re-renders the
    // others. Starts empty: the first pass after a `.md` event sends every
    // story once.
    pub story_snapshots: std::collections::HashMap<String, serde_json::Value>,
    // SkinnedMesh skeleton-shape changes queued by [`poll_pending_assets`]
    // for the next step to apply to ECS-owned `SkeletonPose` components.
    // The reload helper has no ECS access, so it stashes the (skinned_index,
    // new skeleton) pair here and `GraphicsSystem::step` drains it
    // post-`poll_pending_assets` (via [`drain_pending_skeleton_updates`])
    // and rebuilds the matching pose component. Empty in steady state;
    // non-empty for at most one frame after a skeleton-shape reload.
    pub pending_skeleton_updates: Vec<PendingSkeletonUpdate>,
    // Watcher kept alive purely for its drop semantics; events are delivered
    // via the closure registered at construction.
    watcher: Option<notify::RecommendedWatcher>,
}

// One skeleton-shape update produced by a skinned hot-reload pass that
// detected a joint-count change. [`poll_pending_assets`] queues these on
// `AssetHotReloadState.pending_skeleton_updates`; the next
// `GraphicsSystem::step` drains them and rebuilds the matching
// `SkeletonPose` component in the ECS so `AnimationSystem` produces the
// right-sized output going forward.
#[derive(Debug)]
pub(crate) struct PendingSkeletonUpdate {
    // Backend slot the new skeleton belongs to. Used to find the matching
    // `SkeletonPose` (which carries the same `skinned_index`).
    pub skinned_index: SkinnedIndex,
    // Fresh skeleton built from the re-imported `.glb`'s joint defs.
    pub new_skeleton: skeleton::Skeleton,
}

impl std::fmt::Debug for AssetHotReloadState {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let env_inflight = self
            .env_map_inflight
            .try_lock()
            .map(|g| g.is_some())
            .unwrap_or(false);
        let batch_inflight = self
            .asset_batch_inflight
            .try_lock()
            .map(|g| g.is_some())
            .unwrap_or(false);
        f.debug_struct("AssetHotReloadState")
            .field("entries", &self.map.entries.len())
            .field("color_lut", &self.color_lut.is_some())
            .field("environment_map", &self.environment_map.is_some())
            .field("meshes", &self.meshes.entries.len())
            .field("skinned_meshes", &self.skinned_meshes.entries.len())
            .field("procedural_meshes", &self.procedural_meshes.entries.len())
            .field("shaders", &self.shaders.catalog.len())
            .field("sdf_fields", &self.sdf_fields.catalog.len())
            .field("world_jsonl_path", &self.world_jsonl_path)
            .field("signals", &self.signals)
            .field("env_map_inflight", &env_inflight)
            .field("asset_batch_inflight", &batch_inflight)
            .field("watcher", &self.watcher.is_some())
            .finish()
    }
}

impl AssetHotReloadState {
    // Build the state from the init-captured [`HotReloadSources`] bundle and
    // the host's world.jsonl path, and (best-effort) spawn the `notify` watcher
    // over every unique parent directory of those paths, raising `signals`.
    // Watcher creation is best-effort: a missing path or notify error logs and
    // continues; the `reload-assets` debug tool call still raises the same
    // signals. The driver calls this on each tick that finds freshly parked
    // sources.
    pub(crate) fn from_sources(
        sources: HotReloadSources,
        world_jsonl_path: Option<String>,
        signals: Arc<ReloadSignals>,
    ) -> Self {
        let watcher = if sources.is_empty() && world_jsonl_path.is_none() {
            None
        } else {
            spawn_watcher(&sources, world_jsonl_path.as_deref(), Arc::clone(&signals))
        };
        let HotReloadSources {
            map,
            color_lut,
            environment_map,
            meshes,
            skinned_meshes,
            procedural_meshes,
            shaders,
            shader_overrides,
            sdf_fields,
        } = sources;
        Self {
            map,
            color_lut,
            environment_map,
            meshes,
            skinned_meshes,
            procedural_meshes,
            shaders: ShaderReload::new(shaders, shader_overrides),
            sdf_fields: SdfReload::new(sdf_fields),
            world_jsonl_path,
            signals,
            env_map_inflight: Mutex::new(None),
            asset_batch_inflight: Mutex::new(None),
            story_snapshots: std::collections::HashMap::new(),
            pending_skeleton_updates: Vec::new(),
            watcher,
        }
    }

    // Take ownership of any skeleton-shape updates queued by the most
    // recent [`poll_pending_assets`] pass. Drained by
    // `GraphicsSystem::step` so the ECS-owned `SkeletonPose` components
    // can be rebuilt with the new joint hierarchy.
    pub(crate) fn drain_pending_skeleton_updates(&mut self) -> Vec<PendingSkeletonUpdate> {
        std::mem::take(&mut self.pending_skeleton_updates)
    }
}

// ECS-side effects a single hot-reload pass produced that the caller must
// apply to the `World` after dropping its `&mut GraphicsSystem` borrow:
// skeleton-shape changes to splice into `SkeletonPose` components, and Props
// a world.jsonl reload added that must enter the ECS so subsequent systems
// see them. Returned by [`run_frame`] instead of applied in place because the
// reload passes hold the backend + Prop-tracking borrow and have no `World`
// access: the `FrameHook::tick` drive applies these once the
// system borrow is released.
pub(crate) struct FrameHotReloadEffects {
    pub skeleton_updates: Vec<PendingSkeletonUpdate>,
    // Freshly re-compiled story graphs from a `.md` save, to be sent as
    // `StoryReload` events so the running story system swaps them in.
    pub story_updates: Vec<Story>,
    // What became of each Shader and SdfVolume recompile that finished this
    // frame, or could not start.
    pub reload_reports: Vec<ReloadReport>,
}

// Run every asset / shader / world.jsonl reload pass for one frame and return
// the ECS side-effects. `state` is the debug-owned reload catalog +
// in-flight handles; `backend` and `fog` are the world's parked backend and the
// fog it last pushed (see `concinnity_engine::live_edit::render_handoff`).
// This is the per-frame entry point the `FrameHook::tick` drive calls; it
// holds the logic that previously sat at the top of `GraphicsSystem::run_step`,
// minus the ECS mutation: the caller applies that from the returned
// `FrameHotReloadEffects` once the system borrow is released.
pub(crate) fn run_frame(
    state: &mut AssetHotReloadState,
    backend: &mut dyn RenderBackend,
    fog: &mut PushedFogSettings,
    notify: Option<&crate::editor::notify::Notifier>,
) -> FrameHotReloadEffects {
    use crate::editor::notify::Action;
    let mut effects = FrameHotReloadEffects {
        skeleton_updates: Vec::new(),
        story_updates: Vec::new(),
        reload_reports: Vec::new(),
    };

    // Asset-payload poll. Pick up any completed off-thread work first so a
    // fresh `reload_assets` below finds the in-flight slots empty. Cheap when
    // nothing is in flight (a Mutex lock + `None` check).
    poll_pending_envmap(state, backend);
    poll_pending_assets(state, backend);
    // Skeleton-shape changes queued by `poll_pending_assets` are applied to the
    // ECS-owned `SkeletonPose` components by the caller.
    effects.skeleton_updates = state.drain_pending_skeleton_updates();
    // Taken before the pass (success or failure) so a bad source file does not
    // loop forever.
    if state.signals.take_assets() {
        // Spawns up to two worker threads (asset decode + envmap convolution);
        // results land on a later frame via the poll calls above.
        reload_assets(state);
    }

    // World Shader and SdfVolume field reload: start a compile for every
    // subject a save touched, then swap in whichever compiles have finished.
    // The compile and the pipeline build run on a worker and a failed build is
    // never swapped in, so neither a slow compile nor a typo stalls or breaks
    // the live frame.
    let pending_shaders = state.signals.take_shaders();
    let mut reload_reports = Vec::new();
    if !pending_shaders.is_empty() {
        reload_reports = state
            .shaders
            .request(&pending_shaders, backend.pipeline_builder());
    }
    reload_reports.extend(state.shaders.poll(backend));
    let pending_volumes = state.signals.take_sdf_volumes();
    if !pending_volumes.is_empty() {
        reload_reports.extend(
            state
                .sdf_fields
                .request(&pending_volumes, backend.pipeline_builder()),
        );
    }
    reload_reports.extend(state.sdf_fields.poll(backend));
    super::report::report(&reload_reports, notify);
    effects.reload_reports = reload_reports;

    // Markdown story reload poll: re-expand the world's StoryImports and
    // queue every changed graph for the story system. Cheap when the flag is
    // unset.
    if state.signals.take_stories() {
        let path = state.world_jsonl_path.clone();
        if let Some(path) = path {
            effects.story_updates = reload_stories(&path, &mut state.story_snapshots);
            if !effects.story_updates.is_empty() {
                tracing::info!(
                    "story hot-reload: {} story graph(s) re-compiled",
                    effects.story_updates.len(),
                );
                if let Some(n) = notify {
                    n.success(&format!(
                        "{} story graph(s) reloaded",
                        effects.story_updates.len()
                    ));
                }
            }
        }
    }

    // world.jsonl reload poll: regenerate changed ProceduralMeshes first, then
    // re-apply VolumetricFog. Cheap when the flag is unset. (Prop diffing was
    // dropped with the positional render path; reworking it onto the per-entity
    // components is future work.)
    if state.signals.take_world() {
        let path = state.world_jsonl_path.clone();
        if let Some(path) = path {
            let pm_result = reload_procedural_meshes(&path, &mut state.procedural_meshes, backend);
            if pm_result.regenerated > 0 || pm_result.failed > 0 {
                tracing::info!(
                    "ProceduralMesh hot-reload: regenerated={} unchanged={} failed={}",
                    pm_result.regenerated,
                    pm_result.unchanged,
                    pm_result.failed,
                );
                if let Some(n) = notify {
                    if pm_result.failed > 0 {
                        n.error_with(
                            &format!("Mesh reload: {} failed", pm_result.failed),
                            Action::OpenConsole,
                        );
                    } else {
                        n.success(&format!("Meshes regenerated ({})", pm_result.regenerated));
                    }
                }
            }
            let fog_result = reload_volumetric_fog(&path, &mut fog.0, backend);
            if fog_result.updated {
                tracing::info!(
                    "VolumetricFog hot-reload: applied ({})",
                    match fog.0 {
                        Some(s) => format!(
                            "density={:.3} falloff={:.2} dist={:.0} g={:.2}",
                            s.density, s.height_falloff, s.max_distance, s.phase_g,
                        ),
                        None => "disabled".to_string(),
                    }
                );
            }
        }
    }

    effects
}