ALICE-SDF

English | 日本語

A.L.I.C.E. - Adaptive Lightweight Implicit Compression Engine

"Don't send polygons. Send the law of shapes."

Overview

ALICE-SDF is a 3D/spatial data specialist that transmits mathematical descriptions of shapes (Signed Distance Functions) instead of polygon meshes. This enables:

• 10-1000x compression compared to traditional mesh formats
• Infinite resolution - shapes are mathematically perfect at any scale
• CSG operations - boolean operations on shapes without mesh overhead
• Real-time raymarching - GPU-accelerated rendering
• PBR materials - metallic-roughness workflow compatible with UE5/UE6/Unity/Godot
• Keyframe animation - parametric deformation with timeline tracks
• Asset pipeline - OBJ import/export, glTF 2.0 (.glb) export, FBX, USD, Alembic, Nanite, STL, PLY, 3MF, ABM export
• 5-layer mesh persistence - ABM binary format, LOD chain persistence, chunked mesh cache with FIFO eviction, Unity/UE5/UE6 native export
• Manifold mesh guarantee - validation, repair, and quality metrics
• Adaptive Marching Cubes - octree-based mesh generation, detail where it matters
• Dual Contouring - QEF-based mesh generation that preserves sharp edges and corners
• V-HACD convex decomposition - automatic convex hull decomposition for physics
• Attribute-preserving decimation - QEM with UV/tangent/material boundary protection
• Advanced simplifier options - per-vertex lock mask (lock_vertices) for LOD seam preservation, absolute/relative error thresholds (error_absolute)
• Decimation-based LOD - progressive LOD chain from high-res base mesh
• meshopt-compatible codec - binary-compatible index / vertex buffer compression (indexcodec v1 + vertexcodec v0/v1), verified against reference vectors produced by the zeux/meshoptimizer C++ library
• glTF EXT_meshopt_compression - io::meshopt_gltf module + GltfConfig::meshopt_compress option; POSITION / NORMAL / TEXCOORD_0 / JOINTS_0 / WEIGHTS_0 / indices all compressible with per-attribute channel estimation (u8 / u16 / u32 XOR + 8-rotation heuristic)
• Vertex filters - Octahedral (normal / tangent, 50-75% smaller with <1% angular error), Quaternion (rotation, largest-component + cyclic swizzle), Exponential (float mantissa + shared exponent)
• Triangle stripifier - Evans-Skiena-Varshney greedy strip algorithm with 8-triangle lookahead (~48% index reduction on closed meshes), supports primitive-restart or degenerate-triangle joining
• Nanite-style meshlet clusters - V2 adjacency + cone_weight grow with NormalCone (basic + cone_apex) for Vulkan VK_EXT_mesh_shader / DirectX 12 mesh shader culling
• 73 primitives, 24 operations, 7 transforms, 24 modifiers (128 total) - industry-leading shape vocabulary
• Chamfer & Stairs blends - hard-edge bevels and stepped/terraced CSG transitions
• Interval Arithmetic - conservative AABB evaluation for spatial pruning and Lipschitz bound tracking
• Relaxed Sphere Tracing - over-relaxation with Lipschitz-adaptive step sizing
• Neural SDF - pure-Rust MLP that approximates an SDF tree ~10-100x faster for complex scenes
• SDF-to-SDF Collision - grid-based contact detection with interval arithmetic AABB pruning
• CSG Tree Optimization - identity transform/modifier removal, nested transform merging, smooth→standard demotion
• Analytic Gradient - single-pass gradient via chain rules and Jacobian propagation (9 analytic + 44 numerical-fallback primitives)
• Automatic Differentiation - Dual Number forward-mode AD, Hessian estimation, mean curvature computation
• 2D SDF module - pure 2D SDF primitives (circle, rect, bezier, font glyph) with bilinear sampling
• CSG Tree Diff/Patch - structural diff between SDF trees for undo/redo and network sync
• Parametric Constraint Solver - Gauss-Newton optimization for geometric constraints (fixed, distance, sum, ratio)
• Distance Field Heatmap - cross-section slicing with 4 color maps (coolwarm, binary, viridis, magma)
• Shell / Offset Surface - variable-thickness shell modifier with inner/outer offset control
• Volume & Surface Area - Monte Carlo estimation with deterministic PRNG and standard error
• ALICE-Font Bridge - font glyph → 2D/3D SDF conversion, text layout, 3D extrusion (--features font, not available on the crates.io v1.7.7 release — see Installation note, restoration planned for v1.8.0)
• Auto Tight AABB - interval arithmetic + binary search to find minimal bounding box containing the SDF surface
• 7 evaluation modes - interpreted, compiled VM, SIMD 8-wide, BVH, SoA batch, JIT, GPU
• 3 shader targets - GLSL, WGSL, HLSL transpilation
• Engine integrations - Unity, Unreal Engine 5 / 6, VRChat, Godot, WebAssembly

Text-to-3D Pipeline (Server)

ALICE-SDF includes a FastAPI server that converts natural language text into real 3D geometry via LLM-generated SDF trees.

