proof_engine/

lib.rs

#![allow(dead_code, unused_variables, unused_imports, unused_mut, unused_parens, non_snake_case, unreachable_patterns, unused_assignments, unused_labels, unused_doc_comments, private_interfaces, non_camel_case_types, non_upper_case_globals, clippy::all)]

//! # Proof Engine
//!
//! A Rust engine for real-time graphics where every point, glyph and
//! particle on screen is moved by a real equation: an ODE, a force field, a
//! spring, a noise function.
//!
//! <img src="https://gitlab.com/mattbusel/proof-engine/-/raw/main/assets/gifs/strange_attractors.gif" width="100%" alt="Seven strange attractors, each 1,500 points integrated with RK4">
//!
//! ## The math runs without a window
//!
//! The integrators, attractors, fields and [`MathFunction`]s are plain Rust
//! and can be used on their own. This example runs as a doc test:
//!
//! ```rust
//! use proof_engine::math::attractors::{rk4_step, AttractorType};
//! use proof_engine::prelude::Vec3;
//!
//! // Two Lorenz states that start 0.0001 apart...
//! let mut a = Vec3::new(1.0, 1.0, 1.0);
//! let mut b = Vec3::new(1.0001, 1.0, 1.0);
//! for _ in 0..6000 {
//!     a = rk4_step(AttractorType::Lorenz, a, 0.005);
//!     b = rk4_step(AttractorType::Lorenz, b, 0.005);
//! }
//! // ...are far apart after 30 simulated seconds: that is chaos.
//! assert!((a - b).length() > 1.0);
//! ```
//!
//! ## Open a window and draw
//!
//! The `quickstart` example, in full. It needs a GPU with OpenGL 3.3, so it
//! is compiled here but not run:
//!
//! ```rust,no_run
//! use proof_engine::math::attractors::rk4_step;
//! use proof_engine::prelude::*;
//! use proof_engine::render::ui_layer::UiParticle;
//!
//! let mut engine = ProofEngine::new(EngineConfig::default());
//! let mut points: Vec<Vec3> = (0..5000)
//!     .map(|i| Vec3::new(1.0 + i as f32 * 4e-4, 1.0, 1.0))
//!     .collect();
//!
//! engine.run_ui(move |engine, dt| {
//!     for p in points.iter_mut() {
//!         *p = rk4_step(AttractorType::Lorenz, *p, dt);
//!     }
//!     let (w, h) = engine.render_size();
//!     let (cx, cy, s) = (w as f32 / 2.0, h as f32 / 2.0, h as f32 / 60.0);
//!     let color = Vec4::new(0.5, 1.2, 1.6, 1.0);
//!     let dots = points
//!         .iter()
//!         .map(|p| UiParticle::new(cx + p.x * s, cy - (p.z - 25.0) * s, 3.0, 3.0, '●', color))
//!         .collect();
//!     engine.ui.draw_particles(dots);
//! });
//! ```
//!
//! ## Where to look
//!
//! - [`ProofEngine`]: the window and main loop. [`ProofEngine::run`] for 3D
//!   glyph scenes, [`ProofEngine::run_ui`] for screen-space games and plots.
//! - [`EngineConfig`] and [`config::RenderConfig`]: window size, bloom,
//!   tonemap, grain and every other post-processing setting.
//! - [`Glyph`] and [`ProofEngine::spawn_glyph`]: the basic on-screen object.
//! - [`ForceField`], [`MathFunction`] and [`math::attractors`]: the math.
//! - [`render::ui_layer::UiParticle`]: fast screen-space points, as above.
//! - [`prelude`]: the common imports in one line.
//!
//! Every example in the repository can save its own frames to disk with the
//! `PROOF_SHOT` environment variables; see the
//! [README](https://gitlab.com/mattbusel/proof-engine#capture-frames-from-any-program).

