browser-3d-environment/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Run

This is a Rust + wgpu project targeting WASM (primary) and native desktop. It uses Trunk as the WASM bundler.

# Dev server (WASM, hot-reload)
trunk serve -p 8080

# Production build (outputs to dist/)
trunk build --release

# Native desktop build
cargo run --release

# Type-check without building
cargo check

# LAN-accessible dev server (see justfile)
just serve-lan-ichigo

Prerequisites: cargo install trunk, rustup target add wasm32-unknown-unknown

This project uses the jj (jujutsu) version control system, with a git backend.

Architecture

Single-crate Rust app (wgpu-demo) that runs both natively and in-browser via WASM.

Rendering pipeline: wgpu with GL backend (WebGL2 in browser, OpenGL natively). Single render pipeline with two bind groups: camera uniform (group 0) and model uniform with dynamic offsets (group 1). Per-object transforms are written to a dynamic uniform buffer each frame (max 128 objects). Shader is WGSL (src/shader.wgsl) with directional + specular lighting.

Key modules:

• main.rs — winit ApplicationHandler impl, event loop, input dispatch, WASM async init dance (renderer created via spawn_local, shuttled back through thread_local PENDING_INIT)
• renderer.rs — wgpu setup, GPU mesh upload, render pass. Renderer::new() is async for adapter/device request
• camera.rs — FPS camera with yaw/pitch, mouse look. CameraUniform is the GPU-side struct
• mesh.rs — Procedural geometry (icosphere, octahedron, crosshair, spiked ball). All flat-shaded with per-face normals, no index buffers
• scene.rs — SceneObject placement with animated rotation. build_scene() generates all meshes and objects
• input.rs — HashSet<KeyCode> key tracking

Movement model: Z-up coordinate system. Axis-aligned (not camera-relative). W/S = Y (forward/back), A/D = X (left/right), E/Q = Z (up/down). Mouse look controls yaw/pitch.

WASM-specific: web-time replaces std::time::Instant. HUD overlays (help, coordinate bar) are HTML elements in index.html, manipulated via web-sys DOM calls from Rust. Pointer lock via winit's cursor grab API.

Vertex format: Position (vec3) + Normal (vec3) + Color (vec3), interleaved. bytemuck for zero-copy GPU upload.