EvaluatedApplications.Tracer 2.0.2

Tracer

Fast pathfinding and game-AI SDK for .NET: navmesh pathfinding, multi-agent movement, dynamic obstacles, line-of-sight and fog-of-war, influence maps, combat engagement, and tactical behaviors — for real-time simulations with many moving agents (crowds, RTS unit groups, tactical squads). Built on the EvalApp pipeline runtime, so every stage is resource-gated and adaptively tuned to your frame budget.

This page is the only documentation shipped with the package — it is binary-only (source is not distributed), so every public type and method is covered below with a one-line purpose and a working example. All examples were compiled and run against the real package before publishing; every printed // => line is real output, not a guess.

Table of contents

1. Quick start
2. Core concepts and gotchas
3. PathfindingWorld — the root factory
4. Navmesh baking
5. Single-agent pathfinding
6. Multi-agent swarm ticking
7. Layered navmeshes (ground / air / water)
8. Dynamic obstacles
9. Adaptive path budgeting
10. Population simulation (NavSim)
11. Line-of-sight and vision
12. Fog of war
13. Influence maps
14. Congestion analysis
15. Combat engagement
16. Steering behaviors and the Navigator
17. Grid tactics (bake-free tile lane)
18. Population helpers
19. Dependency injection
20. EvalApp pipeline integration
21. License

Quick start

dotnet add package EvaluatedApplications.Tracer

using System.Numerics;
using System.Collections.Immutable; // only needed later, for section 8 (NavSim)
using Tracer;
using Tracer.Models;

var world = new PathfindingWorld();

// Bake a navmesh from a 4x4 square made of two triangles.
var vertices  = new List<Vector2> { new(0, 0), new(4, 0), new(4, 4), new(0, 4) };
var triangles = new List<(int A, int B, int C)> { (0, 1, 2), (0, 2, 3) };
var baker = world.CreateNavMeshBakerService();
var mesh  = await baker.BakeAsync(vertices, triangles);

// Query a single smoothed path.
var single    = world.CreateSingleAgentService();
var waypoints = await single.QueryPathAsync(mesh, new Vector2(0, 0), new Vector2(4, 4));
// waypoints.Count => 2

// Or tick a whole swarm of agents at once (agents sharing a goal reuse one solve).
var agents = new List<AgentDto> { new(Id: 1, Position: new Vector2(0, 0), Goal: new Vector2(4, 4)) };
var multi  = world.CreateMultiAgentService();
var result = await multi.TickAsync(agents, mesh, tickNumber: 0);
// result.Paths.Count => 1, result.Pressure => 0.0 (no TargetFrameMs supplied)

The rest of this page continues from this snippet — world, mesh, and agents below are the ones created here, unless a section says otherwise. Every snippet below was verified against the real package; as sections introduce new types, add their namespace the same way you would in any C# file: Tracer.Abstractions (interfaces, AdaptiveOptions), Tracer.Services (GameMath), Tracer.Behaviors, Tracer.Helpers, Tracer.Extensions (AddTracer), Tracer.Integration, Microsoft.Extensions.DependencyInjection, EvalApp.

Core concepts and gotchas

