Skip to content

tess tess

C++20 grid pathfinding and simulation, without an engine

tess is a header-only C++20 library for bounded grid storage, topology-aware pathfinding, and deterministic simulation updates. It supplies the spatial substrate while leaving rendering, physics, and entity ownership to your application.

This site documents the v1.0.0 release. The 1.x release line preserves the documented stable source API. See support and compatibility for the stability policy and the roadmap for future work.

Get started Explore tutorials API reference

Live demonstrations

  • Live pathfinder

    Move endpoints, paint obstacles, and inspect a real A* query compiled from the C++20 library.

    Open pathfinder

  • Strategy comparison

    Compare A*, route caching, weighted batches, and shared-goal fields by their call shape and reuse counters.

    Compare strategies

  • Colony simulation

    Watch up to 1,024 agents replan around queued wall edits in a deterministic fixed-step model.

    Run colony

  • Live diagnostics

    Inspect path, queued-phase, trace, timing, and consumer allocation snapshots through Dear ImGui and mirrored HTML controls.

    Inspect diagnostics

  • Congestion Lab

    Explore supported, rejected, and experimental congestion-pricing variants over the colony workload.

    Open Congestion Lab

  • Traffic Lab

    Run a large deterministic crowd model with explicit planning budgets and separately reported browser presentation costs.

    Open Traffic Lab

  • Tower

    Route through one six-floor world whose stair transitions connect the vertical topology.

    Climb the tower

  • WebGPU integration

    Exercise the optional GPU transport and submission boundary; pathfinding itself remains on the CPU.

    Inspect WebGPU

A complete path query

The core of a complete world-shape, field-schema, and A* example (compiled and run in CI):

#include <tess/io.h>
#include <tess/pathfinding.h>

#include <cstdint>
#include <iostream>

// 1. Define a 4x4 2D grid and the data stored for each tile.
struct PassableTag {};
using Shape = tess::Shape<tess::Extent3{4, 4}, tess::Extent3{4, 4}>;
using Schema = tess::FieldSchema<tess::Field<PassableTag, std::uint8_t>>;
using World = tess::AlwaysResidentWorld<Shape, Schema>;

auto run_example() -> int {
  // 2. Create the world and mark the tiles that can be crossed.
  World world;  // Zero-initialized: every tile starts impassable.
  world.fill_field<PassableTag>(1);  // All tiles passable for this example.

  // 3. Reuse this scratch storage for repeated path queries.
  tess::PathScratch scratch;
  const auto result = tess::astar_path<World, PassableTag>(
      world, tess::PathRequest{tess::Coord2{0, 0}, tess::Coord2{2, 1}},
      scratch);

  // 4. Check the status, then print the path coordinates and total cost.
  if (result.status != tess::PathStatus::Found || result.path.empty()) {
    std::cerr << "path query failed: " << result.status << '\n';
    return 1;
  }

  std::cout << "path: " << result.path << '\n';
  std::cout << "cost: " << result.cost << '\n';
  return 0;
}

It prints:

path: [Coord3{0, 0, 0}, Coord3{1, 0, 0}, Coord3{2, 0, 0}, Coord3{2, 1, 0}]
cost: 3

Add it to your build with one CMake FetchContent block or an installed package — see Installation.

Choose the smallest surface

  • <tess/pathfinding.h> provides shapes, worlds, topology, and routing.
  • <tess/simulation.h> adds queued operations, schedules, agents, and ECS concepts.
  • <tess/tess.h> remains the compatibility umbrella.

All three are dependency-free. Optional EnTT and Flecs adapters, plus the separate Dear ImGui panels, remain behind explicit integration headers and compile definitions.

Who is tess for?

  • Game and colony-sim developers — construction edits invalidate routes mid-tick, many agents replan around the change, and the whole loop stays deterministic. Start with the tutorial and examples/colony_2d.cc.
  • Engine integrators — a substrate that owns execution, not your loop: versioned DeltaFrames feed your renderer and adapter concepts bind your ECS.
  • Robotics prototypers — occupancy grids, feasibility prechecks, and dirty-driven replanning with reproducible fixed-step runs; see the robotics walkthrough.
  • Headless simulation and research — agent-based models and servers run the same loop with no renderer at all; see use cases and the machine-adoption recipe in for agents.

Where next

  • Getting started

    The concept ladder: shapes, schemas, worlds, writes, pathfinding, topology, and the schedule loop.

    Tutorial

  • Tutorials

    Connected learning paths for basic routing, colony composition, strategy selection, and congestion pricing.

    Explore tutorials

  • Reference

    Architecture contracts, terminology, compatibility evidence, and the generated C++ API.

    Reference map

  • Performance

    Representative medians and CI-enforced benchmark ceilings.

    Benchmarks

Optional credit

If you use tess in research or a product, we'd appreciate an acknowledgment, a link to the project, or the tess logo. You could include this in your paper's acknowledgments, documentation, about page, or credits.

Suggested credit: "Pathfinding powered by tess" or "This work uses tess for pathfinding and grid-based simulation."

Attribution beyond the notices required by the MIT License is entirely optional.

tess project · Logo for light backgrounds · Logo for dark backgrounds