User: "A medieval castle"  →  LLM (Claude/Gemini)  →  SDF JSON  →  ALICE-SDF  →  GLB/OBJ
         text                   ~5-50s                  20 nodes      <55ms        mesh

Architecture

┌─────────────┐     ┌──────────────┐     ┌───────────────┐     ┌──────────┐
│  FastAPI     │     │  LLM Service │     │  SDF Service  │     │  Output  │
│  Server      │────▶│  Claude API  │────▶│  from_json()  │────▶│  GLB     │
│              │     │  Gemini API  │     │  compile()    │     │  OBJ     │
│  POST /gen   │     │  System      │     │  to_mesh()    │     │  JSON    │
│  WS /ws/gen  │     │  Prompt      │     │  export_glb() │     │  Viewer  │
│  GET /viewer │     └──────────────┘     └───────────────┘     └──────────┘
└─────────────┘

API Endpoints

Generated Scene Gallery

Scenes generated by Gemini 2.5 Flash from natural language prompts:

Hand-crafted few-shot examples (used in LLM system prompt):

Scene JSON files are stored in server/examples/scenes/.

Quick Start (Server)

# 1. Build Python bindings
cd /path/to/ALICE-SDF
python -m venv .venv && source .venv/bin/activate
maturin develop --features python

# 2. Install server dependencies
pip install -r server/requirements.txt

# 3. Set API keys
export ANTHROPIC_API_KEY="sk-..."   # for Claude
export GOOGLE_API_KEY="AI..."       # for Gemini

# 4. Start server
uvicorn server.main:app --reload

# 5. Generate 3D from text
curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A snowman", "provider": "gemini", "resolution": 64}' \
  -o snowman.glb

# 6. Open browser viewer
open http://localhost:8000/api/viewer

LLM Providers

Performance Budget

Robustness Features

• JSON repair: Automatic brace/bracket completion for truncated LLM output
• Structure validation: Pre-validates Boolean ops (a/b) and transforms (child) before Rust serde
• Retry with feedback: Up to 2 retries with error message fed back to LLM
• Rate limit handling: Automatic wait-and-retry on 429 errors
• Complexity constraints: System prompt limits scenes to 15-20 nodes, nesting depth ≤6

Server Directory Structure

server/
├── main.py                  # FastAPI app, REST + WebSocket endpoints
├── config.py                # API keys, model config (env vars)
├── models.py                # Pydantic request/response models
├── services/
│   ├── llm_service.py       # Claude/Gemini API with retry logic
│   └── sdf_service.py       # alice_sdf wrapper (parse, mesh, export)
├── prompts/
│   ├── system_prompt.py     # 36-node-type SDF grammar for LLM
│   └── examples.py          # 6 few-shot examples
├── examples/
│   └── scenes/              # Pre-built scene JSON files
│       ├── sphere_on_ground.json
│       ├── snowman.json
│       ├── castle_tower.json
│       ├── alien_mushroom_forest.json
│       ├── twisted_pillar.json
│       └── mechanical_gear.json
├── static/
│   └── viewer.html          # Three.js GLB viewer
├── tests/
│   ├── test_api.py          # 7 API endpoint tests
│   ├── test_llm_service.py  # 17 JSON extraction/validation tests
│   └── test_sdf_service.py  # 13 SDF pipeline tests
└── requirements.txt

Running Tests

source .venv/bin/activate
python -m pytest server/tests/ -v   # 37 tests, all passing

ALICE-View (Real-time 3D Viewer)

ALICE-View is a native GPU raymarching viewer built with wgpu. It renders SDF trees directly on the GPU via WGSL transpilation — no mesh conversion needed.

SDF JSON → ALICE-SDF (WGSL transpile) → wgpu GPU Raymarching → Real-time 3D
              ~1ms                            60 FPS

Features

• GPU Raymarching — SdfNode tree transpiled to WGSL shader, evaluated per-pixel on GPU
• Drag & Drop — Drop .json / .asdf / .asdf.json files onto the window
• File Dialog — File > Open (Ctrl+O) with format filters
• Camera Controls — Mouse orbit, scroll zoom, WASD movement
• Live SDF Panel — Node count, raymarching parameters (max steps, epsilon, AO)

Supported Formats

Quick Start

cd /path/to/ALICE-View

# Open a specific file
cargo run --bin alice-view -- path/to/scene.json

# Or launch empty and drag & drop files onto the window
cargo run --bin alice-view

Keyboard Shortcuts

Viewing Text-to-3D Results

Generated scene JSON files from the Text-to-3D pipeline can be viewed directly:

# View a generated scene
cargo run --bin alice-view -- /path/to/ALICE-SDF/server/examples/scenes/snowman.json

# Or drag any of these onto the window:
#   server/examples/scenes/castle_tower.json
#   server/examples/scenes/mechanical_gear.json
#   server/examples/scenes/alien_mushroom_forest.json

Core Concepts

SDF (Signed Distance Function)