• Coordinates. Everything is System.Numerics.Vector2 in whatever world-space units you baked the mesh with (meters, tiles-as-floats, pixels — your choice). Grid-tactics helpers (section 15) use plain int tile coordinates instead — a separate, bake-free lane.
• Navmesh is triangles, not a tile grid. Bake via INavMeshBakerService — 2 triangles per walkable square cell if you're sourcing from a grid. NavMeshHandle is opaque; you never see the triangle list.
• Unreachable / off-mesh targets never throw. ISingleAgentService.QueryPathAsync returns an empty list; IMultiAgentService.TickAsync returns PathResultDto.PathFound = false with empty Waypoints. The only ArgumentExceptions are on empty input to BakeAsync/FromTriangles (you cannot construct a zero-triangle handle through the public API).
• Costs are in world units, not percentages: NavMeshBlockedZone.Radius, InfluenceSourceDto.FalloffRadius, VisionProfile.Range, ConflictRadius are all world-space distances in your baking units.
• Blocking vs excluding. INavMeshBakerService.BakeAsync's blockedZones excludes covered triangles from the mesh entirely (triangle count drops). IDynamicObstacleService. UpdateAsync's zones isolate triangles in place (clears their neighbours; triangle count never changes). UpdateAsync's newBlockedZones is always the full replacement set, not a delta — pass empty to unblock everything since the last bake or ResetBase().
• Thread-safety. NavMeshHandle/HierarchicalNavMeshHandle/LayeredNavMeshHandle are immutable — safe to read from any thread and to swap atomically between ticks. The stateful services returned by PathfindingWorld.Create* persist tuner state to disk per instance; two services sharing the same serviceKey (and hence the same tuner-state path) should not be driven concurrently from different threads. The stateless services (ILineOfSightService, ICongestionService, IFogOfWarService) have no shared state and are safe to call concurrently.
• Performance — goal sharing. IMultiAgentService.TickAsync caches guidance per goal, not per agent: 500 agents converging on one exit compute that guidance once, then every agent reuses it for free. This is why large swarms stay cheap; see TickOptions in section 4.
• License. Proprietary — see the License section at the end of this page. PathfindingWorld's optional licenseKey only toggles whether adaptive tuning attaches — it never gates a capability off.

1. PathfindingWorld — the root factory

PathfindingWorld is the single entry point. It vends every stateful service, each isolated under its own tuner-state subdirectory so independent levels/zones don't share adaptive-tuning history.

var world1 = new PathfindingWorld();                              // free tier, default tuner path
var world2 = new PathfindingWorld(tunerStatePath: "C:/game/nav");  // custom tuner path
Console.WriteLine(world1.LicenseMode);                             // => Unlicensed

2. Navmesh baking

INavMeshBakerService turns raw triangle geometry into an opaque NavMeshHandle.

var blockedZones = new List<IReadOnlyList<Vector2>>
{
    new List<Vector2> { new(10, 10), new(11, 10), new(11, 11) } // excluded if it covers triangles
};
var meshWithHole = await baker.BakeAsync(vertices, triangles, blockedZones);
// meshWithHole.TriangleCount => 2 (this zone lies outside the 4x4 square, so nothing is excluded)

var hierarchical = await baker.BakeHierarchicalAsync(
    vertices, triangles, blockedZones: null, new SimplificationOptions(MinClusterSize: 2));
// hierarchical.FineTriangleCount => 2, hierarchical.CombinedTriangleCount => 2

var manualMesh = NavMeshHandle.FromTriangles(new List<NavMeshTriangleDefinition>
{
    new(0, new Vector2(0,0), new Vector2(4,0), new Vector2(4,4), new List<int>{1}),
    new(1, new Vector2(0,0), new Vector2(4,4), new Vector2(0,4), new List<int>{0}),
});
Console.WriteLine(manualMesh.FindNearestTriangle(new Vector2(2, 2))); // => 0
Console.WriteLine(manualMesh.HasLineOfSight(new Vector2(0,0), new Vector2(4,4))); // => True

BakeAsync/FromTriangles throw ArgumentException on an empty vertex/triangle list — the only two public ways to obtain a NavMeshHandle, so a handle can never have zero triangles.

3. Single-agent pathfinding

ISingleAgentService is for point-to-point queries where each agent has its own distinct goal. For large swarms sharing goals, prefer IMultiAgentService (section 4) — it is far cheaper.

QueryPathAsync is already shown in the Quick Start above (single.QueryPathAsync(...)). Continuing with the same single and mesh, here's the batch overload:

var batch = await single.QueryPathBatchAsync(mesh, new[]
{
    (new Vector2(0,0), new Vector2(4,4)),
    (new Vector2(0,0), new Vector2(99,99)),   // off-mesh goal
});
Console.WriteLine(batch[1].Count > 0); // => False (unreachable)

