agentsim

agentsim is a Go agent simulation engine designed for integration with digital twins of built infrastructure. It manages agents, roles, behavior trees, per-agent blackboards, time control, observation, and deviation detection.

The project does not store spatial truth or compute routes directly. A functional deployment integrates with:

• geotruth: spatial truth module for objects, areas, positions, and spatial queries.
• LifeRouter: pathfinding module for route calculation, agent movement, and cost-map distribution.
• NATS: communication bus between services and the public engine API.

Requirements

• Go 1.25.3 or a compatible later version.
• A NATS instance shared by the modules.
• Go dependencies available from the repositories listed in go.mod.

Project Structure

• cmd/mainTruth: local startup for the embedded spatial truth module.
• cmd/main: local startup for LifeRouter and the engine with the debug server.
• pkg/agent: public types and internal agent service.
• pkg/agentnats: Go client for consuming the NATS API.
• pkg/embedded: helpers for starting the engine in embedded mode.
• internal/bt: behavior trees, nodes, decorators, and blackboards.
• internal/engine: time loop, agents, watchers, and deviations.
• internal/helper: adapters for external services.
• data: sample behavior trees, blackboards, map, and initial world data.

Local Usage

Start the spatial truth service in one terminal:

cd cmd/mainTruth
go run .

Start the engine and the pathfinding module in another terminal:

cd cmd/main
go run .

The included local configuration exposes the debug server at:

http://localhost:7777

Tests

Run the full test suite:

go test ./...

Check coverage:

go test -cover ./...

On Windows, the Go race detector requires a C compiler compatible with MinGW. For example:

$env:CC='C:\Strawberry\c\bin\x86_64-w64-mingw32-gcc.exe'
go test -race ./...

The internal/testing integration test uses the map included at data/map.png.

Third-Party Notices

Main direct dependency notices are listed in THIRD_PARTY_NOTICES.md.

License

This project is licensed under the Apache License, Version 2.0. See LICENSE for details.

Third-party dependency notices are listed in THIRD_PARTY_NOTICES.md.

Author

Developed by Salustiano Fernández Carro.