You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This is a tool for creating and managing virtual environments and entities within those environments. This intended to be used for game development, but can be used for other purposes as well.
-[What is a virtual environment?](#what-is-a-virtual-environment)
9
-
-[Testing](#testing)
10
-
-[Running the unit tests](#running-the-unit-tests)
11
-
-[Postman](#postman)
12
-
-[Contributing](#contributing)
13
-
-[Using the dev container](#using-the-dev-container)
14
-
-[Deployment](#deployment)
15
-
-[Starting the application](#starting-the-application)
16
-
-[Stopping the application](#stopping-the-application)
17
-
18
-
## Definitions
19
-
### What is a virtual environment?
20
-
A virtual environment is a space where entities can exist and interact with each other. This can be a 2D or 3D space, and can be as simple as a blank space or as complex as a fully realized world.
21
-
22
-
In Viron, a virtual environment is a 2D space where entities can exist and interact with each other. The environment is made up of a grid of cells, each of which can contain a number of entities. The behavior of the entities is up to the client application, which can define rules for how entities interact with each other and with the environment.
23
-
24
-
## Contributing
25
-
### Using the dev container
26
-
This project includes a dev container that you can use to develop and test the code in a consistent environment. To use the dev container, you will need to have Docker and Visual Studio Code installed on your machine. Once you have those installed, follow these steps:
27
-
1. Make sure the Dev Container extension is installed in Visual Studio Code.
28
-
2. Open the project in Visual Studio Code.
29
-
3. Click on the green "Open a Remote Window" button in the bottom left corner of the window.
30
-
4. Select "Reopen in Container" from the menu that appears.
31
-
5. Visual Studio Code will now build the dev container and open the project inside it.
32
-
6. You can now develop and test the code inside the dev container. Any changes you make will be reflected in the project on your local machine.
33
2
34
-
## Testing
35
-
### Running the unit tests
36
-
#### Java
37
-
To run the unit tests, reopen the project in the dev container and run the following command:
3
+
**Viron** is a flexible simulation framework for building and managing 2D virtual environments. It provides tools to create, traverse, and manipulate grid-based spaces where entities can exist, move, and interact. Viron is designed to be used as a **core simulation engine** for games, AI training environments, educational apps, and more.
38
4
39
-
```bash
40
-
mvn test
41
-
```
5
+
---
42
6
43
-
To generate a code coverage report, run the following command:
7
+
## Design Philosophy
44
8
45
-
```bash
46
-
mvn jacoco:report
9
+
Viron is built to be a lightweight, adaptable core for managing 2D environments. Its focus is on:
10
+
11
+
-**Simplicity** – Easy to understand and integrate
12
+
-**Modularity** – Keeps simulation logic separate from game or application logic
13
+
-**Flexibility** – Supports many types of simulations, from games to research
14
+
-**Structure** – Uses grid-based environments for predictable spatial modeling
15
+
-**Reusability** – Designed to be a foundation for many different projects
16
+
17
+
---
18
+
19
+
## Features
20
+
21
+
-**Modular Architecture** – Easy to plug into Java and Python projects
-**Entity Movement** – Track movement across grid cells and between environments
24
+
-**Simulation Agnostic** – Suitable for ecological sims, city builders, idle games, and more
25
+
-**Multi-language Support** – Java and Python implementations with a shared design
26
+
27
+
---
28
+
29
+
## Example Use Cases
30
+
31
+
### 1. Ecosystem Simulator
32
+
Simulates food chain dynamics in a virtual world. Entities such as foxes, rabbits, and grass interact in Viron-managed environments.
33
+
34
+
### 2. Idle Evolution Game
35
+
Evolves creatures over time in changing biomes, using Viron to track grid-based locations and terrain types.
36
+
37
+
### 3. Educational Tools
38
+
Interactive classroom tools where students can simulate ecological systems or environmental changes.
39
+
40
+
### 4. AI Training Environments
41
+
Use Viron to define spatial challenges or resource collection problems in reinforcement learning projects.
42
+
43
+
### 5. Tic Tac Toe
44
+
Use Viron to model a 3×3 environment where each player places an "X" or "O" on the grid. Track turns, detect win conditions, and enforce valid moves.
45
+
46
+
### 6. Chess
47
+
Represent the 8×8 board as a Viron environment. Each piece is an entity with movement logic handled externally. Viron tracks positions, captures, and board state.
48
+
49
+
### 7. Checkers
50
+
Use a grid-based environment to model diagonal movement and jumping. Viron can track entity state changes (like promotion) and valid move paths.
51
+
52
+
### 8. Block Breaker (Breakout)
53
+
Model the paddle, ball, and blocks within a 2D grid. Viron tracks positions, collisions, and block removal as entities are hit.
54
+
55
+
### 9. Pong
56
+
Represent the playing field, paddles, and ball in a 2D space. Viron manages movement updates, collisions, and scorekeeping.
57
+
58
+
### 10. Snake
59
+
Use Viron to track the snake's body segments and apple placement. Manage movement direction, growth, and self-collision logic.
60
+
61
+
### 11. Turn-Based Tactics Game
62
+
Simulate a battlefield grid with units as entities. Viron manages movement, attack range visibility, and terrain occupancy.
63
+
64
+
### 12. Conway’s Game of Life
65
+
Each cell is alive or dead and changes state based on neighbors. Viron can model the entire board and apply the update rules in steps.
66
+
67
+
### 13. Pathfinding Visualizations
68
+
Use Viron to define a navigable grid with start and goal positions. Track algorithm progress (A*, Dijkstra, etc.) in real time through environment updates.
69
+
70
+
### 14. City Simulation
71
+
Simulate a city with roads, zones, and agents (e.g., people, vehicles). Viron provides structure for tracking locations and interactions between entities.
72
+
73
+
---
74
+
75
+
## Installation
76
+
77
+
### Java (Maven)
78
+
79
+
```xml
80
+
<dependency>
81
+
<groupId>com.preponderous</groupId>
82
+
<artifactId>viron</artifactId>
83
+
<version>1.0.0</version>
84
+
</dependency>
47
85
```
48
86
49
-
The code coverage report will be generated in the `target/site/jacoco` directory. Open the `index.html` file in a web browser to view the report.
87
+
### Python
50
88
51
-
#### Python
52
-
To install the required dependencies, run the following command:
To generate a code coverage report, run the following commands:
109
+
---
110
+
111
+
## Testing
112
+
113
+
**Java:**
65
114
66
115
```bash
67
-
coverage run -m pytest
68
-
coverage report
116
+
mvn test
69
117
```
70
118
71
-
The code coverage report will be generated in the terminal.
119
+
**Python:**
120
+
121
+
```bash
122
+
pytest
123
+
```
72
124
73
-
### Postman
74
-
To test the API, you can use the Postman collection provided in the `postman` directory. This collection contains a number of requests that you can use to interact with the API. See the [README](postman/README.md) in the `postman` directory for more information.
125
+
---
75
126
76
127
## Deployment
77
128
### Starting the application
@@ -88,4 +139,18 @@ To stop the application, run the following command:
0 commit comments