ALICE-SDF

Signed distance functions for Rust. A shape is a tree of primitives, CSG operations, transforms and modifiers. The crate evaluates the tree on the CPU (scalar, SIMD, BVH and JIT evaluators), transpiles it to GLSL, WGSL, HLSL and Metal, and turns it into meshes and file formats.

English | 日本語

The same tree drives every backend, and the CPU evaluators return the same bits as each other on every platform CI tests. That makes the tree usable as the single description of a shape: the shader that renders it, the collider that a physics engine queries, and the mesh that is exported or printed are all computed from it, not from separate approximations.

It is not a mesh modeller or a renderer. The GPU shaders are not bit-exact with the CPU (they agree within a tolerance), the value after some modifiers (twist, bend, displacement and similar) is a bound on the distance rather than the distance itself, and turning a field into a fine mesh costs time and memory that grow with the resolution.

Contents

• Installation
• Example
• Determinism
• What is included
• Validation and known defects
• Cargo features
• Bindings
• Performance
• Minimum supported Rust version
• Building and testing
• Related crates
• License

Installation

cargo add alice-sdf

Without the command-line tool (the cli feature, on by default):

cargo add alice-sdf --no-default-features

Python bindings are on PyPI:

pip install alice-sdf

Example

A sphere with a box cut out of it, evaluated, compiled and meshed. The same code is the crate-level doctest in src/lib.rs, so it is compiled and run by cargo test.

use alice_sdf::prelude::*;

// A unit sphere minus a box (box3d takes full extents)
let shape = SdfNode::sphere(1.0).subtract(SdfNode::box3d(1.0, 1.0, 1.0));

// Signed distance: negative inside, zero on the surface, positive outside
let p = Vec3::new(0.9, 0.0, 0.0);
let d = eval(&shape, p);
assert!(d < 0.0);

// Compiled to bytecode for repeated evaluation, with the same bits
let compiled = CompiledSdf::compile(&shape);
assert_eq!(eval_compiled(&compiled, p).to_bits(), d.to_bits());

// A triangle mesh by marching cubes
let mesh = sdf_to_mesh(
    &shape,
    Vec3::splat(-1.5),
    Vec3::splat(1.5),
    &MarchingCubesConfig::default(),
);
assert!(!mesh.indices.is_empty());

More programs are in examples/, and a longer walkthrough (recipes, Python, the LOL language) is in docs/GETTING_STARTED.md.

Determinism

The CPU evaluators (the tree evaluator, compiled scalar, 8-wide SIMD, BVH and the Cranelift JIT) return bit-identical distances for the same tree and point. Two rules make that hold across platforms:

• Every transcendental (sin, atan2, exp, powf, …) goes through alice-det-math, never the platform libm.
• a * b + c is always two roundings; nothing is fused into a multiply-add.

scripts/det_math_guard.py fails CI on a platform libm call or a mul_add in the evaluator and law directories.

Not covered. wasm32 is built in CI but the tests above are not run on it. The GPU shaders (WGSL, GLSL, HLSL, Metal) are a tolerance domain, not a bit-exact one. Targets that do not follow IEEE 754 for the basic operations, and builds with fast-math style flags, are outside the guarantee.

Determinism is not correctness. Matching bits say every machine computes the same numbers; whether the numbers are right is checked separately, see Validation and known defects.

What is included

Every public module, grouped by area with a one-line summary and the feature it needs, is listed in docs/MODULES.md. API details are on docs.rs.

Validation and known defects

Tests in tests/ compare results with closed-form values or with an independent computation: smooth operations, metric fields, interval enclosures (test_interval_soundness.rs), tight bounds, printability, mesh orientation and topology, STEP export, the meshopt codecs against the reference library's vectors, and file-format round trips. Shader output is compiled with naga (and Metal) in CI. Golden hashes only detect change, so they are kept separate from these tests.