An SDF returns the shortest distance from any point to the surface:

• Negative = inside the shape
• Zero = on the surface
• Positive = outside the shape

SdfNode Tree Structure

SdfNode
  |-- Primitive (73): Sphere, Box3D, Cylinder, Torus, Plane, Capsule, Cone, Ellipsoid,
  |                    RoundedCone, Pyramid, Octahedron, HexPrism, Link, Triangle, Bezier,
  |                    RoundedBox, CappedCone, CappedTorus, InfiniteCylinder, RoundedCylinder,
  |                    TriangularPrism, CutSphere, CutHollowSphere, DeathStar, SolidAngle,
  |                    Rhombus, Horseshoe, Vesica, InfiniteCone, Heart, Gyroid,
  |                    Tube, Barrel, Diamond, ChamferedCube, SchwarzP, Superellipsoid, RoundedX,
  |                    Pie, Trapezoid, Parallelogram, Tunnel, UnevenCapsule, Egg,
  |                    ArcShape, Moon, CrossShape, BlobbyCross, ParabolaSegment,
  |                    RegularPolygon, StarPolygon, Stairs, Helix,
  |                    Tetrahedron, Dodecahedron, Icosahedron,                    ← Platonic solids (GDF)
  |                    TruncatedOctahedron, TruncatedIcosahedron,                 ← Archimedean solids
  |                    BoxFrame,                                                   ← IQ wireframe box
  |                    DiamondSurface, Neovius, Lidinoid, IWP, FRD,              ← TPMS surfaces
  |                    FischerKochS, PMY,                                          ← TPMS surfaces
  |                    Circle2D, Rect2D, Segment2D, Polygon2D,                   ← 2D primitives (extruded)
  |                    RoundedRect2D, Annular2D,                                   ← 2D primitives (extruded)
  |                    Terrain                                                     ← procedural biome terrain (FBM + Voronoi erosion)
  |-- Operation (24): Union, Intersection, Subtraction,
  |                    SmoothUnion, SmoothIntersection, SmoothSubtraction,
  |                    ChamferUnion, ChamferIntersection, ChamferSubtraction,
  |                    StairsUnion, StairsIntersection, StairsSubtraction,
  |                    ExpSmoothUnion, ExpSmoothIntersection, ExpSmoothSubtraction, ← IQ exponential smooth
  |                    XOR, Morph,                                                 ← Boolean / Interpolation
  |                    ColumnsUnion, ColumnsIntersection, ColumnsSubtraction,      ← hg_sdf columns
  |                    Pipe, Engrave, Groove, Tongue                               ← hg_sdf advanced
  |-- Transform (7): Translate, Rotate, Scale, ScaleNonUniform,
  |                   ProjectiveTransform,                                         ← perspective projection with inv_matrix
  |                   LatticeDeform,                                               ← Free-Form Deformation (FFD) grid
  |                   SdfSkinning                                                  ← bone-weight skeletal deformation
  |-- Modifier (24): Twist, Bend, RepeatInfinite, RepeatFinite, Noise, Round, Onion, Elongate,
  |                   Mirror, Revolution, Extrude, Taper, Displacement, SineDisplacement, PolarRepeat, SweepBezier,
  |                   Shear,                                                       ← 3-axis shear deformation
  |                   OctantMirror,                                                ← 48-fold symmetry
  |                   IcosahedralSymmetry,                                         ← 120-fold icosahedral symmetry
  |                   IFS,                                                         ← Iterated Function System fractals
  |                   HeightmapDisplacement,                                       ← heightmap-driven surface displacement
  |                   SurfaceRoughness,                                            ← FBM noise roughness
  |                   Animated,                                                    ← timeline-driven parameter animation
  |                   WithMaterial                                                 ← PBR material assignment

Installation