4. Multi-agent swarm ticking

IMultiAgentService is the core swarm tick: pass every agent once per frame, get one PathResultDto per agent back. Agents sharing a goal reuse one cached solve, so a crowd of 500 agents heading to the same point is nearly as cheap as pathing one.

The basic call is already shown in the Quick Start above (multi.TickAsync(agents, mesh, 0)). Continuing with the same agents/multi/mesh, here's an explicit TickOptions:

var tuned = new TickOptions(
    Mode: PathfindingMode.Tuned, TargetFrameMs: 16.67,
    SurroundingMode: true, MaxDirectChasers: 1);
var result2 = await multi.TickAsync(agents, mesh, tickNumber: 1, tuned);
// result2.Paths.Count => 1

Only agents with GoalChanged = true get a fresh path; GoalChanged = false agents are forwarded unchanged at zero cost. Pressure is only meaningful in Tuned mode (or any mode with a TargetFrameMs to compare against) — otherwise it reads 0.0. SurroundingMode makes a group converging on one goal spread across distinct approach corridors automatically (emergent encirclement) — MaxDirectChasers controls how many agents bypass that staging and chase directly.

5. Layered navmeshes (ground / air / water)

LayeredNavMeshHandle lets ground, air, and water units navigate on separate meshes while still being ticked together in one TickAsync call.

var airMesh  = await baker.BakeAsync(vertices, triangles); // a separate mesh for flying units
var layered  = LayeredNavMeshHandle.Create(
    (MovementLayer.Ground, mesh),
    (MovementLayer.Air,    airMesh));
Console.WriteLine(layered.LayerCount); // => 2

var groundOnly     = LayeredNavMeshHandle.FromGround(mesh);
var layeredResult  = await multi.TickAsync(agents, layered, tickNumber: 2);
// layeredResult.Paths.Count => 1

An agent whose MovementLayer has no entry in the LayeredNavMeshHandle is forwarded unchanged with PathFound = false — it never throws. Each layer's flow-field cache is independent, so swapping one layer's mesh does not invalidate another layer's cached guidance.

6. Dynamic obstacles

IDynamicObstacleService blocks and unblocks regions of an already-baked mesh at runtime without a full re-bake.

var obstacles    = world.CreateDynamicObstacleService();
var zone         = new NavMeshBlockedZone(Center: new Vector2(2, 2), Radius: 0.5f);
var blockedMesh  = await obstacles.UpdateAsync(mesh, new[] { zone });
// blockedMesh.TriangleCount == mesh.TriangleCount -- isolation, not exclusion (see Core concepts)

var restoredMesh = await obstacles.UpdateAsync(blockedMesh, Array.Empty<NavMeshBlockedZone>());
obstacles.ResetBase(); // call this right after any full re-bake, not after every UpdateAsync

newBlockedZones is always the full replacement set, not a delta — an empty enumerable restores every triangle blocked since the base was captured (first call, or last ResetBase()). UpdateAsync throws ArgumentException if current has zero triangles — unreachable in practice since no public API can produce a zero-triangle handle.

7. Adaptive path budgeting

IAdaptivePathfindingService is a drop-in replacement for IMultiAgentService that automatically switches strategy under load: below a threshold it delegates straight through (zero overhead); above it, it clusters nearby agents with similar goals and paths only cluster representatives, synthesizing follower paths via formation offsets.

var adaptive        = world.CreateAdaptivePathfindingService();
var adaptiveOptions = new AdaptiveOptions(GroupingThreshold: 0.70f, GroupRadius: 3.0f, MaxGroupSize: 8);
var adaptiveResult  = await adaptive.AdaptiveTickAsync(agents, mesh, tickNumber: 0, pipelineLoad: 0.9f, adaptiveOptions);
// adaptiveResult.Paths.Count => 1

8. Population simulation (NavSim)

NavSim is the highest-level, population-as-a-black-box API: declare named populations with compute-weight shares, and the SDK runs every population's pathfinding strategy internally (each population gets its own IAdaptivePathfindingService under the hood).