docs/oracle-status.md is generated from tests/ and lists every test by status, including tests kept red on purpose (#[ignore = "known defect: …"]) until the implementation is fixed.

docs/wiring-status.md lists public items that nothing outside the tests calls, matched by name. scripts/wiring_guard.py fails CI when a new one appears without a reason. docs/integration-status.md does the same with references resolved by rust-analyzer (scripts/scip_reach.py), so a same-named item elsewhere does not count as a caller; CI fails on a new public item that no example, binding or other module reaches.

docs/node-support.md lists, for every SdfNode variant, which backends handle it: the tree and interval evaluators, the bytecode compiler, both JITs, the Metal and Rust emitters, and the C and Python constructors. tests/test_node_backend_matrix.rs fails CI when a cell changes without the table, and when a variant has no test entry.

scripts/ci_test_coverage_check.py fails CI when a test file gated on a feature is not run by any CI step with that feature, so a feature-gated test cannot report green by running zero tests.

On every push that changes the library, CI (.github/workflows/bake.yml) builds meshes on the GPU (lavapipe) and the CPU for a few scenes with examples/bake_assets, together with glTF, .abm, .nanite, the SDF tree and its bytecode and the collider data (tight AABB, volume, centre of mass, inertia tensor). It checks the files from disk (watertight, GPU and CPU meshes agree, vertices on the surface, closed-form volume and inertia) and keeps them as a workflow artifact.

Cargo features

Features marked AGPL link a crate licensed AGPL-3.0-or-later; see License. All other features, including the defaults, pull in only permissively licensed crates.

Bindings

CI checks the C ABI against its consumers: scripts/abi_decl_check.py and scripts/unreal-abi-check.sh compare every exported function with the C header, the C# bindings and the Unreal Engine plugin.

The Text-to-3D server and the ALICE-View viewer are applications built on the crate; see docs/TEXT_TO_3D.md.

Performance

Benchmarks are in benches/ (criterion):

cargo bench --bench sdf_eval
cargo bench --bench gpu_vs_cpu --features gpu

No numbers are listed here. The figures in older documents were measured before the evaluators were made bit-exact (which removed fused multiply-adds) and have not been measured again since. Run the benchmarks on your target before quoting a number.

Minimum supported Rust version

Minimum supported Rust version: 1.85 (the rust-version in Cargo.toml).

A CI job checks the library with exactly this version for the default features and the docs.rs feature set. Raising the MSRV is a minor-version change, never a patch.

Building and testing

cargo build --release
cargo test
cargo test --features jit --test test_det_parity
cargo test --features "gpu,glsl,gpu-mesh,texture-fit"

scripts/preflight.sh reproduces the CI checks locally (--quick skips the integration and oracle tests).

Related crates

Keep a single version of alice-det-math in your dependency graph. Two versions mean two implementations of the same function, and determinism is lost. Check with cargo tree -i alice-det-math.

Release history is in CHANGELOG.md. Planned work is in docs/ROADMAP.md.

License

The crate is dual-licensed under MIT OR Apache-2.0 (LICENSE-MIT, LICENSE-APACHE).

The physics, codec and sdf-cache features link crates licensed AGPL-3.0-or-later. A build that enables any of them is subject to the AGPL as a whole. The default features and every other feature do not.

The Unity integration (unity-sdf-universe/) and the VRChat package (vrchat-package/) are under the ALICE Community License (LICENSE-COMMUNITY): free for personal use, game development (including commercial games), education and open source; a commercial licence is required for infrastructure services (cloud, metaverse platforms, streaming) as that licence defines them. Commercial licence enquiries: contact@extoria.co.jp

Content you create with the crate (trees, meshes, worlds) is yours.

Many distance functions follow published forms by Inigo Quilez, Mercury (hg_sdf) and Ken Perlin; the list and scope are in THIRD-PARTY-NOTICES.md.

Copyright (C) 2025-2026 Moroya Sakamoto