64 lines
3.8 KiB
Markdown
Executable File
64 lines
3.8 KiB
Markdown
Executable File
# Action Blocks – Developer Documentation
|
||
|
||
Action Blocks is an online player-vs-player falling-block game. Players clear lines to send garbage to each other. They also collect **items** hidden inside pieces and use them on a player of their choice.
|
||
|
||
The project consists of two deployable components:
|
||
|
||
| Component | Folder | Technology | Responsibility |
|
||
|---|---|---|---|
|
||
| Game server | `actionBlocks_server/` | C# / ASP.NET Core 10, SignalR | Runs all game logic, manages lobbies and players, pushes game state to clients |
|
||
| Website | `actionBlocks_website/` | React 19, TypeScript, Vite, CSS Modules, nginx | Renders the game, captures keyboard input, sends it to the server |
|
||
|
||
## Reading order
|
||
|
||
New to the project? Read these in order:
|
||
|
||
1. [Architecture](architecture.md): how the pieces fit together, and why the server is authoritative.
|
||
2. [Game rules](game-rules.md): what the game actually does, with all numbers.
|
||
3. [Server](server.md): a walkthrough of the C# code.
|
||
4. [Protocol](protocol.md): the SignalR API between website and server.
|
||
5. [Frontend](frontend.md): a walkthrough of the React code.
|
||
6. [Development](development.md): running, testing and debugging locally.
|
||
7. [Deployment](deployment.md): Docker, compose, reverse proxy and environment variables.
|
||
8. [Extending](extending.md): step-by-step guides for common changes (new item, new rule, new graphics, …).
|
||
|
||
## Repository layout
|
||
|
||
```
|
||
.
|
||
├── actionBlocks_server/ C# solution (game logic + web host + tests)
|
||
│ ├── src/ActionBlocks.Game/ Pure game logic library (no ASP.NET dependency)
|
||
│ ├── src/ActionBlocks.Server/ ASP.NET Core host: SignalR hub, lobbies, tick loop
|
||
│ ├── tests/ActionBlocks.Game.Tests/ xUnit tests for the game logic
|
||
│ └── Dockerfile
|
||
├── actionBlocks_website/ React frontend
|
||
│ ├── src/ Application code
|
||
│ ├── public/ Static files copied as-is (graphics, config.js)
|
||
│ ├── docker/ nginx config + container start script
|
||
│ └── Dockerfile
|
||
├── doc/ This documentation
|
||
├── docker-compose.yml Runs both containers
|
||
├── .env.example Template for deployment variables
|
||
├── instructions.md The original project brief
|
||
└── tetris_instructions/ Reference material for the base rules (saved web page)
|
||
```
|
||
|
||
## Glossary
|
||
|
||
| Term | Meaning |
|
||
|---|---|
|
||
| **Board / field** | The 10×20 grid of a player. Internally it has 20 extra hidden rows above (the *buffer*). |
|
||
| **Piece** | One of the 7 four-cell shapes (internally named I, J, L, O, S, Z, T). |
|
||
| **Mino** | One of the four cells of a piece. |
|
||
| **Active piece** | The piece currently falling and controlled by the player. |
|
||
| **Ghost** | Preview of where the active piece would land. In the UI it is called the "drop shadow". |
|
||
| **Hold** | Slot where a player can park one piece. It can be used once per piece. |
|
||
| **Garbage** | Gray lines with one hole that rise from the bottom. They are sent by opponents' line clears. |
|
||
| **Item** | A special ability attached to one mino of a piece. You collect it by clearing that mino's row. |
|
||
| **Target** | The player your items are used on. It is selected with the number keys. |
|
||
| **Snapshot** | The full match state the server pushes to all clients many times per second. |
|
||
| **Lobby** | A group of players sharing a 6-character code. It hosts consecutive matches. |
|
||
| **Match** | One round inside a lobby, from countdown to winner. |
|
||
|
||
> Naming note: the project intentionally avoids the trademarked name of the original game in all user-facing text and graphics. Internally, the standard single-letter piece names (I, J, L, …) are used because they are the common technical vocabulary.
|