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), pooled with HikariCP
- 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
Copy sample.env to .env and review the values before starting anything.
JWT_SECRET is required — it has no default, so the service will not start until it is set.
It must match the secret used by the UserAuth service that issues the tokens, and for HS256
it must be at least 32 bytes.
docker-compose up --build
API will be available at: http://localhost:9999
Once running, you can view the interactive API docs:
http://localhost:9999/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