pub mod math;
pub mod glyph;
pub mod entity;
pub mod particle;
pub mod scene;
pub mod render;
pub mod audio;
pub mod integration;
pub mod input;
pub mod config;
pub mod tween;
pub mod debug;
pub mod ui;
pub mod timeline;
pub mod procedural;
pub mod physics;
pub mod combat;
pub mod spatial;
pub mod effects;
pub mod anim;
pub mod animation;
pub mod ai;
pub mod networking;
pub mod replay;
pub mod scripting;
pub mod terrain;
pub mod ecs;
pub mod editor;
pub mod asset;
pub mod save;
/// Character stats, inventory, skills and quests.
pub mod character;
pub mod dsp;
pub mod game;
pub mod profiler;
pub mod vfx;
pub mod netcode;
pub mod network;
pub mod world;
pub mod crafting;
/// Navigation meshes, A* search and steering.
pub mod pathfinding;
pub mod economy;
pub mod behavior;
/// Atmosphere, precipitation and climate simulation.
pub mod weather;
pub mod deferred;
pub mod shader_graph;
pub mod surfaces;
pub mod rendergraph;
pub mod compute;
pub mod lighting;
pub mod number_theory;
/// Graph data structures, layout, community detection, paths and flows.
pub mod graph;
/// Hyperbolic, spherical and toroidal spaces and portals.
pub mod topology;
pub mod stochastic;
pub mod ml;
pub mod wgpu_backend;
pub mod geometry;
pub mod symbolic;
pub mod solver;
pub mod fractal;
pub mod metaball;
pub mod worldgen;
pub mod ecology;
pub mod narrative;
pub mod electromagnetic;
pub mod relativistic;
/// Quantum mechanics simulations: Schrodinger solvers, tunneling, entanglement and more.
pub mod quantum;
/// Sparse voxel octree global illumination (voxel cone tracing), not wired into the demos.
pub mod svogi;
pub mod curves;
pub mod nishita_sky;
pub mod volumetric_fog;
pub mod tiled_lighting;
pub mod export;
mod capture;

pub use config::EngineConfig;
pub use math::{MathFunction, ForceField, Falloff, AttractorType};
pub use glyph::{Glyph, RenderLayer, BlendMode};
pub use entity::AmorphousEntity;
pub use particle::{MathParticle, ParticleInteraction};
pub use scene::SceneGraph;
pub use render::camera::ProofCamera;
pub use input::{InputState, Key};
pub use render::pipeline::FrameStats;
pub use audio::AudioEvent;

/// The main engine struct. Create once, run forever.
pub struct ProofEngine {
    /// Engine settings; most render settings are read every frame.
    pub config: EngineConfig,
    /// The glyphs, particles and force fields in the world.
    pub scene: SceneGraph,
    /// The camera the world pass is drawn from.
    pub camera: ProofCamera,
    /// Keyboard and mouse state for the current frame.
    pub input: InputState,
    /// Screen-space UI, in pixel coordinates. Cleared at the start of every
    /// frame by `run_ui`, so games redraw it immediate-mode style.
    pub ui: render::ui_layer::UiLayer,
    /// Transient screen effects: shockwaves, flashes, light shafts. Fire and
    /// forget; ticked and uploaded by `run_ui` every frame.
    pub fx: render::screen_fx::ScreenFx,
    /// GPU density entities queued for this frame. Drained after the render.
    density_queue: Vec<particle::gpu_density::GpuDensityEntityData>,
    /// The particle budget per density entity, set by `init_gpu_density`.
    density_budget: u32,
    /// Optional audio engine — None if no output device is available.
    pub audio: Option<audio::AudioEngine>,
    // Internal render pipeline (initialized lazily when run() is called)
    pipeline: Option<render::Pipeline>,
}

impl ProofEngine {
    /// Create the engine. The window and GL context are created when `run`
    /// or `run_ui` is called; audio starts now if enabled and a device exists.
    pub fn new(mut config: EngineConfig) -> Self {
        if let Some((w, h)) = capture::window_size() {
            config.window_width = w;
            config.window_height = h;
        }
        let audio = if config.audio.enabled {
            audio::AudioEngine::try_new()
        } else {
            None
        };
        Self {
            camera: ProofCamera::new(&config),
            scene: SceneGraph::new(),
            input: InputState::new(),
            ui: render::ui_layer::UiLayer::new(
                config.window_width as f32,
                config.window_height as f32,
            ),
            fx: render::screen_fx::ScreenFx::new(),
            density_queue: Vec::new(),
            density_budget: 0,
            audio,
            config,
            pipeline: None,
        }
    }