Note (v1.7.7, crates.io landing 2026-09-12) — 5 bridge features are currently removed from [features]: codec / physics / asp / sdf-cache / font. Their src/*_bridge.rs modules remain #[cfg(feature = "...")]-gated so they simply do not compile on crates.io 1.7.7. Users who need the bridges keep using path/git deps against the sibling repos (ALICE-Codec / ALICE-Physics / libasp / alice-cache / alice-font). Scheduled restoration in v1.8.0 once the transitive dep chain publishes to crates.io. See CHANGELOG.md [v1.7.7] - 2026-09-12 entry for details, including the RUSTSEC-2025-0020 (pyo3) and RUSTSEC-2025-0141 (bincode) security fixes and the pyo3 0.23 → 0.29 / bincode 1.3 → 2.0 bumps.

Rust

cargo add alice-sdf

Python

pip install alice-sdf

Claude Code / Codex Skill

The skills/implicit-cad/ directory bundles ALICE-SDF as an installable agent skill for Claude Code / Codex. It exposes SDF authoring, GLSL/WGSL/HLSL transpile, and mesh export (GLB/OBJ/STL/PLY/3MF) as thin CLI wrappers around this crate. See skills/implicit-cad/SKILL.md. Companion alice-lol-sdf skill (in the ALICE-LOL repo) provides the DSL front-end with LLM constrained-decoding support.

Usage

Choose Your Path

Pick the path that matches your role. All paths share the same SdfNode intermediate representation, so you can mix them (e.g. build in LOL, transpile to GLSL, evaluate in Python).

Hello, First SDF (30 seconds)

The smallest useful sample — construct, evaluate, mesh, done:

use alice_sdf::prelude::*;

let sphere = SdfNode::sphere(1.0);
let d = eval(&sphere, glam::Vec3::new(0.5, 0.0, 0.0));
assert!((d + 0.5).abs() < 1e-6);           // point 0.5 away from center → distance -0.5 (inside)

let mesh = sdf_to_mesh(
    &sphere,
    glam::Vec3::splat(-1.5),
    glam::Vec3::splat(1.5),
    &MarchingCubesConfig::default(),
);
println!("{} vertices, {} triangles", mesh.vertices.len(), mesh.indices.len() / 3);

Once this runs, jump to the path that matches your role above.

With ALICE-LOL DSL (Recommended)

The easiest way to create SDF scenes is ALICE-LOL — a lol! proc_macro that lets you write SDF trees declaratively instead of constructing them by hand.

# Cargo.toml
[dependencies]
alice-sdf = { path = "../ALICE-SDF" }
alice-lol = { path = "../ALICE-LOL/alice-lol" }

Before (manual SdfNode construction):

use alice_sdf::prelude::*;

let scene = SdfNode::SmoothUnion {
    k: 0.3,
    children: vec![
        SdfNode::sphere(1.0),
        SdfNode::Translate {
            offset: glam::Vec3::new(2.0, 0.0, 0.0),
            child: Box::new(SdfNode::Round {
                radius: 0.05,
                child: Box::new(SdfNode::box3d(0.8, 0.8, 0.8)),
            }),
        },
    ],
};

After (LOL DSL):

use alice_lol::{lol, to_glsl, eval};

let scene = lol! {
    smooth_union(0.3,
        sphere(1.0),
        translate(2.0, 0.0, 0.0, round(0.05, box3d(0.8, 0.8, 0.8)))
    )
};

Same SdfNode tree, fraction of the code. All 76 constructs (27 primitives, 23 CSG ops, 4 transforms, 19 modifiers, 2 time controls, 3 law constraints) work as function calls.

Transpile to GPU shaders:

let glsl = to_glsl(&scene);                      // GLSL
let wgsl = alice_lol::to_wgsl(&scene);            // WGSL (WebGPU)
let hlsl = alice_lol::to_hlsl(&scene);            // HLSL (DirectX)

CPU evaluation:

let dist = eval(&scene, glam::Vec3::new(0.0, 1.0, 0.0));

Mesh export from a LOL scene:

use alice_lol::lol;
use alice_sdf::prelude::*;

let scene = lol! {
    smooth_union(0.3,
        sphere(1.0),
        translate(2.0, 0.0, 0.0, box3d(0.8, 0.8, 0.8))
    )
};

let mesh = sdf_to_mesh(
    &scene,
    glam::Vec3::splat(-3.0),
    glam::Vec3::splat(3.0),
    &MarchingCubesConfig { resolution: 128, ..Default::default() },
);

alice_sdf::export::obj::write_obj("out.obj", &mesh)?;
alice_sdf::export::glb::write_glb("out.glb", &mesh)?;

Inject Rust variables at runtime:

let radius = 1.5_f32;
let height = compute_height();
let scene = lol! {
    smooth_union(0.2,
        sphere({radius}),
        translate(0.0, {height}, 0.0, cylinder(2.0, 0.5))
    )
};

Validate shape constraints at compile time:

use alice_lol::law::{LawSet, Law, Priority};

let laws = LawSet::new()
    .add(Law::non_overlap(&a, &b), Priority::Hard)        // shapes must not intersect
    .add(Law::min_thickness(&scene, 0.1), Priority::Soft(0.5));  // wall thickness >= 0.1
let report = laws.check();

For full LOL documentation, see ALICE-LOL README.

Rust (Direct SdfNode Construction)

For fine-grained control or when you need access to advanced node types not yet covered by the LOL DSL, you can construct SdfNode trees directly:

use alice_sdf::prelude::*;

// Create a sphere with radius 1
let sphere = SdfNode::sphere(1.0);

// Subtract a box from it
let result = sphere.subtract(SdfNode::box3d(1.5, 1.5, 1.5));

// Evaluate distance at a point
let distance = eval(&result, glam::Vec3::ZERO);

// Convert to mesh
let mesh = sdf_to_mesh(
    &result,
    glam::Vec3::splat(-2.0),
    glam::Vec3::splat(2.0),
    &MarchingCubesConfig::default()
);

Python

import alice_sdf as sdf

# Create primitives
sphere = sdf.SdfNode.sphere(1.0)
box3d = sdf.SdfNode.box3d(2.0, 1.0, 1.0)

# CSG operations (method syntax)
result = sphere.subtract(box3d)

# Operator overloads (Pythonic syntax)
a = sdf.SdfNode.sphere(1.0)
b = sdf.SdfNode.box3d(0.5, 0.5, 0.5)
union     = a | b    # a.union(b)
intersect = a & b    # a.intersection(b)
subtract  = a - b    # a.subtract(b)

# Transform
translated = result.translate(1.0, 0.0, 0.0)

# Evaluate at points (NumPy array)
import numpy as np
points = np.array([[0.5, 0.0, 0.0], [1.0, 1.0, 1.0]], dtype=np.float32)
distances = sdf.eval_batch(translated, points)

# Compiled evaluation (2-5x faster for repeated use)
compiled = sdf.compile_sdf(sphere)
distances = compiled.eval_batch(points)               # compiled batch
vertices, indices = compiled.to_mesh((-2,-2,-2), (2,2,2), resolution=64)  # compiled mesh

# Convert to mesh
vertices, indices = sdf.to_mesh(translated, (-2.0, -2.0, -2.0), (2.0, 2.0, 2.0))

# Export to multiple formats
sdf.export_obj(vertices, indices, "model.obj")
sdf.export_glb(vertices, indices, "model.glb")
sdf.export_fbx(vertices, indices, "model.fbx")
sdf.export_usda(vertices, indices, "model.usda")
sdf.export_alembic(vertices, indices, "model.abc")

# UV unwrap → (positions[N,3], uvs[N,2], indices[M])
positions, uvs, indices = sdf.uv_unwrap(vertices, indices)

Sine Displacement (v1.7.3, isotropic + anisotropic)

SineDisplacement adds a sin-wave perturbation to any child SDF. As of v1.7.3 it accepts a per-axis Vec3 frequency, so you can drive fine XYZ-independent patterns (scales, wood grain, cloth drape) from a single node.

Two ergonomic constructors:

use alice_sdf::prelude::*;
use glam::Vec3;

// Isotropic: sphere with fine cellular perturbation.
let scales = SdfNode::sphere(1.0).sine_displacement(0.03, 25.0);

// Anisotropic: long thin scales (high freq on X, low on Y and Z).
let fish_scales = SdfNode::sphere(1.0).sine_displacement_aniso(0.03, Vec3::new(40.0, 10.0, 10.0));

// Anisotropic: wood grain (rings dense along Y, sparse elsewhere).
let wood = SdfNode::box3d(1.0, 3.0, 1.0)
    .sine_displacement_aniso(0.01, Vec3::new(4.0, 30.0, 4.0));

Both variants transpile to GLSL / WGSL / HLSL through the standard pipeline (to_glsl / to_wgsl / to_hlsl). The transpiler emits per-axis sin(freq.x * p.x) * sin(freq.y * p.y) * sin(freq.z * p.z), matching the CPU modifier_sine_displacement reference. Interval-arithmetic bounds and diff (derivative) support are already wired, so displaced SDFs remain safe for raymarching and gradient-based sampling.

Common Recipes

Copy-paste patterns that come up over and over. All examples assume use alice_sdf::prelude::*;.

1. Rounded box (chamfer)

let rounded = SdfNode::box3d(1.0, 1.0, 1.0).round(0.15);

2. Smooth blob (union with soft blend)

let blob = SdfNode::sphere(1.0)
    .smooth_union(SdfNode::sphere(0.7).translate(1.2, 0.0, 0.0), 0.4);
// signature: smooth_union(self, other: Self, k: f32) — k is the blend radius

3. Hollow shell (onion)

let shell = SdfNode::sphere(1.0).onion(0.05);   // 5cm thick wall

4. Infinite tiling (repeat_infinite)

let tiles = SdfNode::box3d(0.4, 0.4, 0.4).repeat_infinite(1.0, 1.0, 1.0);
// finite variant: .repeat_finite([count_x, count_y, count_z], spacing)

5. Twist along Y

let twisted = SdfNode::box3d(0.4, 2.0, 0.4).twist(1.5);   // 1.5 rad/unit around Y

6. Displacement (sine + noise)

let rough = SdfNode::sphere(1.0).sine_displacement(0.03, 20.0);

7. CSG chain (subtract holes from a plate)

let plate = SdfNode::box3d(2.0, 0.1, 2.0);
let hole  = SdfNode::cylinder(2.0, 0.15);
let drilled = plate
    .subtract(hole.translate(-0.8, 0.0,  0.0))
    .subtract(hole.translate( 0.8, 0.0,  0.0))
    .subtract(hole.translate( 0.0, 0.0, -0.8));

8. GPU transpile (WebGPU / Metal / DX12)

use alice_lol::{lol, to_wgsl};

let scene = lol! { smooth_union(0.3, sphere(1.0), box3d(0.8, 0.8, 0.8)) };
let wgsl_source = to_wgsl(&scene);      // paste into a WGSL shader

For VFX-focused patterns (fluid simulation, mandelbulb, magic effects, ribbon FX, plasma balls, portals, force fields) see docs/VFX_COOKBOOK.md.

For general recipe collection (procedural terrain, camera-relative modifiers, bounding-volume tricks, LOD strategy) see docs/COOKBOOK.md.

Where to go next

For deep technical sections (Material / Animation / Architecture / Mesh / Platonic Solids / Interval Arithmetic / Neural SDF / Collision / Analytic Gradient / Dual Contouring / CSG Tree Optimization / Auto Tight AABB / Texture Fitting / Raymarching / FFI bindings / Feature Flags / Physics Bridge / 3D Print Pipeline / Performance / Benchmarking / Unity / VRChat / Unreal / Godot / Cross-Crate Bridges / Asset Delivery Network / Nanite hybrid pipeline) see docs/USAGE.md.

License

Open Core Model - Free for creators, licensed for infrastructure.

Free Use (No License Required)

• Personal projects
• Indie game development (any revenue)
• AAA game studios (shipped games)
• Educational & research
• Open source projects

Commercial License Required

• Metaverse platforms (10,000+ MAU)
• Cloud streaming services (SaaS/PaaS)
• Infrastructure providers
• Competing products

See LICENSE (MIT) and LICENSE-COMMUNITY for details.

Content you create (.asdf files, worlds, games) is 100% yours. No royalties.

LLM × 3D Creation Pipeline (SDF + LOL + View + Physics)

Four ALICE projects combine to form an end-to-end text-to-3D workflow — from natural language to physically simulated 3D scenes:

User: "A snowman with a top hat"
         │
         ▼
┌──────────────────┐  LOL DSL or JSON  ┌───────────────────┐  WGSL / GLB   ┌──────────────┐
│  LLM             │ ────────────────▶ │  ALICE-SDF        │ ────────────▶ │  ALICE-View  │
│  (Claude/Gemini) │                   │  parse → compile  │               │  GPU Preview │
│                  │                   │  → mesh / shader  │               │  60 FPS      │
└──────────────────┘                   └────────┬──────────┘               └──────────────┘
                                                │
                                                │ SdfField trait
                                                │ (feature = "physics")
                                                ▼
                                       ┌───────────────────┐
                                       │  ALICE-Physics     │
                                       │  Fix128 XPBD       │
                                       │  SDF CCD / Forces  │
                                       │  Destruction / Fluid│
                                       └───────────────────┘

LLM-generated shapes are not just visual — they are physics-ready. The CompiledSdfField wrapper exposes the SDF as an O(1) collision query surface, enabling rigid body, destruction, and fluid interactions without convex decomposition.

v1.7.7 note — The physics feature is not available on the crates.io 1.7.7 release. Until v1.8.0, use a path/git dep against this repo with alice-sdf = { git = "https://github.com/ext-sakamoro/ALICE-SDF", features = ["physics"] }. See Installation.

Quick Start

# 1. Start the Text-to-3D server (generates LOL/JSON via LLM)
cd ALICE-SDF/server
python main.py

# 2. POST a prompt — server returns SDF JSON
curl -X POST http://localhost:8000/api/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A snowman with a top hat", "format": "json"}'

# 3. View the result in real-time
cd ALICE-View
cargo run --bin alice-view -- ../ALICE-SDF/server/output/latest.json

Programmatic (Rust)

use alice_lol::runtime_parser::parse_lol;
use alice_sdf::prelude::*;
use alice_sdf::physics_bridge::CompiledSdfField;

// LLM output (text) → SdfNode
let lol_text = r#"smooth_union(0.3, sphere(1.0), translate(0.0, 1.5, 0.0, sphere(0.7)))"#;
let scene = parse_lol(lol_text).unwrap();

// GPU shader for rendering
let wgsl = alice_lol::to_wgsl(&scene);

// Export mesh
let mesh = alice_sdf::mesh::sdf_to_mesh(
    &scene,
    glam::Vec3::splat(-3.0),
    glam::Vec3::splat(3.0),
    &MeshConfig::default(),
);

// Physics-ready collision shape (no convex decomposition needed)
let field = CompiledSdfField::new(scene);
// field.distance(x, y, z)            → f32        (1 eval)
// field.distance_and_normal(x, y, z) → (f32, Vec3) (4 evals, tetrahedral)

Why LOL over JSON?

For complex scenes, LOL typically uses 3-4x fewer tokens, which reduces both LLM cost and hallucination.

Mobile (iOS / Android)

ALICE-SDF ships a UniFFI-based mobile SDK so the Rust core can be called directly from Swift (iOS) and Kotlin (Android).

Supported targets

Verified on real devices (2026-06-06)

Both platforms produced identical numerical output (sphere d = 0.2806, smooth_union(k=0.3) = 0.2056) — proving binary parity of the Rust core across Apple Silicon and Android ARM.

Quick start (Swift)

import AliceSDF

let d = sdfSphere(
    point:  Vec3(x: 1, y: 0, z: 0),
    center: Vec3(x: 0, y: 0, z: 0),
    radius: 1.0
)
// d ≈ 0 (point on sphere surface)

let blended = opSmoothUnion(a: 0.5, b: 0.6, k: 0.1)
// blended < 0.5 (smooth union pulls below min)

Quick start (Kotlin)

import uniffi.alice_sdf.*

val d = sdfSphere(
    point  = Vec3(1f, 0f, 0f),
    center = Vec3(0f, 0f, 0f),
    radius = 1.0f
)
// d ≈ 0

val blended = opSmoothUnion(a = 0.5f, b = 0.6f, k = 0.1f)

Build the SDK

# iOS XCFramework (device + simulator)
cd mobile/packaging/ios && ./build-xcframework.sh

# Android .so + Kotlin bindings (4 ABI)
export ANDROID_NDK_HOME=/opt/homebrew/share/android-ndk
cd mobile/packaging/android && ./build-aar.sh

Sample apps and the full integration guide live in mobile/.

Web (WebAssembly), VFX (OpenVDB), Bevy Engine

wasm feature — WebAssembly bindings

Browser-side SDF evaluation + slice rendering via wasm-bindgen.

cargo build --target wasm32-unknown-unknown --no-default-features --features wasm

JavaScript usage:

import init, { sdf_sphere, op_smooth_union, render_sphere_slice_rgba } from './alice_sdf.js';
await init();
const d = sdf_sphere(1, 0, 0, /*center*/ 0, 0, 0, /*radius*/ 1.0);  // ≈ 0
const rgba = render_sphere_slice_rgba(256, 256, 0, 0, 0, 1.0, 2.5);  // Uint8Array for canvas

