Skip to content

Latest commit

 

History

History
209 lines (142 loc) · 13.5 KB

DETAILS.md

File metadata and controls

209 lines (142 loc) · 13.5 KB

Proof Engine: details

The full README before it was cut down. Back to the short README.


Games where everything is particles and really breaks. No meshes. Destruction, cloth and fluid come from one spring-physics system.

Mesh engines need a system per kind of damage. This uses one, with different spring constants. It runs CHAOS RPG and O'BLOCK (free on Steam).

If it doesn't do what this README says, open an issue and I'll fix it.

Proof Engine

English | 简体中文 | 日本語 | 한국어

Write the equations. Proof Engine draws what they do, in real time, with HDR glow.

A Rust graphics engine plus ready-to-run demos.

Download for Windows (.exe)  ·  macOS and Linux  ·  Shipped game: O'BLOCK on Steam  ·  Site  ·  docs.rs  ·  crates.io version  CI  MSRV 1.88

The galaxy example running: about 3,000 glyphs on four spiral arms, each on its own circular orbit, with a hot core and dim red outer arms, seen at an angle as the camera circles.

The galaxy demo, recorded from the engine's own framebuffer.

Rust on OpenGL. Points and glyphs move by differential equations (Lorenz and six other strange attractors), force fields and physics. Then a half-float HDR pipeline draws them with bloom and an ACES tonemap.

Shipped on Steam: O'BLOCK

O'BLOCK, a sneaker-flipping roguelike that runs on Proof Engine

I shipped O'BLOCK on Steam on it. A sneaker-flipping roguelike: haggle with buyers who bluff, build a resale empire, don't draw heat. Free to play, so you can see the engine in a real release.

Shipping it meant adding Chinese, Japanese and Korean text to the glyph atlas: Adding Chinese, Japanese and Korean text to a Rust OpenGL game engine.

Download

System Download
Windows proof-lorenz.exe: double-click it. Or all 10 demos and the editor (.zip).
macOS (Apple silicon / Intel) demos for arm64 / demos for x64
Linux (x86_64) proof-engine-demos-linux-x64.tar.gz
Your own Rust program cargo add proof-engine

No Rust needed. Just a GPU with OpenGL 3.3+. Unsigned: on Windows click More info, then Run anyway. macOS and Linux notes: docs/INSTALL.md.

Math screensaver

Ten strange attractors as a Windows screensaver, computed live. Download proof-screensaver.scr, put it somewhere it can stay, right-click, Install (or copy it into C:\Windows\System32 and pick proof-screensaver in Screen Saver Settings). Settings... opens its options. Uninstall and more: docs/SCREENSAVER.md.

How it works

Animated diagram, how math becomes a frame, for one frame of the lorenz example. 1 Math: RK4 steps 40,000 Lorenz states on the CPU. 2 Glyphs: each state becomes one glyph instance, placed from x and z and coloured by its speed, all drawn in one instanced call. 3 Light: a half-float HDR buffer where overlaps add up past 1.0, trails keep 55 percent of the last frame, bloom blurs the glow. 4 Frame: exposure, ACES tonemap and vignette, then the HUD text painted sharp on top.

Each frame: your code moves the points. The engine makes each point a glyph. The GPU adds up their light in an HDR buffer. The composite turns light into the picture. One real frame after each stage:

The lorenz example captured by the engine at the same frame three ways: the glyph pass alone, a grainy butterfly of dots; with trails and bloom, the loops fill in and glow; with the tonemap and grade, deeper blacks and warmer highlights.

Examples

Real captures of cargo run --release --example <name> (or proof-<name>.exe).

lorenz strange_attractors
40,000 points circling the two wings of the Lorenz attractor, teal where slow and amber where fast. Seven strange attractors, Lorenz, Rossler, Chen, Halvorsen, Aizawa, Thomas and Dadras, 1,500 points each, turning slowly.
40,000 points on the Lorenz equations. Nobody drew the wings. Seven chaotic systems, 1,500 points each. Colour is speed.
sky math_rain
The sky example in late afternoon: a blue sky fading to white near the sun over brown mountains. A hundred columns of green mathematical symbols falling at different speeds, the leading glyph of each bright white-green.
A day passing. Each sky cell is a Rayleigh and Mie scattering integral, every frame. Falling math symbols. Speed from a sine, flicker from a logistic map.

All 21 demos and their controls: docs/DEMOS.md.

Use it in 3 steps

1. Make a project and add the engine.

cargo new lorenz-demo && cd lorenz-demo
cargo add proof-engine

2. Replace src/main.rs with this (also in the repo as examples/quickstart.rs):