    /// Turn on GPU density entities with a per-entity particle budget.
    ///
    /// The budget is capped at
    /// [`MAX_PARTICLES_PER_ENTITY`](particle::gpu_density::MAX_PARTICLES_PER_ENTITY):
    /// past that there are more particles than pixels and the picture stops
    /// improving while the frame time keeps climbing. Asking for more is
    /// fine; you get the cap and a log line.
    pub fn init_gpu_density(&mut self, particles: u32) {
        let cap = particle::gpu_density::MAX_PARTICLES_PER_ENTITY;
        if particles > cap {
            log::info!("gpu density: {particles} particles requested, drawing {cap} per entity");
        }
        self.density_budget = particles.min(cap);
    }

    /// Draw a density entity this frame. Call every frame it should show.
    pub fn queue_gpu_density_entity(&mut self, entity: particle::gpu_density::GpuDensityEntityData) {
        self.density_queue.push(entity);
    }

    /// Send an audio event. No-op if audio is unavailable.
    pub fn emit_audio(&self, event: audio::AudioEvent) {
        if let Some(ref a) = self.audio {
            a.emit(event);
        }
    }

    /// Run the engine. Calls `update` every frame with elapsed seconds.
    /// Blocks until the window is closed.
    pub fn run<F>(&mut self, mut update: F)
    where
        F: FnMut(&mut ProofEngine, f32),
    {
        self.run_with_overlay(move |engine, dt, _gl| {
            update(engine, dt);
        });
    }

    /// Run the engine with an overlay callback.
    /// The overlay callback receives the glow GL context reference and is called
    /// AFTER scene rendering but BEFORE buffer swap — perfect for egui.
    pub fn run_with_overlay<F>(&mut self, mut update: F)
    where
        F: FnMut(&mut ProofEngine, f32, &glow::Context),
    {
        let pipeline = render::Pipeline::init(&self.config);
        self.pipeline = Some(pipeline);
        let mut capture = capture::Capture::from_env();
        let fixed_dt = capture::fixed_dt();

        let mut last = std::time::Instant::now();
        loop {
            let now = std::time::Instant::now();
            let dt = fixed_dt.unwrap_or_else(|| now.duration_since(last).as_secs_f32().min(0.1));
            last = now;

            // Poll input
            if let Some(ref mut p) = self.pipeline {
                if !p.poll_events(&mut self.input) {
                    break;
                }
            }

            // Step force fields and physics
            self.scene.tick(dt);

            // User update (logic only — no GL calls here)
            // We pass a dummy gl ref for the logic phase; the real painting
            // happens after the scene render.
            let gl_ptr = self.pipeline.as_ref().map(|p| p.gl() as *const glow::Context);

            // Sync render config so runtime changes (particle_multiplier, bloom, etc.)
            // take effect this frame.
            if let Some(ref mut p) = self.pipeline {
                p.update_render_config(&self.config.render);
            }

            // Render scene first
            if let Some(ref mut p) = self.pipeline {
                p.set_density_entities(&self.density_queue, self.density_budget);
                p.render(&self.scene, &self.camera);
            }
            self.density_queue.clear();
            self.fx.lights.clear();

            // NOW paint the overlay (egui) on top of the rendered scene
            if let Some(ptr) = gl_ptr {
                let gl_ref = unsafe { &*ptr };
                update(self, dt, gl_ref);
            }

            // PROOF_SHOT: read the finished frame back before it is swapped away.
            if let Some(ref mut c) = capture {
                if c.after_draw(self) {
                    break;
                }
            }

            // Honour a quit asked for during the update, as `run_ui` does.
            if self.input.quit_requested {
                break;
            }

            // Swap
            if let Some(ref mut p) = self.pipeline {
                if !p.swap() {
                    break;
                }
            }
        }
    }