openvdb feature — OpenVDB Float Grid I/O

Bake SDF trees into voxel grids for DCC tools (Houdini, Maya, Nuke, Blender).

use alice_sdf::io::vdb::{bake_to_vdb, load_dense_grid_from_vdb};
use alice_sdf::prelude::*;

let node = SdfNode::sphere(1.0);
let bytes = bake_to_vdb(&node, (-2.0, 2.0), 64).unwrap();
std::fs::write("sphere.vdb", &bytes).unwrap();

Backed by vdb-rs 0.6 (pure Rust). Currently writes a compact custom container (ALICEVDB1); full OpenVDB binary parity is planned as vdb-rs exposes its write API.

alice-sdf-bevy — Bevy 0.18 plugin

Drop-in plugin that turns SdfShape components into renderable Mesh3d assets automatically.

use bevy::prelude::*;
use alice_sdf_bevy::{AliceSdfPlugin, SdfShape};

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(AliceSdfPlugin)
        .add_systems(Startup, |mut commands: Commands| {
            commands.spawn(SdfShape::Sphere { radius: 1.0 });
        })
        .run();
}

See bindings/bevy/alice-sdf-bevy/examples/sphere_demo.rs for a full 3-shape demo with camera + light.

3D Gaussian Splatting (.splat)

