QSi is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install qsi

It will make the qsi command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall qsi uninstalls.

Adding `qsi` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add qsi

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

qsi = "0.2.0"

The qsi library will be automatically available globally. Read the qsi library documentation.

Back to the crate overview.

Readme

QSi

A lightweight, transparent 3D simulation library with ECS architecture.
Built on wgpu and winit for cross-platform 3D graphics.

Philosophy

Lightweight: Minimal dependencies, easy to understand
Transparent: You can see and modify everything
Flexible: ECS architecture allows for custom components and systems
Educational: Simple enough to understand completely
Performance: Designed for high-performance simulations

Quick Start

use qsi::prelude::*;

fn main() -> anyhow::Result<()> {
    App::new()
        .with_title("My App")
        .add_startup_system(setup_scene)
        .add_system(update_system)
        .run()
}

fn setup_scene(world: &mut World, renderer: &mut Renderer) {
    world.spawn()
        .with(Transform::default())
        .with(Camera::default());
}

fn update_system(world: &mut World, input: &InputState, time: &TimeState) {
    // Your update logic here
}

Architecture

Entity Component System (ECS)

Simple ECS with entities as integer IDs, components as data, systems as functions, and a world container.

Graphics Pipeline

Built on wgpu with mesh components, vertex/index buffers, and separate triangle/line rendering pipelines.

Core Systems

App: Main application runner with event loop
Graphics: wgpu-based rendering system
Input: Mouse and keyboard state management
Time: Frame timing and delta time calculation
Math: Transform component and matrix utilities
Camera: 3D camera with orbital controls

Current Features

Core ECS

Entity creation and management
Component storage with type safety
Query system for component iteration
Builder pattern for entity creation

Graphics Rendering

wgpu-based renderer
Vertex/index buffer management
Mesh component system
Triangle and line rendering pipelines
Depth testing
Basic shader (position + color)

Camera System

Camera component with orbital controller
Mouse controls (drag to rotate, wheel to zoom)
View matrix generation
Perspective projection

Input & Time

Mouse and keyboard input handling
Frame timing and FPS calculation
Delta time tracking
Timer utilities

Math

Transform component (position, rotation, scale)
Velocity component
Matrix operations via cgmath

Potential Additions

Graphics

Texture support
Basic lighting
Instanced rendering
Wireframe mode

ECS

System scheduling
Change detection
Resource management

Assets

Basic mesh loading (OBJ/glTF)
Texture loading

Physics

Simple collision detection
Basic physics integration

Features Intentionally Left Out

If you need these features, consider using Bevy instead:

Audio system
Complex UI framework
Advanced rendering (PBR, shadows, post-processing)
Animation system
Scripting support
Networking
Scene editor
Asset hot-reloading
Plugin architecture
Complex physics engine integration built-in
Platform-specific optimizations

Dependencies

wgpu: Graphics API abstraction
winit: Window management
cgmath: Linear algebra
anyhow: Error handling
bytemuck: GPU data transmutation

Controls

Mouse Drag: Rotate camera
Mouse Wheel: Zoom
Escape or Ctrl+C: Exit

Getting Started

Add to Cargo.toml:

[dependencies]
qsi = "0.1.0"
anyhow = "1.0"

Create your app:

use qsi::prelude::*;

fn main() -> Result<()> {
    App::new()
        .with_title("Simulation")
        .add_startup_system(setup)
        .run()
}

fn setup(world: &mut World, renderer: &mut Renderer) {
    // Add your simulation objects
}

Installing the command-line executable

Adding qsi library as a dependency

Adding `qsi` library as a dependency