mirror of
https://github.com/Cockatrice/Cockatrice.git
synced 2026-07-07 05:53:59 -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:
DawnFire42
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
|
||||
|
|
@ -8,4 +8,6 @@
|
|||
- @subpage querying_the_card_database
|
||||
|
||||
- @subpage loading_card_pictures
|
||||
- @subpage displaying_cards
|
||||
- @subpage displaying_cards
|
||||
|
||||
- @subpage command_zone_architecture
|
||||
|
|
@ -0,0 +1,125 @@
|
|||
@page commander_format Commander Format Support
|
||||
|
||||
# Overview
|
||||
|
||||
Cockatrice provides dedicated support for the Commander (EDH) format, including specialized zones for managing your commander and partner commander cards.
|
||||
|
||||
## What is the Command Zone?
|
||||
|
||||
The Command Zone is a special area where your commander resides when not on the battlefield. In Cockatrice, this is represented as a dedicated zone that appears above the stack when playing Commander format games.
|
||||
|
||||
Key features:
|
||||
- **Primary Command Zone**: Holds your main commander card
|
||||
- **Partner Zone**: Expandable secondary zone for partner commanders
|
||||
- **Companion Zone**: Optional zone for Ikoria companion cards
|
||||
- **Background Zone**: Optional zone for Baldur's Gate background enchantments
|
||||
- **Commander Tax Counters**: Visual tracking of commander tax (the additional mana cost each time you cast your commander from the command zone)
|
||||
|
||||
## Enabling the Command Zone
|
||||
|
||||
The Command Zone automatically appears when the game server indicates you're playing a Commander format game. If you don't see the Command Zone, check that:
|
||||
1. The game room is configured for Commander format
|
||||
2. The server supports command zones
|
||||
|
||||
## Using the Command Zone
|
||||
|
||||
### Designating a Commander
|
||||
|
||||
To place a card in the Command Zone:
|
||||
1. Drag the card from your hand, library, or other zone to the Command Zone
|
||||
2. Primary and Partner zones accept one card each; Companion and Background zones can hold multiple cards (for edge-case mechanics like Rule 0 multiple companions)
|
||||
|
||||
### Zone States
|
||||
|
||||
All zones toggle between **full size** and **minimized (25% height)** via double-click. Tax counters remain visible when minimized.
|
||||
|
||||
### Partner Zone
|
||||
|
||||
Click the toggle button at the bottom of the Command Zone (or use the context menu) to expand/collapse the Partner Zone. It behaves identically to the primary zone with its own card display, minimize capability, and dedicated Partner Tax counter.
|
||||
|
||||
> **Note**: The Partner Zone will not collapse if it contains a card or has a tax counter value greater than 0. This prevents accidentally hiding important game state.
|
||||
|
||||
### Companion Zone
|
||||
|
||||
The Companion Zone is designed for the Ikoria companion mechanic:
|
||||
|
||||
**When to use**: If your deck includes a companion card (a creature that can start outside the game if your deck meets its restriction), place it in the Companion Zone.
|
||||
|
||||
**Enabling**: The Companion Zone must be enabled when creating the game (see Game Creation Options below).
|
||||
|
||||
**Features**:
|
||||
- Displays your companion card(s) publicly (supports multiple for Rule 0 edge cases)
|
||||
- No tax counter (companion mechanic doesn't use commander tax)
|
||||
- Collapsible to save screen space
|
||||
|
||||
### Background Zone
|
||||
|
||||
The Background Zone is designed for the Baldur's Gate "Choose a Background" mechanic:
|
||||
|
||||
**When to use**: If your commander has "Choose a Background" (like many commanders from Commander Legends: Battle for Baldur's Gate), place your background enchantment in this zone.
|
||||
|
||||
**Enabling**: The Background Zone must be enabled when creating the game (see Game Creation Options below).
|
||||
|
||||
**Features**:
|
||||
- Displays your background enchantment(s) publicly (supports multiple for edge cases)
|
||||
- No tax counter (backgrounds don't have commander tax)
|
||||
- Collapsible to save screen space
|
||||
|
||||
## Commander Tax Tracking
|
||||
|
||||
Cockatrice tracks commander tax with dedicated counters:
|
||||
|
||||
- **Commander Tax Counter**: Appears in the top-left of the Command Zone
|
||||
- **Partner Tax Counter**: Appears in the top-left of the Partner Zone (when expanded)
|
||||
|
||||
### Adjusting Tax Counters
|
||||
|
||||
Using the context menu (right-click on the zone):
|
||||
- "Increase Commander Tax Counter (+1)" - Increments the tax by 1
|
||||
- "Decrease Commander Tax Counter (-1)" - Decrements the tax by 1
|
||||
|
||||
Tax counters track the number of times your commander has been cast during the game.
|
||||
|
||||
## Context Menu Options
|
||||
|
||||
The battlefield's "Commander" submenu provides consolidated access to all zone actions: view zones, adjust tax counters (+1/-1), and toggle partner/companion/background zones. Right-clicking directly on a zone shows zone-specific options (view, tax counter for Primary/Partner, toggle, minimize).
|
||||
|
||||
## UI Summary
|
||||
|
||||
| Element | Location | Action |
|
||||
|---------|----------|--------|
|
||||
| Command Zone | Above the stack | Holds primary commander |
|
||||
| Partner Zone | Below Command Zone (when expanded) | Holds partner commander |
|
||||
| Companion Zone | Below Partner Zone (when enabled) | Holds companion card(s) |
|
||||
| Background Zone | Below Companion Zone (when enabled) | Holds background enchantment(s) |
|
||||
| Toggle Button | Bottom of Command Zone | Click to expand/collapse Partner Zone |
|
||||
| Tax Counter | Top-left of Primary/Partner zones | Shows current commander tax |
|
||||
| Minimize | Zone background | Double-click to toggle 25% height mode |
|
||||
|
||||
## Game Creation Options
|
||||
|
||||
When creating a game, you can configure which zones are available:
|
||||
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| Enable Command Zone | Unchecked | Enables commander and partner zones with tax counters |
|
||||
| Enable Companion Zone | Unchecked | Enables the Companion Zone for Ikoria companion mechanic |
|
||||
| Enable Background Zone | Unchecked | Enables the Background Zone for Baldur's Gate backgrounds |
|
||||
|
||||
All three options are independent checkboxes. You can enable any combination:
|
||||
- **Command Zone only**: Standard Commander/EDH gameplay
|
||||
- **Companion Zone only**: Use companion cards in any format
|
||||
- **Background Zone only**: Use backgrounds without commander zones
|
||||
- **Any combination**: Mix and match as your game requires
|
||||
|
||||
**Defaults for new games**: All zone options default to unchecked. Your preferences are saved for future games when "Remember settings" is enabled.
|
||||
|
||||
## Tips
|
||||
|
||||
- Tax counters are persistent throughout the game and visible to all players
|
||||
- Cards in the Command Zone are visible to all players (public information)
|
||||
|
||||
## See Also
|
||||
|
||||
- @ref creating_decks - How to create and edit decks
|
||||
- @ref editing_decks - Detailed deck editing guide
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
@page user_reference User Reference
|
||||
|
||||
|
||||
## Deck Management
|
||||
|
||||
- @subpage creating_decks
|
||||
|
|
@ -7,6 +7,10 @@
|
|||
- @subpage editing_decks
|
||||
- @subpage exporting_decks
|
||||
|
||||
## Game Formats
|
||||
|
||||
- @subpage commander_format
|
||||
|
||||
## Release Channels
|
||||
|
||||
- @subpage beta_release
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue