Viron is your foundational spatial simulation service — the bedrock on which worlds are built.
It manages environments, grids, locations, and entities through a clean REST API so you can skip the boilerplate and focus on fun, emergent gameplay.
It serves as a reusable backend component for simulation-based games, AI experiments, and virtual world applications.
Every game and simulation needs a shared understanding of where things are and how they relate.
Without Viron, developers waste weeks reinventing grid systems, spatial queries, and entity placement logic for each new project.
With Viron:
- Creating an entire environment takes seconds.
- Populating it with entities is a single API call.
- Debugging is instant and visual.
- Multiplayer is a breeze because the world is already consistent for every client.
You sit down with your morning coffee.
In five minutes, you’ve:
- Spawned an entire planet via
POST /api/v1/environments. - Populated it with hundreds of plants and creatures with one request.
- Watched the simulation come alive as agents move, interact, and adapt.
- Debugged a gameplay issue in seconds by querying exactly what’s in a problem area.
Instead of building coordinate math and entity managers from scratch, you’re free to design mechanics, test wild ideas, and ship faster.
Viron abstracts away low-level spatial data management so client applications can focus on simulation logic, rendering, and game mechanics.
Core responsibilities:
- Managing hierarchical spatial structures (environments → grids → locations).
- Tracking entity placement and movement.
- Providing clean, testable REST APIs.
- Offering debug tools for rapid development and testing.
The MVP implements the endpoints defined in docs/openapi/viron-api.json and documented in docs/MVP.md.
Environment Management
- Create, retrieve, update (including renaming), and delete environments.
- Create grids as squares (
gridSize) or with independent dimensions (numRows/numColumns). - Query environments by ID, name, or contained entity.
Grid Management
- Retrieve grids by ID or environment.
- Find the grid containing a specific entity.
Location Management
- Retrieve locations by ID, grid, or environment.
- Manage entity placement in locations.
Entity Management
- Create, retrieve, and delete entities.
Debug Utilities
- Generate sample environments, grids, locations, and entities.
- Quickly create a world and place an entity for testing.
- Disabled by default — set
VIRON_DEBUG_ENABLED=true(propertyviron.debug.enabled) to register/api/v1/debug/**. Left off, those endpoints are not mapped at all, so debug tooling does not ship to production.
For detailed endpoint definitions and request/response formats, see
docs/MVP.mdanddocs/openapi/viron-api.json.
- Java 21
- Spring Boot 3
- Lombok
- MapStruct (model ↔ DTO mapping)
- Spring Security (OAuth2 resource server / JWT)
- PostgreSQL (persistence layer)
- Maven (build tool)
- Docker + Docker Compose (deployment)
- Swagger/OpenAPI (API documentation)
- JaCoCo (test coverage)
- Planned: Flyway (future migrations); schema currently comes from
db-scripts/setup/
viron/
├── src/main/java/preponderous/viron/
│ ├── config/ # Spring configuration (security, database, OpenAPI)
│ ├── controllers/ # REST controllers (Environment, Grid, Location, Entity, Debug)
│ ├── database/ # JDBC access helpers
│ ├── dto/ # Data Transfer Objects for API requests/responses to keep internal models private
│ ├── exceptions/ # Exception types and the global exception handler
│ ├── factories/ # Creation logic for environments and entities
│ ├── mappers/ # MapStruct mappers between models and DTOs
│ ├── models/ # Internal domain models
│ ├── repositories/ # Data access layer
│ └── services/ # Business logic
├── src/main/python/ # Python client SDK
├── src/test/java/... # Unit and integration tests
├── db-scripts/ # SQL schema setup scripts
├── docs/
│ ├── MVP.md # Implementation checklist for MVP
│ └── openapi/
│ └── viron-api.json # API specification
├── postman/ # Postman collection generated from the API specification
├── pom.xml # Maven configuration
└── README.md # This file
- Java 21
- Maven 3.9+
- Docker & Docker Compose
mvn clean install
docker-compose up --build
API will be available at: http://localhost:8080
Once running, you can view the interactive API docs:
http://localhost:8080/swagger-ui.html
or refer to the docs/openapi/viron-api.json file.
Run all unit and integration tests:
mvn test
This project is licensed under the MIT License.
Copyright © 2022-2025 Daniel McCoy Stephenson. All rights reserved.
For inquiries, feature requests, or contributions, please open an issue or reach out via the official GitHub repository:
https://github.com/Preponderous-Software/Viron