🌌 Spatial

Declarative 3D Rendering for Android inspired by Jetpack Compose

Modern • Reactive • Cinematic • GPU-Abstracted

📜 License

Spatial is licensed under the PolyForm Shield License 1.0.0.

You may embed Spatial in your own applications — including commercial apps — free of charge, modify it for that purpose, and redistribute it with your application, as long as you keep the required copyright and license notices.

You may not copy, fork, or rebrand this codebase to publish a competing 3D library, SDK, or practical substitute for Spatial, and you may not remove or obscure authorship.

✨ Vision

Spatial is a modern declarative 3D rendering library for Android inspired by Jetpack Compose.

Its goal is to make 3D scene creation feel as natural and expressive as Compose, while completely hiding the complexity of OpenGL and GPU pipelines from the developer.

For a more detailed explanation: https://deepwiki.com/danielitoCode/Spatial

Spatial is not intended to become a full game engine.

Instead, it focuses on:

Declarative scene composition
Smooth cinematic motion
State-driven rendering
Compose-first APIs
Natural gestures
Modular rendering architecture
Clean GPU abstraction

🎯 Core #1 Goals

Core #1 exposes its public Compose API from the root com.elitec.spatial_compose package.

Public consumer entry points

For Pilar 1, application and playground consumers should depend on :spatial-compose as the public facade for scene authoring. Load GLB assets with Element.Model(model = ModelResource.fromRawResource(R.raw.my_model), ...); spatial-compose delegates parsing internally, so consumers should not depend directly on :spatial-geometry unless they are building a dedicated diagnostic parser screen.

Material changes for rendered primitives or GLB models should be expressed through Modifier3D.color(...) for simple flat colors or Modifier3D.material(...) when a caller needs to pass the public material data object. The :spatial-material module is reserved for the material implementation and future texture/shader metadata APIs; apps should add implementation(project(":spatial-material")) only after a deliberate public material API is exposed from that module.

Current status

Core #1 remains In Development. This status must only change when the Core #1 contracts and tests are closed and passing against the real public API. Until then, README badges, phase notes, and release messaging must not describe Core #1 as complete or stable.

Included

