mirror of
https://github.com/Cockatrice/Cockatrice.git
synced 2026-07-08 09:03:57 -07:00
docs(command-zone): add developer and user documentation
Add comprehensive documentation for the command zone feature. Developer documentation: - command_zone_architecture.md: detailed architecture overview - Layer separation (types, state, logic, graphics) - Component interactions and dependencies - Testing strategy and coverage - Index update to include new architecture doc User documentation: - commander_format.md: how to use Commander format in Cockatrice - Zone configuration options - Gameplay mechanics (commander tax, zone reveals) - Tips for Commander games - Index update to include new format doc
This commit is contained in:
parent
c2a10466db
commit
2b8090a69e
4 changed files with 240 additions and 2 deletions
|
|
@ -0,0 +1,107 @@
|
|||
@page command_zone_architecture Command Zone Architecture
|
||||
|
||||
The command zone feature implements Commander format support in Cockatrice,
|
||||
providing zones for commander cards with manual tax tracking.
|
||||
|
||||
# Architecture Overview
|
||||
|
||||
The command zone follows Cockatrice's logic/graphics separation pattern:
|
||||
|
||||
```
|
||||
┌───────────────────────────────────────────────────┐
|
||||
│ Graphics: CommandZone, ZoneToggleButton, │
|
||||
│ CommanderTaxCounter │
|
||||
└───────────────────────────────────────────────────┘
|
||||
│ signals/slots
|
||||
▼
|
||||
┌───────────────────────────────────────────────────┐
|
||||
│ Logic: CommandZoneLogic (card storage, positions) │
|
||||
└───────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
# Zone Types
|
||||
|
||||
| Zone | Name Constant | Purpose | Enablement |
|
||||
|------|---------------|---------|------------|
|
||||
| Primary | `ZoneNames::COMMAND` | Main commander, always visible | `enable_command_zone` |
|
||||
| Partner | `ZoneNames::PARTNER` | Partner commander, collapsible | `enable_command_zone` |
|
||||
| Companion | `ZoneNames::COMPANION` | Ikoria companion card | `enable_companion_zone` |
|
||||
| Background | `ZoneNames::BACKGROUND` | Baldur's Gate background | `enable_background_zone` |
|
||||
|
||||
All zones use the same `CommandZone` and `CommandZoneLogic` classes,
|
||||
differentiated by the `isPrimaryZone` flag. Primary and Partner zones are always
|
||||
created together when command zone is enabled. Companion and Background zones
|
||||
can be enabled independently via separate game creation options.
|
||||
|
||||
Primary and Partner zones hold a single card (commander rules, tax counter positioning); Companion and Background support multiple cards for edge cases. See `supportsMultipleCards()` in `command_zone_types.h`.
|
||||
|
||||
# Key Components
|
||||
|
||||
## CommandZoneLogic
|
||||
Manages the card list for a command zone. Overrides `addCardImpl()` to support
|
||||
positional insertion when cards are reordered via drag-and-drop.
|
||||
|
||||
@see CommandZoneLogic
|
||||
|
||||
## CommandZone
|
||||
Graphics layer handling rendering and input. Features:
|
||||
- Vertical card centering
|
||||
- Expand/collapse for partner zone
|
||||
- Minimize mode (25% height)
|
||||
- Drag-and-drop support
|
||||
|
||||
@see CommandZone
|
||||
|
||||
## CommanderTaxCounter
|
||||
Visual counter showing cumulative commander tax. Positioned at top-left of
|
||||
the zone. Players manually increment the counter when casting their commander.
|
||||
|
||||
@see CommanderTaxCounter
|
||||
|
||||
## ZoneToggleButton
|
||||
Small button at the seam between zones. Clicking toggles the sibling zone
|
||||
visibility. Used by the primary command zone to toggle the partner zone, and
|
||||
can be reused by any zone that needs to toggle a sibling.
|
||||
|
||||
@see ZoneToggleButton
|
||||
|
||||
# Common Modifications
|
||||
|
||||
## Adding a new zone property
|
||||
1. Add the property to `CommandZoneLogic`
|
||||
2. Emit a signal when the property changes
|
||||
3. Connect the signal in `CommandZone` to update visuals
|
||||
|
||||
## Changing zone appearance
|
||||
1. Modify `CommandZone::paint()` for background/border
|
||||
2. Modify `reorganizeCards()` for card layout
|
||||
3. Update `boundingRect()` if size changes
|
||||
|
||||
## Modifying tax behavior
|
||||
The tax counter value is managed by the server. To change tax logic:
|
||||
1. Server-side changes in `libcockatrice_network/libcockatrice/network/server/remote/game/server_player.cpp`
|
||||
2. Counter display changes in `CommanderTaxCounter`
|
||||
|
||||
# Menu Integration
|
||||
|
||||
The command zone context menus are managed by `PlayerMenu`:
|
||||
|
||||
| Menu | Zone | In Player Menu | Special Features |
|
||||
|------|------|----------------|------------------|
|
||||
| commandZoneMenu | Primary | Yes | View partner zone, partner toggle, tax counters for both |
|
||||
| partnerZoneMenu | Partner | No (zone right-click only) | Self-toggle, partner tax counter |
|
||||
| companionZoneMenu | Companion | Yes | Standard zone actions, no tax counter |
|
||||
| backgroundZoneMenu | Background | Yes | Standard zone actions, no tax counter |
|
||||
|
||||
The `commandZoneMenu` consolidates all commander-related actions including partner
|
||||
zone access ("View partner zone" action). The `partnerZoneMenu` is not added to
|
||||
the main player menu but remains attached to the partner zone itself for direct
|
||||
right-click access. This consolidation reduces menu clutter while maintaining
|
||||
full functionality.
|
||||
|
||||
All menus are created in the `PlayerMenu` constructor and attached to their zones
|
||||
in `setMenusForGraphicItems()`. Companion and Background zones have simpler
|
||||
menus without tax counter adjustments (these mechanics don't use commander tax).
|
||||
|
||||
@see CommandZoneMenu
|
||||
@see PlayerMenu
|
||||
Loading…
Add table
Add a link
Reference in a new issue