# Sim;Engine
Sim;Engine is a validated visualization library built for simulation products.
It provides a high-performance 2D renderer, scientific visualization paths,
and a focused retained 3D stereometry pipeline.
Sim;X is the primary consumer and design driver, but the crate is reusable.
Applications provide ready visual state. Sim;Engine owns cameras, drawing,
clipping, interpolation, GPU resources, composition, recovery, and rendering
diagnostics. Physics, simulation stepping, domain entities, UI navigation, and
plugins remain in the host application.
Version **0.1.0** is the first official Sim;Engine release. The crate remains
pre-1.0, and its supported release target is Linux with Vulkan. A concrete
adapter/driver is supported when the mandatory semantic fixture passes on it;
untested drivers are not inferred from Mesa evidence. The minimum supported
Rust version is 1.90.
## Documentation
- [Library documentation](DOCUMENTATION.md) - installation, concepts, every
rendering path, recovery, performance, architecture, and examples.
- [Changelog](CHANGELOG.md) - release history and user-visible changes.
- Generated API reference:
```bash
cargo doc --all-features --no-deps --open
```
## Capabilities
- validated circles, rectangles, rounded rectangles, lines, and polylines;
- solid, linear-gradient, and radial-gradient fills;
- logical-pixel strokes, shadows, clipping, and stable layer ordering;
- 2D camera pan, rotation, zoom, fit, and picking;
- fallible tweening and easing;
- streaming, prepared, and dynamic triangle geometry;
- budgeted instanced particle rendering;
- scalar-field textures, color maps, partial updates, and heatmaps;
- offscreen targets, composition, and bounded trails;
- device recovery with explicit retained-resource restoration;
- typed logical-pixel, 3D world-length, and target-scale boundaries;
- retained 3D meshes, independent transforms, hardware depth, and visible or
dashed hidden mathematical edges;
- atomic retained-3D scene recovery that preserves stable object IDs and visual
state across logical-device replacement.
Translucent section materials, hatching, projected 3D anchors, and 3D picking
are not part of v0.1.0.
## Installation
The default feature set includes the `wgpu` renderer:
```toml
[dependencies]
sim-engine = "0.1"
```
Use core visual-state APIs without GPU dependencies:
```toml
[dependencies]
sim-engine = { version = "0.1", default-features = false }
```
## Quick Start
```rust
use sim_engine::{Camera2d, Color, Rect, Scene, ShapeStyle, Vec2};
let camera = Camera2d::new(Vec2::ZERO, 2.0)?;
let mut scene = Scene::new(Color::rgb8(12, 14, 18))?;
scene.try_circle(
Vec2::new(10.0, 20.0),
8.0,
ShapeStyle::filled(Color::rgb8(86, 195, 255)),
)?;
scene.try_rect(
Rect::from_center_size(Vec2::ZERO, Vec2::new(120.0, 64.0)),
8.0,
ShapeStyle::fill_stroke(
Color::rgb8(24, 31, 44),
2.0,
Color::rgb8(86, 195, 255),
),
)?;
# let _ = camera;
# Ok::<(), Box<dyn std::error::Error>>(())
```
Window creation stays in the host. Renderer initialization is asynchronous;
steady-state updates and rendering are synchronous submissions:
```rust,ignore
let options = WgpuRendererOptions::new(
RendererPresentMode::Vsync,
window.scale_factor(),
)?;
let mut renderer = WgpuRenderer::new_with_options(
window.clone(),
width,
height,
options,
).await?;
let report = renderer.render_with_metrics(&scene, &camera)?;
```
## Choose A Rendering Path
| Small changing scene | `Scene` |
| Static geometry with a moving camera | `PreparedScene` |
| Frequently changing triangles | `DynamicMesh2d` |
| Large point or circle population | `ParticleField2d` |
| Dense scalar grid | `ScalarFieldTexture` |
| Bounded gas plus particle overlay | `render_layered_visualization` |
| Stereometry solids and hidden edges | `Mesh3d` plus `Scene3d` |
## Examples
```bash
cargo run --release --example demo
cargo run --release --example ui_demo -- --uncapped
cargo run --release --example star_remnant_stress -- --benchmark
cargo run --release --no-default-features --example particle_cpu_benchmark
cargo run --release --example stereometry_3d -- --uncapped
cargo run --release --example cylinder_derivation_3d -- --uncapped --benchmark
```
## Verification
The v0.1.0 Linux release gate checks the declared Rust 1.90 MSRV, all targets with
and without the renderer, strict clippy, rustdoc, Vulkan semantic GPU readback
with a backend assertion, and the publishable package boundary:
```bash
./scripts/linux_release_gate.sh
```
The gate records the exact adapter/backend/driver run in
`target/linux-vulkan-adapter.txt`; CI publishes the same file as an artifact.
## License
Licensed under either
[MIT](https://github.com/lexawhatt/Sim-Engine/blob/main/LICENSE) or
[Apache-2.0](https://github.com/lexawhatt/Sim-Engine/blob/main/LICENSE-APACHE),
at your option.