    /// Run a UI-driven game.
    ///
    /// Unlike \[`run`\], `update` is called *before* the scene is drawn, and the
    /// screen-space `ui` layer is painted afterwards. That ordering matters for
    /// a game: what you push this frame is what appears this frame, rather than
    /// showing up one frame late.
    ///
    /// The UI layer is cleared before each `update`, so games redraw it in full
    /// every frame instead of tracking what to erase.
    pub fn run_ui<F>(&mut self, mut update: F)
    where
        F: FnMut(&mut ProofEngine, f32),
    {
        let pipeline = render::Pipeline::init(&self.config);
        self.pipeline = Some(pipeline);

        // Size the UI layer from the framebuffer, which is what the viewport
        // uses; the window's own size can differ on a scaled display.
        let (w, h) = self.render_size();
        self.ui.resize(w as f32, h as f32);

        let mut capture = capture::Capture::from_env();
        let fixed_dt = capture::fixed_dt();

        let mut last = std::time::Instant::now();
        let mut last_size = (w, h);
        loop {
            let now = std::time::Instant::now();
            let dt = fixed_dt.unwrap_or_else(|| now.duration_since(last).as_secs_f32().min(0.1));
            last = now;

            if let Some(ref mut p) = self.pipeline {
                if !p.poll_events(&mut self.input) {
                    break;
                }
            }

            // Keep the UI projection matched to the framebuffer.
            let size = self.render_size();
            if size != last_size {
                last_size = size;
                self.ui.resize(size.0 as f32, size.1 as f32);
            }

            self.scene.tick(dt);

            // Game logic and UI construction, both before anything is drawn.
            self.ui.begin_frame();
            update(self, dt);

            // Honour a quit asked for during the update.
            //
            // `request_quit` used to set a flag that nothing read, so a game's
            // own Quit menu did nothing at all and the only way out was the
            // window's close button. The check goes here, after the update and
            // before the render, so the frame that asked to quit is the last
            // one and nothing half-drawn reaches the screen.
            if self.input.quit_requested {
                break;
            }

            // Trauma decays here. It used to be added and never ticked in
            // this loop, so the first hit left the camera shaking forever.
            self.camera.shake.tick(dt);
            self.fx.tick(dt);

            if let Some(ref mut p) = self.pipeline {
                p.update_render_config(&self.config.render);
                p.set_density_entities(&self.density_queue, self.density_budget);
                // The scene, then the UI's world pass into the same buffer,
                // then post-processing over both.
                p.render_frame(&self.scene, &self.camera, Some(&self.ui), &self.fx);
                // The HUD, painted after post-processing so it stays sharp.
                p.render_ui(&self.ui);
            }
            self.density_queue.clear();
            self.fx.lights.clear();

            if let Some(ref mut c) = capture {
                if c.after_draw(self) {
                    break;
                }
            }

            if let Some(ref mut p) = self.pipeline {
                if !p.swap() {
                    break;
                }
            }
        }
    }

    /// Add a force field to the scene.
    pub fn add_field(&mut self, field: ForceField) -> scene::FieldId {
        self.scene.add_field(field)
    }

    /// Remove a force field.
    pub fn remove_field(&mut self, id: scene::FieldId) {
        self.scene.remove_field(id)
    }

    /// Spawn a glyph into the scene.
    pub fn spawn_glyph(&mut self, glyph: Glyph) -> glyph::GlyphId {
        self.scene.spawn_glyph(glyph)
    }

    /// Spawn an amorphous entity, creating its formation glyphs.
    pub fn spawn_entity(&mut self, mut entity: AmorphousEntity) -> entity::EntityId {
        // If no formation was specified, generate a default diamond
        if entity.formation.is_empty() {
            use entity::formation::Formation;
            let f = Formation::diamond(2);
            entity.formation = f.positions;
            entity.formation_chars = f.chars;
        }
        // Ensure colors are filled (white if unspecified)
        while entity.formation_colors.len() < entity.formation.len() {
            entity.formation_colors.push(glam::Vec4::ONE);
        }
        // Spawn one glyph per formation slot
        for i in 0..entity.formation.len() {
            let offset = entity.formation[i];
            let ch = entity.formation_chars.get(i).copied().unwrap_or('◆');
            let color = entity.formation_colors.get(i).copied().unwrap_or(glam::Vec4::ONE);
            let id = self.scene.spawn_glyph(Glyph {
                character: ch,
                position: entity.position + offset,
                color,
                emission: 0.8,
                glow_color: glam::Vec3::new(color.x, color.y, color.z),
                glow_radius: 1.2,
                mass: entity.entity_mass / entity.formation.len().max(1) as f32,
                layer: RenderLayer::Entity,
                ..Default::default()
            });
            entity.glyph_ids.push(id);
        }
        self.scene.spawn_entity(entity)
    }

