From 2b8090a69ebfeb1b20854fe15c01abea10635fe9 Mon Sep 17 00:00:00 2001 From: DawnFire42 Date: Thu, 26 Feb 2026 15:53:29 -0500 Subject: [PATCH] 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 --- .../command_zone_architecture.md | 107 +++++++++++++++ .../developer_documentation/index.md | 4 +- .../formats/commander_format.md | 125 ++++++++++++++++++ .../extra-pages/user_documentation/index.md | 6 +- 4 files changed, 240 insertions(+), 2 deletions(-) create mode 100644 doc/doxygen/extra-pages/developer_documentation/command_zone_architecture.md create mode 100644 doc/doxygen/extra-pages/user_documentation/formats/commander_format.md diff --git a/doc/doxygen/extra-pages/developer_documentation/command_zone_architecture.md b/doc/doxygen/extra-pages/developer_documentation/command_zone_architecture.md new file mode 100644 index 000000000..9e14f3f30 --- /dev/null +++ b/doc/doxygen/extra-pages/developer_documentation/command_zone_architecture.md @@ -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 diff --git a/doc/doxygen/extra-pages/developer_documentation/index.md b/doc/doxygen/extra-pages/developer_documentation/index.md index da2d444d8..774ec5359 100644 --- a/doc/doxygen/extra-pages/developer_documentation/index.md +++ b/doc/doxygen/extra-pages/developer_documentation/index.md @@ -8,4 +8,6 @@ - @subpage querying_the_card_database - @subpage loading_card_pictures -- @subpage displaying_cards \ No newline at end of file +- @subpage displaying_cards + +- @subpage command_zone_architecture \ No newline at end of file diff --git a/doc/doxygen/extra-pages/user_documentation/formats/commander_format.md b/doc/doxygen/extra-pages/user_documentation/formats/commander_format.md new file mode 100644 index 000000000..5ba9e4b7a --- /dev/null +++ b/doc/doxygen/extra-pages/user_documentation/formats/commander_format.md @@ -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 diff --git a/doc/doxygen/extra-pages/user_documentation/index.md b/doc/doxygen/extra-pages/user_documentation/index.md index 3f10a0ac6..ff3b7912f 100644 --- a/doc/doxygen/extra-pages/user_documentation/index.md +++ b/doc/doxygen/extra-pages/user_documentation/index.md @@ -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