https://github.com/ifimust/room_generator
Room generator service for 2D game levels
https://github.com/ifimust/room_generator
flask google-app-engine microservice numpy procedural-generation python
Last synced: about 1 month ago
JSON representation
Room generator service for 2D game levels
- Host: GitHub
- URL: https://github.com/ifimust/room_generator
- Owner: ifIMust
- Created: 2024-07-08T22:56:23.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-09-21T17:35:13.000Z (9 months ago)
- Last Synced: 2025-09-21T17:42:54.067Z (9 months ago)
- Topics: flask, google-app-engine, microservice, numpy, procedural-generation, python
- Language: Python
- Homepage:
- Size: 22.2 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# room_generator
## Description
room_generator is a service that generates 2D "rooms" in JSON format.
This is useful for e.g. procedural roguelike/dungeon games if the rooms are aggregated into a larger level.
It is intended for use with [level_generator](https://github.com/ifIMust/level_generator) (not yet released).
Depending on request criteria, it may create a rectangle, circle, or ellipse shape.
Walls have closed diagonals.
room_generator can be deployed to Google App Engine or run locally.
## Usage
To generate a room with height 11 and width 7, GET `/?h=11&w=7`.
### Parameters
- `h` and `w` have a minimum size of 3 and default of 3.
- `v` enables void tiles for circles and ellipses (default false). Use `?v=true` or `?v=1`.
- `type` explicitly requests a room shape: `rectangle`, `circle`, or `ellipse` (case insensitive). If not provided, the shape is automatically selected based on dimensions.
### Shape Requirements
When using explicit `type` requests, dimensions must meet specific requirements:
- **Rectangle**: Any `h >= 3` and `w >= 3`
- **Circle**: Must have `h == w`, both odd numbers, and `>= 5` (minimum 5x5)
- **Ellipse**: Both `h` and `w` must be odd numbers and `>= 5`
Invalid dimension combinations return HTTP 400 error.
The output format is a JSON document describing the room. Each nested list in `data` represents a row.
0 is floor, 1 is wall, 127 is void (used for circle/ellipse backgrounds).
### Examples
If a local server is running on port 4949:
**Basic rectangle:** `http://localhost:4949/?h=3&w=4` yields (when pretty-printed):
```
{
"data": [
[1, 1, 1, 1],
[1, 0, 0, 1],
[1, 1, 1, 1]
],
"shape": [3, 4],
"style": "rectangle"
}
```
**Explicit circle:** `http://localhost:4949/?h=7&w=7&type=circle` creates a 7x7 circle.
**Explicit ellipse with void tiles:** `http://localhost:4949/?h=7&w=9&type=ellipse&v=true` creates a 7x9 ellipse with void tiles in corners.
## Running a local instance
### System Dependencies
First install the required system packages:
**Fedora/RHEL/CentOS:**
```
sudo dnf install python3-devel
```
**Ubuntu/Debian:**
```
sudo apt-get install python3-dev
```
### Setup
In the room_generator project directory, create and set up the venv environment:
```
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
```
Using gunicorn:
```
gunicorn -b :8000 'room_generator:create_app()'
```
Using the debug server:
```
flask --app room_generator run --port 4949
```
Using waitress:
```
waitress-serve --host 127.0.0.1 --port 4949 --call room_generator:create_app
```
## Testing
### Running Tests
To run all tests:
```
pytest
```
To run specific test files:
```
pytest tests/test_api.py
pytest tests/test_rectangle.py
```
### Test Coverage
Run tests with coverage analysis:
```
pytest --cov=room_generator --cov-report=term-missing
```
Generate an HTML coverage report:
```
pytest --cov=room_generator --cov-report=html
```
The HTML report will be generated in the `htmlcov/` directory. Open `htmlcov/index.html` in a web browser to view detailed coverage information.
### Code Quality
Run the linter to check code style:
```
flake8 room_generator tests
```
## Architecture Notes
### Code Organization
- **Unified Interface**: All generators use `generate_X(height, width, void=False)` signature
- **Internal Validation**: Each shape module validates its own requirements and raises ValueError for invalid inputs
- **Dispatch Pattern**: API uses single entry point with try/catch error handling
- **Auto-selection**: Automatic shape choice based on dimensions when no explicit type given
### Adding New Room Types
1. Create new module with `generate_X(height, width, void=False)` function that validates internally
2. Add to dispatch table in `room_generator/__init__.py`
3. Add comprehensive tests covering valid/invalid cases
4. Update documentation