    /// Emit a burst of particles at a position.
    pub fn emit_particles(&mut self, emitter: particle::EmitterPreset, origin: glam::Vec3) {
        particle::emit(&mut self.scene, emitter, origin);
    }

    /// Apply trauma (screen shake). 0.0 = none, 1.0 = maximum.
    pub fn add_trauma(&mut self, amount: f32) {
        self.camera.add_trauma(amount);
    }
}

/// Request quit on next frame.
impl ProofEngine {
    /// Ask the run loop to exit at the end of the current frame.
    pub fn request_quit(&mut self) {
        self.input.quit_requested = true;
    }

    /// Get a reference to the glow GL context (for egui integration).
    /// Returns None if the pipeline hasn't been initialized yet.
    pub fn gl(&self) -> Option<&glow::Context> {
        self.pipeline.as_ref().map(|p| p.gl())
    }

    /// Get the window reference (for egui-winit event processing).
    pub fn window(&self) -> Option<&winit::window::Window> {
        self.pipeline.as_ref().map(|p| p.window())
    }

    /// Get the current window size in pixels.
    pub fn window_size(&self) -> (u32, u32) {
        self.pipeline.as_ref().map(|p| p.window_size()).unwrap_or((1600, 1000))
    }

    /// The framebuffer size, in the same units the viewport uses.
    ///
    /// Screen-space UI must lay out against this, not the window size: on a
    /// scaled display the two differ and the UI ends up magnified.
    pub fn render_size(&self) -> (u32, u32) {
        self.pipeline.as_ref().map(|p| p.render_size()).unwrap_or((1600, 1000))
    }

    /// The frame currently in the back buffer, as RGBA8 with the top row
    /// first, or `None` before the window exists.
    ///
    /// Read straight off the GPU after post-processing, so it is exactly
    /// what the pipeline drew. Asking the window manager for a picture of a
    /// hardware-accelerated window is unreliable: it hands back whatever it
    /// last cached, which can be a stale frame or a blank one.
    pub fn frame_pixels(&self) -> Option<(u32, u32, Vec<u8>)> {
        let p = self.pipeline.as_ref()?;
        let (w, h, mut rgba) = p.read_frame();
        if w == 0 || h == 0 {
            return None;
        }
        export::flip_rows(w, h, &mut rgba);
        Some((w, h, rgba))
    }

    /// Write the frame currently on screen to an image file.
    ///
    /// The extension picks the format (`.png`, `.jpg`, `.bmp`, `.tga`,
    /// `.gif`); an unknown extension writes a BMP, as this always did
    /// before. The image is opaque. See [`export`] for animated GIFs and for
    /// saving buffers of your own.
    pub fn save_frame(&self, path: &str) -> std::io::Result<()> {
        let (w, h, rgba) = self.frame_pixels().ok_or_else(|| {
            std::io::Error::new(std::io::ErrorKind::Other, "no frame to read: the window is not open")
        })?;
        export::save_opaque(path, w, h, &rgba)
    }
}

/// Common imports for using Proof Engine.
pub mod prelude {
    pub use crate::{
        ProofEngine, EngineConfig,
        MathFunction, ForceField, Falloff, AttractorType,
        Glyph, RenderLayer, BlendMode,
        AmorphousEntity,
        MathParticle, ParticleInteraction,
        AudioEvent,
        particle::EmitterPreset,
        render::camera::ProofCamera,
        input::{InputState, Key},
        scene::{SceneGraph, FieldId},
        audio::MusicVibe,
        tween::{Tween, Easing, TweenState, Tweens, AnimationGroup},
        tween::easing::Easing as EasingFn,
        tween::keyframe::{KeyframeTrack, Keyframe, CameraPath, ExtrapolateMode},
        tween::sequence::{TweenSequence, TweenTimeline, SequenceBuilder},
        debug::DebugOverlay,
        render::pipeline::FrameStats,
        render::screen_fx::{ScreenFx, ScreenLight, Shockwave},
        render::ui_layer::UiPass,
    };
    // Quat and Mat4 belong here too: the skeleton and animation APIs hand out
    // transforms built from them, so a caller who only has the prelude cannot
    // pose a figure without reaching past it into glam.
    pub use glam::{Mat4, Quat, Vec2, Vec3, Vec4};
}