Convert SDF surfaces into Inria 3DGS-compatible .splat files (32 bytes/splat: position + scale + RGBA + compressed quaternion). Drop-and-drop into any WebGL viewer (gsplat.tech / SuperSplat / antimatter15/splat).

use alice_sdf::io::splat::{sdf_to_splats, save_splat, SplatConfig};
use alice_sdf::prelude::*;

let node = SdfNode::sphere(1.0);
let cfg = SplatConfig { bounds: (-2.0, 2.0), resolution: 64, base_color: [220, 220, 240, 255] };
let splats = sdf_to_splats(&node, &cfg);
save_splat("sphere.splat", &splats).unwrap();

Blender Add-on (bindings/blender/)

Blender 4.0+ add-on. Imports .asdf directly and adds an "ALICE-SDF" N-panel with sphere/box/torus generators. Requires the alice_sdf Python module (built via cargo build --release --features python).

Install: zip the alice_sdf_blender/ folder and load via Edit > Preferences > Add-ons > Install....

Houdini Python Plugin (bindings/houdini/)

SideFX Houdini 20+ Python module + Python SOP code for .asdf loading and primitive generation. Auto-installer detects $HSITE / $HOUDINI_USER_PREF_DIR.

import alice_sdf_hou
sdf = alice_sdf_hou.sphere(1.0)
alice_sdf_hou.sdf_to_hou_geo(sdf, hou.pwd().geometry(), bounds=(-2.0, 2.0), resolution=64)