var sim = NavSim.Create(world)
    .WithFrameBudget(16.67)
    .AddPopulation("creeps", maxCount: 100, computeWeight: 1.0f)
    .Build();

var simInput = new SimTickInput(mesh, TickNumber: 0, Populations: ImmutableArray.Create(
    new PopulationInput("creeps", agents, ComputeWeight: 1.0f)));

var simResult  = await sim.TickAsync(simInput);
var creepResult = simResult.GetPopulation("creeps");
// creepResult.Paths.Count => 1

9. Line-of-sight and vision

ILineOfSightService combines range checks, cone/sector vision, and navmesh walkability.

var los      = world.CreateLineOfSightService();
var canSee   = los.HasLineOfSight(mesh, new Vector2(0, 0), new Vector2(4, 4)); // => True

var observer = new AgentDto(1, new Vector2(0, 0), new Vector2(0, 0));
var vision   = new VisionProfile(Range: 10f, FieldOfViewDeg: 90f, FacingAngleRad: 0f);
var targets  = new List<AgentDto> { new(2, new Vector2(3, 0), new Vector2(3, 0)) };

var visResults = los.QueryVisibility(mesh, observer, vision, targets);
// visResults.Count(r => r.IsVisible) => 1

var allPairs = los.QueryAllPairs(mesh, new[] { (observer, vision), (targets[0], vision) });
// allPairs.Length => 2

10. Fog of war

IFogOfWarService manages a grid of per-cell visibility state across ticks — independent of the navmesh pathfinding, shares only NavMeshHandle for grid bounds.

var fow     = world.CreateFogOfWarService();
var fogGrid = fow.CreateGrid(mesh, new FogOfWarOptions(CellSize: 1f, Mode: FogMode.ExploredPersists, MaxRevealRadius: 20));
fow.Update(fogGrid, new[] { (observer, vision) }, mesh);

var cellVis = fow.GetVisibility(fogGrid, new Vector2(1, 1)); // => Visible
Console.WriteLine(fogGrid.AtWorld(new Vector2(1, 1)));       // => Visible
Console.WriteLine(fogGrid.WorldToCol(new Vector2(1, 1)));    // => 1
Console.WriteLine(fogGrid.CellCenter(0, 0));                 // => <0.5, 0.5>

var snapshot = fogGrid.GetSnapshot();     // ReadOnlyMemory<CellVisibility>, for serialization
fogGrid.RestoreSnapshot(snapshot.Span);   // round-trip it back
Console.WriteLine(fogGrid[0, 0]);         // => Visible

11. Influence maps

IInfluenceMapService computes one combined influence float per navmesh triangle from a set of positioned emitters (e.g. "how controlled/dangerous is this area") — useful for AI tactical decisions.

var influence = world.CreateInfluenceMapService();
var sources   = new List<InfluenceSourceDto> { new(Position: new Vector2(0, 0), Strength: 10f, FalloffRadius: 5f) };
var values    = await influence.ComputeAsync(mesh, sources);
// values[0] => 10.00 (triangle 0 contains the source itself)

Sources whose position falls outside the navmesh are silently excluded; an empty sources list returns all zeros.

12. Congestion analysis

ICongestionService is a cheap (O(n), single-pass spatial hash), per-tick snapshot of crowd density and flow — feeds the Queue/FlowLane steering behaviors (section 14) but is usable standalone for any congestion-aware logic.

var congestionService = world.CreateCongestionService();
var congestion = congestionService.ComputeMap(agents, previousPositions: null, cellSize: 2f);

Console.WriteLine(congestion.GetDensity(new Vector2(0, 0)));        // => 1
Console.WriteLine(congestion.GetFlowDirection(new Vector2(0, 0)));  // => <0, 0> (no previous positions yet)
Console.WriteLine(congestion.IsCongested(new Vector2(0, 0)));       // => False
Console.WriteLine(congestion.GetFlowCoherence(new Vector2(0, 0)));  // => 0

