Open Source · C++23 · Foundation layer

Mosaic

One foundation under every Starworks product.

The zero-dependency C++ layer beneath Arcane, Astra and Manifold2D: platform detection, deterministic SIMD, and the seams every component plugs into.

C++23Zero dependenciesHeader-mostlyMIT

View on GitHub

Language C++23, header-mostly

Depends on the standard library only

Threads none of its own

Licence MIT

The foundation

Every product starts here.

Arcane, Astra and Manifold2D each need the same low-level pieces. Mosaic owns one canonical copy of them, so every component builds on the same ground.

ArcaneThe engine. Its world runs on Astra, its physics on Manifold2D.

AstraThe ECS. Archetype storage, compile-time queries. Manifold2D2D physics. Deterministic rigid bodies.

MosaicPlatform · Jobs · Log · Assert · SIMD · Bits · FunctionRef

C++ standard libraryand nothing else

Each route runs from a product to what it is built on. Arcane builds on Astra, Manifold2D and Mosaic; Astra and Manifold2D build on Mosaic; Mosaic needs only the standard library.

Inside Mosaic

Small. Deliberate. Shared.

Eight pieces every product needs, kept in one canonical copy.

Platform

Architecture, compiler and SIMD-capability detection: MOSAIC_HAS_AVX2, MOSAIC_HAS_NEON, MOSAIC_FORCEINLINE and friends.

Jobs

IWorkScheduler, the threading seam. Mosaic creates no threads: the host injects a scheduler, and SerialWorkScheduler is the deterministic default.

Log

A logging seam: the host installs one sink with SetLogSink, and every library reports through it.

Assert

MOSAIC_ASSERT behind an injected assert handler. A failing guard reaches the host even with logging silenced.

Simd / Wide

Lane-wide f32w, i32w and b32w for solver-style math: AVX2, NEON or scalar, chosen at compile time, and bit-identical to the scalar path.

Simd / Bits

Byte matching, 128- and 256-bit bitmaps and hashing: the toolbox behind SwissTable and bloom acceleration.

Bits · BitSet

Generic bit intrinsics and a compact bit set: one canonical copy instead of one per library.

FunctionRef

A non-owning, zero-allocation callable: how work crosses the scheduler seam without touching the heap.

The seams

Mosaic declares. The host decides.

Real code from Arcane and Manifold2D, lightly trimmed: how a host plugs into each seam.

Arcane adapts its own task system to the seam; Mosaic never makes a thread

// Arcane/Jobs/ArcaneWorkScheduler.hpp
class ArcaneWorkScheduler final : public Mosaic::IWorkScheduler
{
public:
    void ParallelFor(std::size_t count, std::size_t minBatch,
                     Mosaic::FunctionRef<void(std::size_t, std::size_t,
                                              std::uint32_t)> fn) override
    {
        if (m_exec == nullptr)
        {
            if (count != 0) fn(0, count, 0);   // serial: worker 0
            return;
        }
        m_exec->ParallelFor(count, minBatch,
            [&](std::size_t b, std::size_t e, std::uint32_t w) { fn(b, e, w); });
    }

    std::uint32_t WorkerCount() const noexcept override
    {
        return m_exec ? m_exec->WorkerCount() : 1u;
    }

private:
    Arcane::ITaskExecutor* m_exec = nullptr;
};

Arcane routes every library’s logs and asserts into its own logger

// Arcane/Base/Log.cpp
// noexcept sink: forward into the engine logger. category + message are fmt
// ARGUMENTS (literal format) so a stray {} in a message cannot fmt-inject.
void MosaicLogSinkImpl(const Mosaic::LogRecord& r, void* /*user*/) noexcept
{
    try
    {
        Arcane::Log::Engine()->log(
            spdlog::source_loc{r.location.file_name(),
                               static_cast<int>(r.location.line()),
                               r.location.function_name()},
            ToSpd(r.level), "[{}] {}", r.category, r.message);
    }
    catch (...) {}
}

// once, at start-up: Astra and Manifold2D now log and assert through Arcane
Mosaic::SetLogSink(MosaicSink(), nullptr);
Mosaic::SetAssertHandler(Arcane::Assert::MosaicHandler(), nullptr);

Manifold2D solves contacts lane-wide: eight at a time on AVX2, four on NEON

// Manifold2D/Physics/Solver/ContactConstraintSimd.hpp (the normal solve)
const b32w gap = cmp_gt(s, zero);
const f32w biasGap = s * invH;
const f32w biasPen = max(ccBias * s, vMaxNeg);
f32w bias, massScale, impScale;
if (useBias)
{
    bias      = select(gap, biasGap, biasPen);
    massScale = select(gap, one, ccMassScale);
    impScale  = select(gap, zero, ccImpScale);
}
else { /* the relax pass: bias 0, scale 1/0 (elided) */ }

// vn = dot((vA + wA x rA) - (vB + wB x rB), n).
const f32w dvx = (vAx + (-wA * rAy)) - (vBx + (-wB * rBy));
const f32w dvy = (vAy + ( wA * rAx)) - (vBy + ( wB * rBx));
const f32w vn = dvx * nx + dvy * ny;

// impulse = -nMass*massScale*(vn+bias) - impScale*nImp.
f32w impulse = -nMass * massScale * (vn + bias) - impScale * nImp;
// accumulated clamp >= 0.
const f32w newI = max(nImp + impulse, zero);
impulse = newI - nImp;
nImp = newI;
store(pt.normalImpulse, nImp);

Principles

Four promises.

Zero dependencies

The C++ standard library and nothing else. No Astra, Manifold2D, Arcane or third-party include ever enters Mosaic.

Creates no threads

Parallelism goes through the injected IWorkScheduler; the host decides what runs where.

Deterministic SIMD

Simd/Wide builds with strict floating point (/fp:strict, or -ffp-contract=off with no fast-math) and bit-matches the scalar path.

One arrow

Every product depends on Mosaic; Mosaic depends on none of them. Each takes one canonical copy instead of hand-rolling its own.

The stack

What it holds up.

ArcaneEngine Learn more

AstraECS Learn more

Manifold2D2D physics Learn more

Mosaic

Build on Mosaic.

Open source under the MIT licence, and the first thing every Starworks component includes.

C++23
Zero dependencies
Header-mostly
MIT

View on GitHub