MagicaVoxel .vox IO

Voxelize an SDF tree and save as a MagicaVoxel-compatible .vox file (v150 RIFF) — ideal for indie / voxel art pipelines.

use alice_sdf::io::vox::{sdf_to_vox, save_vox, VoxConfig};
use alice_sdf::prelude::*;

let node = SdfNode::sphere(1.0);
let cfg = VoxConfig { size: 64, bounds: (-1.5, 1.5), color_index: 79 };
save_vox("sphere.vox", &sdf_to_vox(&node, &cfg)).unwrap();

@alice-sdf/threejs — Three.js / React Three Fiber wrapper

TypeScript npm package built on the wasm feature. Exposes AliceSDF class, Three.js DataTexture helper, optional <AliceSDFSlicePlane> for @react-three/fiber, and WebXR raymarching helpers.

import { AliceSDF } from "@alice-sdf/threejs";
const sdf = await AliceSDF.load("/alice_sdf.js");
const tex = await sdf.createSliceTexture(512, 512, [0, 0, 0], 1.0, 2.5);
scene.add(new THREE.Mesh(new THREE.PlaneGeometry(2, 2), new THREE.MeshBasicMaterial({ map: tex })));

Maya Python Plugin (bindings/maya/)

Autodesk Maya 2024+ Python module — adds "ALICE-SDF" top-level menu, builds polygon meshes through MFnMesh.

