kiss3d Documentation

Start a local development server to preview the website. The server runs at http://localhost:3000 and supports live reloading for most changes.

npm start

To use kiss3d in your Rust project, add it to your Cargo.toml dependencies. The library is designed to be cross-platform, working on both native platforms and WASM.

[dependencies]
kiss3d = "0.37"

The website features interactive WebAssembly demos compiled from kiss3d examples. These are output to static/demos/.

To build all available demos:

npm run build:demos

To build a specific demo by name:

npm run build:demo <example_name>
# e.g., npm run build:demo cube

To deploy the static site to GitHub Pages, use the deploy script and provide your GitHub username via the GIT_USER environment variable:

GIT_USER=<Your GitHub username> npm run deploy

The #[kiss3d::main] macro simplifies writing kiss3d applications that target both native platforms and WebAssembly (WASM). It automatically handles the platform-specific boilerplate required to run an asynchronous main function.

How it works:

• On native platforms: It uses pollster::block_on to execute your async function.
• On WASM: It uses wasm_bindgen_futures::spawn_local to spawn the async function.

Requirements for the macro:

• The function must be named main.
• The function must be async.
• The function must not have any parameters.
• The function should utilize async rendering methods (e.g., render_async(), render_with_camera_async()).

#[kiss3d::main]
async fn main() {
    let mut window = Window::new("My App");
    while window.render_async().await {
        // Your render loop
    }
}

You can build the static site in two ways:

1. Build everything (both the website and all WASM demos):

npm run build:all

2. Build only the website (this assumes you have already built the demos separately):

npm run build

The resulting static files are located in the build directory.

Install the required npm packages for the website using:

npm install

To develop or build the kiss3d website, you need Node.js (v18+), Rust with the wasm32-unknown-unknown target, and the wasm-bindgen-cli tool.

Install the necessary Rust targets and CLI tools using:

rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli

The Camera3d trait defines the interface for all 3D cameras in kiss3d. You can implement this trait to create custom camera behaviors, such as specialized movement patterns or unique rendering logic.

Built-in implementations include:

• OrbitCamera3d: An orbital camera (the default).
• FirstPersonCamera3d: An FPS-style camera.
• FixedView3d: A static camera with a fixed view.

When implementing Camera3d, you must provide logic for:

• Event handling: Responding to WindowEvent via handle_event.
• Transformations: Providing the camera's position (eye), view transform (view_transform), and the combined projection/view matrix (transformation).
• Lifecycle: Updating state per frame via update and managing rendering passes via num_passes, start_pass, and render_complete.

Kiss3d can record 3D scenes to MP4 files. This requires FFmpeg to be installed on your system and the recording feature enabled in Cargo.toml.

FFmpeg Installation:

• macOS: brew install ffmpeg
• Ubuntu/Debian: sudo apt install ffmpeg libavcodec-dev libavformat-dev libavutil-dev libswscale-dev
• Windows: Download from ffmpeg.org and add to PATH.

Cargo.toml configuration:

[dependencies]
kiss3d = { version = "0.40", features = ["recording"] }

To use immediate mode GUI support within your kiss3d application, enable the egui feature in your Cargo.toml.

[dependencies]
kiss3d = { version = "0.40", features = ["egui"] }

An OrbitCamera3d (arc-ball camera) rotates around a fixed focus point (at) and always looks at it. It provides built-in interaction handling for mouse and keyboard inputs:

• Rotation: Left button press + drag rotates the camera around the focus point.
• Translation: Right button press + drag moves the focus point on the plane orthogonal to the view direction.
• Zoom: Scroll in/out changes the distance from the camera to the focus point.
• Reset: Pressing the designated reset key (default: Enter) sets the focus point to the origin (Vec3::ZERO).

// Camera looking at origin from 5 units away on the Z axis
let camera = OrbitCamera3d::new(Vec3::new(0.0, 0.0, 5.0), Vec3::ZERO);