142 lines
3.3 KiB
Markdown
142 lines
3.3 KiB
Markdown
# Peddlers of Ketran
|
|
|
|
This project consists of both the front-end React client and back-end Node.js game API server for the Settlers of Catan-style board game.
|
|
|
|
The application is designed to run inside Docker containers. Do not run `npm install` or modify `node_modules` locally, as this can create environment drift. All development and building should be done through the provided Docker workflows.
|
|
|
|
## Development and Production
|
|
|
|
The application can be launched in development or production mode by setting the `PRODUCTION` environment variable.
|
|
|
|
- Set `PRODUCTION=0` (or leave unset) for development mode: hot-reloading server and client.
|
|
- Set `PRODUCTION=1` for production mode: static built site served by the server.
|
|
|
|
### Prerequisites
|
|
|
|
- Docker
|
|
- Docker Compose
|
|
|
|
### Launching
|
|
|
|
```bash
|
|
# For development (hot-reload)
|
|
PRODUCTION=0 ./launch.sh
|
|
|
|
# For production (static build)
|
|
PRODUCTION=1 ./launch.sh
|
|
```
|
|
|
|
#### Development Mode
|
|
|
|
When `PRODUCTION=0`:
|
|
- Server runs with hot-reloading via `ts-node-dev` on port 8930
|
|
- Client runs with React hot module replacement on port 3001 (HTTPS)
|
|
- Client proxies API calls to the server
|
|
- Both services run in separate containers with mounted source directories
|
|
|
|
Open `https://localhost:3001` in your browser for the client. Changes to server or client code will trigger automatic reloads.
|
|
|
|
#### Production Mode
|
|
|
|
When `PRODUCTION=1`:
|
|
- Builds static client files and serves them directly from the Node.js server
|
|
- Server runs compiled TypeScript from `dist/` on port 8930
|
|
- No hot-reloading; requires rebuild for changes
|
|
- Database mounted for persistence
|
|
|
|
The application will be available at `http://localhost:8930`.
|
|
|
|
### Building (for Production)
|
|
|
|
If you need to manually build the production image:
|
|
|
|
```bash
|
|
docker-compose build
|
|
```
|
|
|
|
This builds the image with server and client dependencies installed and built.
|
|
|
|
### Environment Variables
|
|
|
|
Create a `.env` file in the project root with any required environment variables. The server start script loads these via `export $(cat ../.env | xargs)`.
|
|
|
|
## Architecture
|
|
|
|
```plantuml
|
|
skinparam componentStyle rectangle
|
|
|
|
component "Server" as server
|
|
component "Resources" as res
|
|
component "Client" as client
|
|
component "Game" as game
|
|
component "Player" as player
|
|
|
|
package "Game" as game {
|
|
component Players as players
|
|
}
|
|
|
|
server <-> resource : serves static files to client
|
|
client <-> server : API calls
|
|
player <-> client
|
|
players -r-> player
|
|
server -> game
|
|
```
|
|
|
|
## API Documentation
|
|
|
|
### POST /api/v1/game
|
|
|
|
#### Request
|
|
|
|
```json
|
|
{}
|
|
```
|
|
|
|
#### Response
|
|
|
|
```json
|
|
{
|
|
"gameId": "id",
|
|
"gameState": {
|
|
"tiles": []
|
|
}
|
|
}
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Add security tokens in `server/config/local.json`:
|
|
|
|
```bash
|
|
cat << EOF > server/config/local.json
|
|
{
|
|
"tokens": [ {
|
|
"$(whoami)": "$(< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c${1:-32};echo;)"
|
|
} ]
|
|
}
|
|
EOF
|
|
```
|
|
|
|
## Testing
|
|
|
|
### Create New Game
|
|
```bash
|
|
curl -X POST http://localhost:8930/api/v1/games/
|
|
```
|
|
|
|
### Get Game Status
|
|
```bash
|
|
curl -X GET http://localhost:8930/api/v1/games/:id
|
|
```
|
|
|
|
## Game States
|
|
|
|
- **Lobby**: Players register, choose colors, roll for position, set ready
|
|
- **Active**: Gameplay phase
|
|
|
|
Chat is available at all times for registered players.
|
|
|
|
## License Attribution
|
|
|
|
The dice faces (dice-six-faces-*.svg) are Copyright [https://delapouite.com/](https://delapouite.com/) and licensed as [CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/).
|