13. Combat engagement

IEngagementService resolves attacker-vs-defender combat between two groups using spatial partitioning and parallel per-defender resolution. Consumers supply their own agent type extending GameAgent — the SDK never touches your extra fields but preserves them through.

var attackers = new List<GameAgent> { new(Id: 10, Position: new Vector2(0,0),   Goal: new Vector2(0,0),   Attack: 20f, Defense: 5f) };
var defenders = new List<GameAgent> { new(Id: 20, Position: new Vector2(0.5f,0), Goal: new Vector2(0.5f,0), Attack: 10f, Defense: 5f, Health: 50f, MaxHealth: 50f) };

var engagement   = world.CreateEngagementService();
var engageResult = await engagement.ResolveAsync(attackers, defenders, radius: 2f, ct: default);
// engageResult.Outcomes.Length => 2 (bidirectional: both sides attack each tick)
// engageResult.UpdatedDefenders[0].Health => 32.5 (damage already applied)

var outcomesOnly = await engagement.ResolveOutcomesAsync(attackers, defenders, radius: 2f, ct: default);
// outcomesOnly.Length => 2, no Health change on attackers/defenders themselves

// Custom resolver: you decide what happens per attacker/defender pair.
Func<GameAgent, GameAgent, float, IGameMath, IEnumerable<EngagementOutcome>> customResolver =
    (a, d, dist, math) => new[] { EngagementOutcome.Miss(a.Id, d.Id) };
var customResult = await engagement.ResolveAsync(attackers, defenders, radius: 2f, customResolver, ct: default);
// customResult.Outcomes[0].Kind => Miss

// Custom math (tuning the built-in formulas, or implement IGameMath yourself for different mechanics).
var customMath = new GameMath(new GameMathOptions(BaseHitChance: 0.8f, CritChance: 0.15f));
Console.WriteLine(customMath.HitChance(20, 5, 1, 5));  // => 0.95
Console.WriteLine(customMath.DamageRoll(20, 5));       // => 17.50
Console.WriteLine(customMath.CooldownTicks(1f));       // => 10

var engagementWithMath = world.CreateEngagementService(gameMath: customMath);

Per-agent MaxAttacksPerTick budget: overflow hits beyond the cap are demoted to Miss, never dropped — total outcome count is unchanged either way. AttackLayerMask (a MovementLayer combination) restricts which defender layers an attacker can reach; the default All preserves "everyone can attack everyone in range" behavior.

14. Steering behaviors and the Navigator

INavigatorService composes pluggable INavigationBehaviors with pathfinding: each tick, every behavior scores itself, the highest score wins, its goal is evaluated, then the winning goal is pathfound. Build one via the fluent NavigatorBuilder.

var navigator = world.CreateNavigator()
    .WithMesh(mesh)
    .WithBehavior(new SeekBehavior())
    .WithBehavior(new WanderBehavior(radius: 2f, seed: 42))
    .WithBehavior(new PatrolBehavior(new List<Vector2> { new(0,0), new(4,4) }, arrivalDistance: 0.5f))
    .WithBehavior(new FleeBehavior(fleeRadius: 5f))
    .WithBehavior(new QueueBehavior())
    .WithBehavior(new FlowLaneBehavior())
    .WithStrategy(new DefaultNavigationStrategy(stuckThreshold: 5))
    .WithCongestion()
    .Build();

var navResult = await navigator.TickAsync(agents, tickNumber: 0);
// navResult.Paths.Length => 1, navResult.Paths[0].ActiveBehavior => "Seek"

Stuck handling: every tick, NavigatorService asks your INavigationStrategy IsStuck(agent, lastPath, consecutiveFailures); if true, OnPathFailed picks the fallback — Retry (default) leaves the goal alone, Stop zeroes Waypoints/PathFound and relabels ActiveBehavior to "Stopped", Wander re-paths to an internally sampled nearby point and relabels ActiveBehavior to "Wander (fallback)".

15. Grid tactics (bake-free tile lane)

