marvin
1996b9c83e
Generate retro sound effects and music in the browser with the Web Audio API, so no audio files are needed. Any sound can still be replaced by a file. Audio (src/audio/): - 16 effects (move, rotate, hold, hard drop, lock, line clears, garbage, items, countdown, knockout, win/lose), triggered by comparing match snapshots, so the server is unchanged - Background music as a shuffled playlist of any number of tracks, either synth songs or audio files; 3 original songs included, tempo rises with the level - SoundPlayer interface, so the audio engine can be replaced - Audio files and music tracks are registered in theme/assets.ts (soundFiles, musicTracks) - All volume levels for developers are in config/sound.ts (master, sfx, music, per effect, per track, default slider positions) UI: - Speaker button fixed in the top right corner of every screen; opens an inline strip with a mute button and volume slider for SFX and music that doesn't cover the boards or pause the game - Leave button below it in the lobby and the game; in a running match it asks for a second click because leaving gives up the match - Lobby Music panel to switch single tracks on or off - Keys: M all sound on/off, B music on/off, N next track - Settings are saved in localStorage Docs: audio section in frontend.md, sound and music guide in extending.md, new keys in game-rules.md and the README.
79 lines
3.7 KiB
Markdown
79 lines
3.7 KiB
Markdown
# Action Blocks
|
|
|
|
Online player-vs-player falling-block game with items.
|
|
|
|
**Developer documentation:** see [`doc/`](doc/README.md) for architecture, game rules, protocol, frontend, deployment and how-to guides.
|
|
|
|
| Component | Path | Tech |
|
|
|---|---|---|
|
|
| Game server (logic, lobbies, players) | `actionBlocks_server/` | ASP.NET Core 10, SignalR |
|
|
| Website | `actionBlocks_website/` | React 19 + Vite + TypeScript, CSS Modules, served by nginx |
|
|
|
|
## Gameplay
|
|
|
|
- 10x20 field, hold, 5-piece preview, ghost piece, bag randomizer, wall kicks, 0.5 s lock delay (15 move resets).
|
|
- Garbage from line clears (attack table incl. spins, back-to-back, combos) goes to opponents in a **round-robin cycle**.
|
|
- 1 in 10 pieces carries an **item** inside one of its blocks. Clear the line containing that block to collect it (max 10, FIFO).
|
|
- **1-9** selects the item target (1 = you, 2.. = opponents in the order shown). **F** uses the first item on the target.
|
|
- You never see who targets you, but every opponent's items are shown beneath their mini field.
|
|
- Item names flash on top of the field they hit.
|
|
- Retro sound effects and a background music playlist, all synthesized in the browser. Any sound can be swapped for an audio file. The speaker button in the upper right corner opens volume sliders and mute buttons for effects and music. **M** mutes everything, **B** toggles the music, **N** skips the track.
|
|
|
|
Controls: arrows or WASD to move/rotate/soft drop, Space for hard drop, Z/Q/Ctrl to rotate left, C/Shift to hold.
|
|
|
|
## Local development
|
|
|
|
```bash
|
|
# server on :5080
|
|
cd actionBlocks_server && dotnet run --project src/ActionBlocks.Server --urls http://localhost:5080
|
|
dotnet test # game logic tests
|
|
|
|
# website on :5173, proxies /hub to the server
|
|
cd actionBlocks_website && npm install && npm run dev
|
|
```
|
|
|
|
## Deployment
|
|
|
|
```bash
|
|
docker network create actionBlocks_website # if not already created
|
|
docker network create actionBlocks_server
|
|
docker compose up -d --build
|
|
```
|
|
|
|
The website uses relative URLs. It works under a sub-path such as `/website/`, whether or not the proxy strips that prefix.
|
|
|
|
The reverse proxy (attached to both networks) should route:
|
|
|
|
- the site to `actionblocks-website:80`
|
|
- `/hub` to `actionblocks-server:8080`, with WebSocket upgrade headers forwarded
|
|
|
|
| Variable | Container | Purpose |
|
|
|---|---|---|
|
|
| `SERVER_URL` | website | Hub URL as seen by the browser. Empty means `<site origin>/hub`. Written into `config.js` at container start. |
|
|
| `ALLOWED_ORIGINS` | server | Comma-separated CORS origins. Empty allows any origin. |
|
|
| `HUB_PATH` | server | Hub endpoint path (default `/hub`). |
|
|
| `PATH_BASE` | server | Prefix to accept when the proxy forwards a sub-path unstripped, e.g. `/server`. |
|
|
| `Game__*` | server | Overrides any `GameSettings` value, e.g. `Game__ItemSpawnChance=0.2`. |
|
|
|
|
## Extending
|
|
|
|
**Adding an item**
|
|
|
|
1. Create a class implementing `IItem` in `actionBlocks_server/src/ActionBlocks.Game/Items/`.
|
|
2. Register it in `ItemRegistry.Default`.
|
|
3. Add an entry with the same id to `itemVisuals` in `actionBlocks_website/src/theme/assets.ts`, and add an icon in `public/assets/items/`.
|
|
|
|
**Changing rules**
|
|
|
|
- Values: `GameSettings`.
|
|
- Behaviour behind interfaces: `IRotationSystem`, `IRandomizer`, `IGarbageCalculator`, `IScoreCalculator`, `IGarbageTargeter`.
|
|
- The match flow lives in `Match`, and the per-player simulation in `PlayerGame`.
|
|
|
|
**Changing graphics**
|
|
|
|
- Every image path is in `src/theme/assets.ts`. You can set an image logo there with `uiAssets.logo`.
|
|
- Block colors are in `src/theme/colors.ts`.
|
|
- Block drawing style is in `src/render/draw.ts`.
|
|
- Key bindings are in `src/config/keybindings.ts`.
|
|
- Sound files and music tracks are registered in `src/theme/assets.ts` (`soundFiles`, `musicTracks`). All volume levels are in `src/config/sound.ts`.
|