use proof_engine::math::attractors::rk4_step;
use proof_engine::prelude::*;
use proof_engine::render::ui_layer::UiParticle;

fn main() {
    let mut engine = ProofEngine::new(EngineConfig::default());

    // 5,000 points in a line 2 units long, each 0.0004 from the next.
    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| {
        // Advance every point along the Lorenz equations.
        for p in points.iter_mut() {
            *p = rk4_step(AttractorType::Lorenz, *p, dt);
        }
        // Draw them: x across, z up, centred in the window.
        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);
    });
}

3. Run it with cargo run --release. The points move as one streak for about ten seconds. Then chaos pulls them into the Lorenz butterfly:

Four real frames of the quickstart program. At 1 second a tiny speck; at 13.5 seconds a thin arc; at 16 seconds the points have split into loops; at 18.5 seconds they fill both wings of the Lorenz butterfly.

Linux needs the ALSA headers first (sudo apt install libasound2-dev pkg-config). Always build with --release.

More

Record a GIF of any demo. The engine reads its own frames and writes the GIF. The window stays hidden.

PROOF_HIDDEN=1 PROOF_FIXED_DT=30 PROOF_SHOT=lorenz.gif PROOF_SHOT_AT=300 \
PROOF_SHOT_COUNT=120 PROOF_SHOT_WIDTH=480 cargo run --release --example lorenz

Use .png or .jpg for one picture. Settings: docs/CAPTURE.md.

Try your own equations without recompiling. Write them in Rhai, a small scripting language. The whole Thomas attractor:

let b = 0.208186;
[sin(y) - b * x, sin(z) - b * y, sin(x) - b * z]

Draw it, and redraw on every save:

cargo run --release --example scripted_attractor -- examples/scripts/thomas.rhai thomas.png --dt 0.05 --map turbo --watch

A typo shows where it is and keeps the last good picture. In your own program, math::scripted::ScriptedSystem does the same.

Colour maps. math::color::preset_gradient("viridis") gives any of 38 standard maps (viridis, magma, turbo, cubehelix, ColorBrewer). Gradient::from_css("#000, deeppink 40%, gold") takes a CSS gradient.

Sound to a file. audio::OfflineRenderer runs the synth with no sound card. audio::wav::write_wav saves it. Try cargo run --release --example audio_bounce.

Every core. math::attractors::rk4_step_all(kind, &mut points, dt) steps a whole slice. With parallel it uses rayon. On an i7-13700KF, 40,000 Lorenz points take 1.21 ms per frame on one core, 0.10 ms with parallel (cargo bench --bench attractor_bench). Same bits either way.

Cargo features

Feature Default What it adds
rhai-scripts on math::scripted: systems written in Rhai, hot reloaded
parallel off multi-core rk4_step_all (rayon)
http off real requests for networking::http, the leaderboard and analytics clients (ureq, rustls)
websocket off real ws:// / wss:// connections for networking::websocket (tungstenite, rustls)
net off http + websocket

Without http / websocket the network clients return an error. No feature pulls in OpenSSL.

How it compares

  • nannou: general creative coding (wgpu, draw API, audio, OSC). Use it for general sketches.
  • macroquad: small game library that runs on the web. Use it for 2D browser games.
  • Proof Engine: narrower. Glyphs and particles moved by equations, HDR bloom, with attractors, force fields, colour maps, scripts and frame capture built in. Tests check the equations against ode_solvers (Lorenz, Rossler, Thomas, Aizawa and Chen, written out separately).

Documentation

Doc What is in it
Install and run Every download, macOS/Linux notes, building from source, project status
Demos All 21 examples with pictures and controls, the sky and Lorenz write-ups
How it works The frame pipeline, engine.fx, lights, GPU density, sound, what each module holds
Capture frames PROOF_SHOT and PROOF_HIDDEN: record any program's frames without a window appearing
Proof Editor The scene editor, its download and keys
Screensaver Proof Saver: install, settings, live-art mode, building the .scr
docs.rs The full API
Changelog · Contributing Release history and how to send a change

chaos-rpg is a roguelike with a frontend on Proof Engine. CHAOS_RPG_API_CONTRACT.md lists what it needs.

Built with

Windows and OpenGL: winit, glutin, glow. Math: glam. Text: ab_glyph. Sound: cpal. Images and GIFs: image. WAV: hound. Colour maps: colorgrad. Scripts: rhai. Saves: serde_json.

License

MIT, see LICENSE.

Source, issues and stars: GitHub. Mirror and release downloads: GitLab. More of my Rust: tensorust.com/open-source.

Hire the author

I build LLM features, iOS apps and performance fixes for clients. Fixed price. Services and pricing · Email · LinkedIn