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.

Follow development on X: @deepissuemassaj

• 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

There is still no perfect 1:1 Kotlin equivalent of three.js. materia is aiming at that gap: a scene-first Kotlin Multiplatform engine with three.js-style ergonomics, modern GPU backends, and a broad built-in runtime surface.

materia is still alpha, so this is best read as a positioning map rather than a maturity ranking. Today the shared JS/JVM/Android path is the strongest, while Apple and XR support are earlier than the core scene, material, loader, and rendering stack.

These numbers are measured on a specific reference machine and should be read as environment-specific samples, not universal guarantees.

• Methodology: 1920x1080 output, 120 warmup frames, 600 measured frames, and 3 repeats per scene/platform. Frame metrics use wall-clock timings around each render iteration. Heap values are deltas from the platform-reported heap baseline captured before scene boot.
• Frame metrics are CPU-side wall-clock timings around each render iteration, not GPU timestamp queries.
• Raw benchmark captures live in docs/benchmarks/data/raw/, and the aggregated snapshot lives in docs/benchmarks/data/latest.json.

Reference environment:

• JVM: Linux 6.18.21-1-cachyos-lts, Java 22.0.2, VULKAN on NVIDIA GeForce RTX 4090
• Web: Chrome 147.0.7727.55, WEBGPU on Adapter name unavailable
• Android: Pixel_9_Pro (sdk_gphone16k_x86_64), OPENGL, emulator / host-GPU-assisted result

Synthetic contract tests in the repo still exist for validation and guardrails, but the README table above is sourced only from these measured benchmark captures.

• JDK 17+
• Node.js ≥ 18 (for JS target)
• Android SDK API 34 (for Android target)
• Xcode 15+ with Metal-capable simulator/device (for Apple beta targets)
• Vulkan drivers or WebGPU-enabled browser

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

# Build all targets
./gradlew build

# Run tests
./gradlew test

# Generate coverage report
./gradlew koverHtmlReport

Run the Gradle-based examples directly, or open the Apple host apps in Xcode:

# Triangle demo
./gradlew :examples:triangle:runJvm          # Desktop
./gradlew :examples:triangle:jsBrowserRun    # Browser
./gradlew :examples:triangle:runMacos        # Apple Native (macOS host only)
open examples/triangle-ios-app/MateriaTriangleDemo.xcodeproj  # Native iOS host app

# Volume texture demo
./gradlew :examples:volume-texture:runJvm    # Desktop
./gradlew :examples:volume-texture:jsBrowserRun
open examples/volume-texture-ios-app/MateriaVolumeTextureDemo.xcodeproj  # iOS Simulator / My Mac (Mac Catalyst)

# 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.

Apple Beta: The active shared modules and example modules compile for iosArm64, iosX64, iosSimulatorArm64, macosArm64, and macosX64. The current runtime model is split:

• :examples:triangle exercises the shared Apple engine path. ./gradlew :examples:triangle:runMacos launches the macOS native executable, and examples/triangle-ios-app/MateriaTriangleDemo.xcodeproj hosts the exported MateriaTriangle framework on iOS.
• examples:volume-texture still uses the legacy root RendererFactory API. The current working Apple path is examples/volume-texture-ios-app/MateriaVolumeTextureDemo.xcodeproj, which packages the generated JS/WebGL bundle for iOS Simulator and My Mac (Mac Catalyst).

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

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

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

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.

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.

Materia is built on top of these excellent open source projects:

• wgpu4k – Kotlin Multiplatform bindings for wgpu, providing the unified WebGPU/Vulkan graphics backend
• korlibs-math – Kotlin Multiplatform math library from Korge, providing vectors, matrices, and quaternions

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

_{Built with ❤️ using Kotlin Multiplatform}