Materia

Kotlin Multiplatform 3D Engine

Modern rendering toolkit targeting WebGPU, Vulkan, and emerging XR surfaces with Three.js-style ergonomics.

⚠️ Alpha Software – Materia is under active development. APIs may change between releases. Not recommended for production use yet.

---

✨ Highlights

• Unified Rendering API – Write once, render everywhere with expect/actual abstractions over WebGPU, Vulkan (LWJGL), and Metal (MoltenVK)
• Three.js-Style API – Familiar scene graph, materials, cameras, controls, and lighting patterns for easy adoption
• Performance-First – Arena allocators, uniform ring buffers, GPU resource pooling, and automatic instancing
• Comprehensive Loaders – GLTF 2.0, OBJ, FBX, Collada, PLY, STL, DRACO, KTX2, HDR/EXR textures, fonts
• Full Controls Suite – OrbitControls, FlyControls, PointerLockControls, TrackballControls, DragControls, TransformControls
• Debug Helpers – AxesHelper, GridHelper, BoxHelper, ArrowHelper, CameraHelper, light helpers
• Cross-Platform Audio – Positional audio and analyser abstractions aligned with the camera system
• Production Ready – Built-in validation, Kover coverage, and dependency scanning pipelines

---

🎯 Platform Support

Platform	Backend	Status
Browser (JS/WASM)	WebGPU (WebGL2 fallback)	✅ Ready
JVM (Linux/macOS/Windows)	Vulkan via LWJGL 3.3.6	✅ Ready
Android	Vulkan (API 24+)	✅ Ready
Native (macOS/iOS)	MoltenVK	🟡 In Progress

---

🚀 Quick Start

Prerequisites

• JDK 17+
• Node.js ≥ 18 (for JS target)
• Android SDK API 34 (for Android target)
• Vulkan drivers or WebGPU-enabled browser

Build

git clone https://github.com/codeyousef/Materia.git
cd Materia

# Build all targets
./gradlew build

# Run tests
./gradlew test

# Generate coverage report
./gradlew koverHtmlReport

---

📦 Examples

Run any example with Gradle:

# Triangle demo
./gradlew :examples:triangle:runJvm          # Desktop
./gradlew :examples:triangle:jsBrowserRun    # Browser

# VoxelCraft (Minecraft-style demo)
./gradlew :examples:voxelcraft:runJvm
./gradlew :examples:voxelcraft:jsBrowserRun

# Embedding Galaxy (particle visualization)
./gradlew :examples:embedding-galaxy:runJvm

# Force Graph (network visualization)  
./gradlew :examples:force-graph:runJvm

Browser Requirements: Chrome 113+, Edge 113+, or Firefox Nightly with WebGPU enabled.

Android: Connect a device/emulator with Vulkan support, then run :examples:triangle-android:installDebug.

---

🏗️ Project Structure

materia-engine/         # Core: scene graph, materials, animation
materia-gpu/            # GPU abstraction: WebGPU/Vulkan backends
materia-postprocessing/ # Post-processing effects pipeline
materia-validation/     # Production readiness validation CLI
examples/               # Multiplatform example applications
docs/                   # API reference and guides

---

📖 Documentation

• Getting Started Guide
• API Reference
• Architecture Overview
• Platform-Specific Notes

---

🔧 Development

Quality Gates

./gradlew build                       # Compile + tests
./gradlew koverVerify                 # Coverage check (50% minimum)
./gradlew lintDebug                   # Android lint
./gradlew dependencyCheckAnalyze      # Security audit
./gradlew validateProductionReadiness # Full validation suite

Shader Compilation

The project uses dual shader sources:

• WebGPU (JS): WGSL strings in Kotlin code
• Vulkan (JVM): Pre-compiled SPIR-V in src/jvmMain/resources/shaders/

Run ./gradlew compileShaders to regenerate SPIR-V from WGSL sources.

---

🤝 Contributing

Contributions welcome! Please:

1. Fork and create a feature branch
2. Add tests for new functionality
3. Run quality gates before submitting
4. Open a PR with clear description

See CONTRIBUTING.md for detailed guidelines.

---

📄 License

Apache License 2.0 – Use freely in commercial and open source projects.

---

_{Built with ❤️ using Kotlin Multiplatform}