Tracer.Helpers.GridTactics is a separate, pure/static lane for tile or square-grid tactics games that don't want a navmesh at all. The grid is supplied as predicates (passable/blocksSight), so it works with any tilemap representation.

bool[,] walls = new bool[10, 10];
walls[5, 5] = true;
bool BlocksSight(int x, int y) => x is >= 0 and < 10 && y is >= 0 and < 10 && walls[x, y];
bool Passable(int x, int y)    => x is >= 0 and < 10 && y is >= 0 and < 10 && !walls[x, y];

bool sees  = GridTactics.LineOfSight(0, 0, 9, 9, BlocksSight);         // => False (wall at (5,5) blocks it)
var reach  = GridTactics.Reachable(0, 0, maxSteps: 3, Passable);       // => 10 reachable tiles (incl. start)
bool cover = GridTactics.InCover(4, 5, BlocksSight);                   // => True (adjacent to the wall)

var gridTargets = new List<(int X, int Y)> { (3, 3), (6, 6) };
int nearest = GridTactics.NearestInRange(0, 0, gridTargets, t => t, range: 10, BlocksSight);
// nearest => 0 (index of (3,3))

Use this instead of ILineOfSightService/ISingleAgentService for tile/square-grid games — no bake step needed at all.

16. Population helpers

Small standalone utilities for common swarm-management problems; none require a PathfindingWorld.

int keep = AgentBudget.Allocate(pressure: 0.8f, currentCount: 500, maxCount: 500, morale: 0.5f);
// keep => 160

var spread = GoalSpreading.Spread(
    agents, new List<Vector2> { new(4, 4), new(10, 10) }, new GoalSpreadingOptions(AllowReuse: false));
// spread.Length => 1, one (AgentId, Goal) pair per input agent that got a goal

var spawnPoints = SpawnPool.GetSpawnPoints(
    new List<Vector2> { new(0, 0), new(0.1f, 0), new(5, 5) }, count: 2, new SpawnPoolOptions(MinSpacing: 1f));
// spawnPoints.Length => 2 (the two candidates close together collapse to one pick)

17. Dependency injection

Tracer.Extensions.ServiceCollectionExtensions.AddTracer registers Tracer with Microsoft.Extensions.DependencyInjection.

using Microsoft.Extensions.DependencyInjection;
using Tracer.Extensions;

var services = new ServiceCollection();
services.AddTracer(options => { options.TunerStatePath = "C:/game/nav"; });
var provider = services.BuildServiceProvider();

var diWorld = provider.GetRequiredService<PathfindingWorld>();
var diMulti = provider.GetRequiredService<IMultiAgentService>();
// diWorld.LicenseMode => Unlicensed

Adaptive pathfinding, engagement, LOS, congestion, fog-of-war, simulation, and the navigator are not DI-registered — resolve PathfindingWorld from the container and call its Create* methods directly for those.

18. EvalApp pipeline integration

Tracer.Integration plugs a PathfindingWorld and its services into an EvalApp pipeline as a shared global context, for consumers already building their game loop on EvalApp.

using EvalApp;
using Tracer.Integration;

var appBuilder = Eval.App("my-game").WithTracer(world);

Gotcha: EvalApp.IAppBuilder.WithContext holds a single global context (last call wins). If your app also calls WithContext for another package (e.g. a database SDK) on the same builder, one context silently replaces the other. Build one Eval.App(...) per concern if you need both.

License

Proprietary — this package ships the compiled library only; see LICENSE for the full terms. Installing and using unmodified copies for internal evaluation and non-commercial development or testing is licensed; commercial, production, or revenue-generating use requires a separate commercial licence from the owner. No feature on this page is gated behind a tier or a licence key — every capability described works identically with or without one. Copyright (c) 2026 Dongyang Stephen Chen, trading as Evaluated Applications. All rights reserved.

PathfindingWorld's optional licenseKey constructor parameter exists but has no effect on which capabilities are available — see Core concepts and gotchas above.