import alice_sdf_maya
alice_sdf_maya.register_menu()
alice_sdf_maya.add_sphere(radius=1.5, resolution=64)

Nuke Python Plugin (bindings/nuke/)

Foundry Nuke 15 / 16+ Python module — exports .asdf to volume binary and 2D RGBA slices for compositing pipelines.

import alice_sdf_nuke
alice_sdf_nuke.export_asdf_as_volume("/path/to/model.asdf", out_path="/tmp/model.alicevdb")

Cinema 4D Python Plugin (bindings/cinema4d/)

Maxon Cinema 4D 2024 / 2025 / 2026+ Python module — generates PolygonObject from SDF primitives and imports .asdf directly into the C4D scene.

import alice_sdf_c4d
alice_sdf_c4d.add_sphere(radius=100.0, resolution=64)   # C4D units: cm
alice_sdf_c4d.import_asdf("/path/to/model.asdf", bounds=(-300.0, 300.0), resolution=128)

CAD Interchange — STEP / IGES (FEM-style mesh export)

ALICE-SDF can tessellate any SDF tree (Marching Cubes) and emit either:

• STEP AP203 (ISO 10303-21 ASCII) — CARTESIAN_POINT + POLY_LOOP + FACE_OUTER_BOUND triangles. Note: this is a mesh-style representation, not a full ADVANCED_FACE / MANIFOLD_SOLID_BREP BREP. Tools that accept faceted STEP (FreeCAD, some Rhino plugins, mesh-aware CAD viewers) can open it; tools that strictly require MANIFOLD_SOLID_BREP may reject it. Full BREP wrapping is planned (see docs/PUBLISH.md).
• IGES (Entity 134 Node + Entity 136 Finite Element) — FEM mesh entities. Intended for FEM solvers and viewers that understand these entity types. Standard CAD modeling tools usually expect Entity 144 (Trimmed Surface), which is not yet emitted.

Both files round-trip in the unit tests but real-world CAD interoperability is best verified per-tool.

use alice_sdf::io::step::{export_step, StepConfig};
use alice_sdf::io::iges::{export_iges, IgesConfig};
use alice_sdf::prelude::*;

let node = SdfNode::sphere(1.0);
export_step("sphere.step", &node, &StepConfig::default()).unwrap();
export_iges("sphere.igs",  &node, &IgesConfig::default()).unwrap();

alice-sdf-openxr — Native VR / AR Helpers (bindings/openxr/)

A small Rust crate on top of the openxr bindings that turns ALICE-SDF distance queries into VR-friendly helpers. Works with Meta Quest standalone (Android APK), PC VR (SteamVR / Oculus PC), Microsoft Mixed Reality, and Apple Vision Pro via its OpenXR backend.

use alice_sdf_openxr::{XrPose, raymarch_sphere};
use glam::Vec3;

// inside an XRFrame callback
let head_pose: XrPose = openxr_pose.into();
let hit_dist = raymarch_sphere(head_pose, Vec3::new(0.0, 1.5, -1.0), 0.3, 5.0);
if hit_dist > 0.0 {
    // controller / head is looking at the sphere
}

AliceSDFVisionOS — Apple Vision Pro SwiftPM Package (mobile/swift-package-visionos/)

A visionOS / RealityKit-flavoured Swift Package that wraps the same AliceSDF.xcframework used by the iOS / iPadOS / macOS targets and adds factory helpers for ModelEntity.

import SwiftUI
import RealityKit
import AliceSDFVisionOS

struct ImmersiveView: View {
    var body: some View {
        RealityView { content in
            let sphere = AliceSDFRealityKit.makeSphereEntity(radius: 0.1)
            sphere.position = SIMD3(0, 1.5, -1.0)
            content.add(sphere)
        }
    }
}

REST API Server (server/)

An axum + tokio HTTP server that exposes ALICE-SDF primitive evaluation and operations over JSON — intended as the backend for cloud-served SDF UIs (e.g. alicelaw.net/sdf-metaverse).

cd server && cargo run --release
# → ALICE-SDF server listening on http://0.0.0.0:8787

POST /eval
Content-Type: application/json

{ "shape": "sphere", "point": [1, 0, 0], "params": { "radius": 1.0, "center": [0, 0, 0] } }

Response: { "distance": 0.0 }

Related Projects

Copyright (c) 2025-2026 Moroya Sakamoto — https://alicelaw.net/