Essential 3D primitives
Orbit camera
Smooth zoom
Inertia and damping
Declarative scene API
Basic camera/transform motion system
Gesture system
Flat-color material rendering (no active lighting/shading in Core #1)
Material abstraction
Units system
GPU abstraction layer
Compose integration

Intentionally Excluded

Physics
ECS
PBR
Shadows
Real lighting and shaded light evaluation
Vulkan
Skeletal animation
Post-processing
Advanced animation timelines and clip sequencing
Multiplayer systems
Editor tooling

🚧 Over Core #1

These items are explicitly outside the Core #1 scope and must not be pulled into Core #1 API, renderer, or test commitments:

PBR
Shadows
Active lights in shaders
Object animation
External model loading
Advanced picking

Core #1 Lighting Decision

Core #1 keeps lighting as contracts only. LightData exists so scene, light, and future renderer modules can agree on shape, direction, color, and intensity metadata, but Core #1 does not transport lights through the render frame and does not evaluate real lighting in shaders.

The active Core #1 renderer supports flat-color materials: the material color is passed directly to the shader without directional, ambient, point, or physically based light contribution.

🧠 Core Philosophy

Spatial follows a strict design philosophy:

Declarative

Scenes describe state.

Reactive

State changes update rendering automatically.

Compose-first

Inspired by Compose mental models and APIs.

Cinematic

Motion quality matters more than feature quantity.

Opinionated

Good defaults and minimal boilerplate.

🧩 Core #1 public API

Core #1 exposes its stable public Compose API from the root com.elitec.spatial_compose package. Implementation packages remain split internally, but application code should prefer these root imports.

Public imports

import com.elitec.spatial_compose.CameraState
import com.elitec.spatial_compose.Element
import com.elitec.spatial_compose.GestureSensitivity
import com.elitec.spatial_compose.Gestures
import com.elitec.spatial_compose.Modifier3D
import com.elitec.spatial_compose.MotionSpec
import com.elitec.spatial_compose.Scene
import com.elitec.spatial_compose.SceneGestures
import com.elitec.spatial_compose.rememberCameraState

A real Android render host is supplied by the runtime adapter:

import com.elitec.spatial_compose_runtime_adapter.DefaultSceneRenderHostFactory

Compilable Compose example

import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.runtime.Composable
import androidx.compose.ui.Modifier
import com.elitec.spatial_compose.Element
import com.elitec.spatial_compose.Gestures
import com.elitec.spatial_compose.Modifier3D
import com.elitec.spatial_compose.Scene
import com.elitec.spatial_compose_runtime_adapter.DefaultSceneRenderHostFactory
import com.elitec.spatial_units.deg
import com.elitec.spatial_compose.rememberCameraState
import com.elitec.spatial_units.meters

@Composable
fun CoreOneScene() {
    val cameraState = rememberCameraState(
        yaw = 20f.deg,
        pitch = (-12f).deg,
        zoom = 1.25f,
    )
    Scene(
        modifier = Modifier.fillMaxSize(),
        renderHostFactory = DefaultSceneRenderHostFactory,
        cameraState = cameraState,
        gestures = Gestures.orbitAndZoom(),
    ) {
        Element.Cube(
            modifier = Modifier3D.Default
                .size(2f.meters)
                .position(0f.meters, 0f.meters, (-5f).meters),
        )

        Element.Sphere(
            modifier = Modifier3D.Default
                .size(1f.meters)
                .position(3f.meters, 0f.meters, (-8f).meters),
        )
    }
}

🏗️ Architecture

Spatial uses a hybrid architecture:

Clean Architecture

Feature First

Rendering-Oriented Pragmatism

The architecture prioritizes:

Ownership boundaries
Module independence
Rendering performance
Scalability
Low coupling
Maintainability

Spatial avoids unnecessary enterprise abstractions such as:

Excessive repositories
DTO overengineering
Artificial use cases
Massive inheritance hierarchies

🧭 Scene3D Split

The old monolithic Scene3D responsibility is now documented as a thin public facade plus internal feature slices:

components/Scene.kt owns the Compose Scene composable, Android view hosting, render-host lifecycle, gesture modifier wiring, scene graph collection, and frame submission.
scene/* owns scene graph construction and conversion: SceneBuilder, SceneContentScope, SceneNode, gesture configuration, render host contracts, graph remembering, and renderable-node adapters.
modifier/* owns Modifier3D, gesture input modifiers, and conversion from declarative transforms to model matrices.
state/* owns CameraState and rememberCameraState.
core/Element.kt owns the primitive element facade (Element.Cube, Element.Sphere, and Element.Plane).
Scene3D.kt remains the root-package public API facade that re-exports the stable Core #1 symbols from com.elitec.spatial_compose.

📦 Workspace Structure

spatial/
│
├── app/
│
├── spatial-renderer/
├── spatial-scene/
├── spatial-camera/
├── spatial-motion/
├── spatial-gesture/
├── spatial-material/
├── spatial-geometry/
├── spatial-light/
├── spatial-math/
├── spatial-units/
├── spatial-compose/
└── spatial-core/

🧱 Module Responsibilities

app/

Type

Android Application

Purpose

Playground and showcase application.

Used for:

Rendering validation
Gesture testing
Motion tuning
FPS monitoring
Demo scenes
Visual experimentation

spatial-renderer/

Type

Android Library

Purpose

Shared Core #1 motion primitives for basic camera and transform animation.

Responsibilities

Basic camera/transform interpolation
Shared easing curves
Shared camera animation duration planning
Runtime/Compose motion parity helpers

Out of scope for Core #1

Skeletal animation
Advanced keyframe timelines
Clip blending and sequencer-style orchestration

Internal Features

renderer/
 ├── shader/
 ├── pipeline/
 ├── buffer/
 ├── texture/
 ├── framebuffer/
 ├── renderloop/
 └── context/

spatial-scene/

Type

Kotlin Library

Purpose

Scene graph and hierarchical structure.

Responsibilities

Node hierarchy
Transform propagation
Traversal
Visibility management
Dirty flags
Parent-child relationships

spatial-camera/

Type

Kotlin Library

Purpose

Camera behavior and cinematic motion.

Responsibilities

Orbit camera
Pan
Zoom
Damping
Inertia
Smooth transitions
Projection systems

Internal Features

camera/
 ├── orbit/
 ├── zoom/
 ├── inertia/
 ├── interpolation/
 └── projection/

spatial-motion/

Type

Kotlin Library

Purpose

Animation and motion engine.

Responsibilities

Animation timelines
Interpolation
Spring systems
Easing
Transitions
Motion orchestration

spatial-gesture/

Type

Android Library

Purpose

Touch and gesture input system.

Responsibilities

Multi-touch
Pinch zoom
Orbit gestures
Velocity tracking
Gesture smoothing
MotionEvent handling

spatial-material/

Type

Kotlin Library

Purpose

Material abstraction layer.

Responsibilities

Flat-color materials for Core #1
Texture materials (future)
Shader metadata (future)
Material bindings
Lighting properties as metadata only; active light evaluation is outside Core #1

spatial-geometry/

Type

Kotlin Library

Purpose

Mesh and primitive generation.

Responsibilities

Cube generation
Sphere generation
Cylinder generation
Plane generation
Mesh data
Normals
UV coordinates

spatial-light/

Type

Kotlin Library

Purpose

Lighting models.

Responsibilities

Light contracts and helper factories
Directional light metadata
Light intensity metadata
Light direction metadata

Out of scope for Core #1

Active lighting in shaders
Shaded material evaluation
Shadows

spatial-math/

Type

Kotlin Library

Purpose

Pure mathematical foundation.

Responsibilities

Vec2
Vec3
Vec4
Quaternion
Matrix4
Projection math

Important

This module must remain:

Lightweight
Pure Kotlin
Allocation-friendly
Dependency-free

spatial-units/

Type

Kotlin Library

Purpose

Consistent spatial units system.

Responsibilities

Meters
Centimeters
Degrees
Unit conversions
Spatial consistency

Example

1.meters
45.deg
50.cm

spatial-compose/

Type

Android Library

Purpose

Declarative Compose integration layer.

Responsibilities

Scene composables
Element composables
Modifier3D
remember states
Compose adapters

Important

This module does NOT render directly.

It orchestrates:

state
composition
declarative APIs

spatial-core/

Type

Kotlin Library

Purpose

Core orchestration and public contracts.

Responsibilities

Public APIs
Module orchestration
Shared contracts
Engine coordination

🔄 Dependency Direction

Compose
   ↓
Core
   ↓
Scene
   ↓
Renderer

Rules:

High-level modules never depend on UI.
Renderer never knows Compose.
Scene never knows Android.
Math remains framework-independent.

🧪 Development Workflow

Spatial is developed using a parallel playground application.

Recommended workflow

Modify renderer
      ↓
Run playground
      ↓
Validate motion
      ↓
Tune gestures
      ↓
Refactor APIs
      ↓
Repeat

🎮 Playground Purpose

The playground app acts as:

Rendering sandbox
Motion laboratory
Camera tuning environment
FPS validator
Material previewer
Demo showcase

🧰 Technology Stack

Core Technologies

Kotlin
OpenGL ES 3.0+
Jetpack Compose
Coroutines
Gradle Kotlin DSL

Dependency Injection

Recommended:

Koin (limited usage)

Use DI ONLY for:

Renderer services
Shader registries
Texture caches
Motion orchestrators

Avoid DI for:

Vec3
Matrix4
Geometry
Units
Transforms

📐 Units System

Spatial avoids arbitrary floats whenever possible.

Example:

Modifier3D
    .size(2.meters)
    .rotateY(45.deg)

This improves:

readability
spatial consistency
API ergonomics

🎥 Motion System

Motion quality is one of Spatial's highest priorities.

Core #1 focuses heavily on:

smooth orbit camera
cinematic transitions
natural zoom
inertia
damping
interpolation

The renderer should feel premium even with simple cubes.

🚀 Development Phases

Phase 1

Rendering foundations:

EGL
OpenGL setup
Triangle rendering
Render loop

Phase 2

Math engine:

Vec3
Matrix4
Quaternion

Phase 3

Camera system:

Orbit
Zoom
Inertia
Gestures

Phase 4

Scene graph:

Nodes
Hierarchy
Traversal

Phase 5

Geometry:

Cube
Sphere
Plane
Cylinder

Phase 6

Materials:

Solid materials
Texture materials
Basic lighting

Phase 7

Compose DSL:

Scene
Element
Modifier3D

Phase 8

Basic motion system:

animateTo for camera/transform changes
interpolation
- shared easing/duration planning

Advanced timelines, skeletal animation, and clip sequencing are intentionally outside Core #1.

Phase 9

Polish:

smooth gestures
frame pacing
shader caching
lifecycle cleanup

Phase 10

Showcase playground.

✅ Core #1 Success Criteria

Core #1 is complete when:

Primitives render correctly
Camera feels cinematic
Zoom feels smooth
Gestures feel natural
Motion transitions work
Compose integration works
API feels elegant
60 FPS remain stable
OpenGL complexity stays hidden

🔮 Long-Term Vision

Potential future expansions:

glTF loading
PBR
Real lighting and shaded light evaluation
Shadows
Vulkan backend
Compose Multiplatform
Spatial UI
Physics integration
WebGPU backend

💡 Guiding Principle

Less GPU complexity. More declarative intent.

Spatial — Declarative 3D Rendering for Android

Built for modern Android graphics experimentation.

Name		Name	Last commit message	Last commit date
.ai		.ai
.github/workflows		.github/workflows
.idea		.idea
.kotlin/errors		.kotlin/errors
app		app
build-logic		build-logic
gradle		gradle
roadmap		roadmap
scripts		scripts
spatial-camera		spatial-camera
spatial-compose-runtime-adapter		spatial-compose-runtime-adapter
spatial-compose		spatial-compose
spatial-core		spatial-core
spatial-geometry		spatial-geometry
spatial-gesture		spatial-gesture
spatial-light		spatial-light
spatial-material		spatial-material
spatial-math		spatial-math
spatial-motion		spatial-motion
spatial-renderer		spatial-renderer
spatial-runtime		spatial-runtime
spatial-scene		spatial-scene
spatial-units		spatial-units
spatial		spatial
website		website
.gitignore		.gitignore
LICENSE		LICENSE
NOTICE		NOTICE
PLAN_PREDEFINED_3D_MODELS.md		PLAN_PREDEFINED_3D_MODELS.md
PUBLISHING.md		PUBLISHING.md
banner.png		banner.png
build.gradle.kts		build.gradle.kts
design.md		design.md
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
icon.png		icon.png
logo.png		logo.png
readme.md		readme.md
settings.gradle.kts		settings.gradle.kts

Latest commit

History

Folders and files

Repository files navigation

🌌 Spatial

Declarative 3D Rendering for Android inspired by Jetpack Compose

📜 License

✨ Vision

🎯 Core #1 Goals

Public consumer entry points

Current status

Included

Intentionally Excluded

🚧 Over Core #1

Core #1 Lighting Decision

🧠 Core Philosophy

Declarative

Reactive

Compose-first

Cinematic

Opinionated

🧩 Core #1 public API

Public imports

Compilable Compose example

🏗️ Architecture

Clean Architecture

Feature First

Rendering-Oriented Pragmatism

🧭 Scene3D Split

📦 Workspace Structure

🧱 Module Responsibilities

app/

Type

Purpose

spatial-renderer/

Type

Purpose

Responsibilities

Out of scope for Core #1

Internal Features

spatial-scene/

Type

Purpose

Responsibilities

spatial-camera/

Type

Purpose

Responsibilities

Internal Features

spatial-motion/

Type

Purpose

Responsibilities

spatial-gesture/

Type

Purpose

Responsibilities

spatial-material/

Type

Purpose

Responsibilities

spatial-geometry/

Type

Purpose

Responsibilities

spatial-light/

Type

Purpose

Responsibilities

Out of scope for Core #1

spatial-math/

Type

Purpose

Responsibilities

Important

spatial-units/

Type

Purpose

Responsibilities

Example