feat(command-zone): add foundational type definitions

Add core type definitions and constants for the command zone feature:

- zone_names.h: Add command zone name constants (command, partner,
  companion, background) for protocol and lookup operations
- command_zone_types.h: Define CommandZoneType enum, ZoneVisibility enum,
  and StateChangeResult struct for state machine logic
- counter_ids.h: Define shared counter IDs and names for commander tax
  tracking (IDs 8-9 reserved to avoid conflicts with user counters)

These headers are intentionally minimal and dependency-free to enable
inclusion in both production code and isolated unit tests.
This commit is contained in:
DawnFire42 2026-02-26 18:29:51 -05:00
parent e2d5c7438d
commit 3a92505c5e
3 changed files with 120 additions and 0 deletions

View file

@ -0,0 +1,87 @@
/**
* @file command_zone_types.h
* @ingroup GameGraphicsZones
* @brief Type definitions for command zone state management.
*
* This header is intentionally minimal and dependency-free so it can be
* included in both production code and isolated unit tests.
*/
#ifndef COCKATRICE_COMMAND_ZONE_TYPES_H
#define COCKATRICE_COMMAND_ZONE_TYPES_H
/**
* @enum CommandZoneType
* @brief Identifies the type of command zone.
*
* Each zone type has different behavior:
* - Primary: Always visible, never collapsible, has tax counter
* - Partner: Collapsible, has tax counter
* - Companion: Collapsible, no tax counter
* - Background: Collapsible, no tax counter
*/
enum class CommandZoneType
{
Primary, ///< Main commander - always visible, never collapsible
Partner, ///< Partner commander
Companion, ///< Companion
Background ///< Background
};
/**
* @enum ZoneVisibility
* @brief Represents the visual display state of a zone.
*/
enum class ZoneVisibility
{
Expanded, ///< Full height, cards visible
Minimized, ///< 25% height, cards clipped
Collapsed ///< Zero height, only toggle button visible (not valid for Primary)
};
/**
* @namespace CommandZoneConstants
* @brief Constants for command zone sizing.
*/
namespace CommandZoneConstants
{
constexpr double MINIMIZED_HEIGHT_RATIO = 0.25;
}
/**
* @brief Returns whether the given zone type supports multiple cards.
*
* Primary and Partner zones hold exactly one card (commander rules,
* tax counter positioning). Companion and Background zones support
* multiple cards to handle rare mechanics like multiple companions.
*
* @param type The command zone type to check
* @return true if the zone can hold multiple cards, false for single-card zones
*/
inline bool supportsMultipleCards(CommandZoneType type)
{
return type == CommandZoneType::Companion || type == CommandZoneType::Background;
}
/**
* @struct StateChangeResult
* @brief Result of a state mutation. Use the boolean flags to determine side effects;
* do not interpret visibility transitions directly (information hiding principle).
*/
struct StateChangeResult
{
bool geometryChanged; ///< Caller should call prepareGeometryChange() and update layout
bool shouldEmitExpanded; ///< Caller should emit expandedChanged(isExpanded())
bool shouldEmitMinimized; ///< Caller should emit minimizedChanged(isMinimized())
/**
* @brief Returns a result indicating no changes occurred.
* @return StateChangeResult with all flags false
*/
static StateChangeResult noChange()
{
return {false, false, false};
}
};
#endif // COCKATRICE_COMMAND_ZONE_TYPES_H

View file

@ -23,6 +23,10 @@ constexpr const char *HAND = "hand";
constexpr const char *DECK = "deck";
constexpr const char *SIDEBOARD = "sb";
constexpr const char *STACK = "stack";
constexpr const char *COMMAND = "command";
constexpr const char *PARTNER = "partner";
constexpr const char *COMPANION = "companion";
constexpr const char *BACKGROUND = "background";
} // namespace ZoneNames
#endif // ZONE_NAMES_H

View file

@ -0,0 +1,29 @@
#ifndef COUNTER_IDS_H
#define COUNTER_IDS_H
/**
* Shared counter IDs used by both client and server.
* These must match between server_player.cpp and player_event_handler.cpp.
*
* Reserved counter IDs for system counters:
* IDs 0-7: Standard player counters (life, mana colors, storm)
* IDs 8-9: Commander tax counters (reserved, do not use for custom counters)
* IDs 10+: Available for user-created counters
*
* The server's newCounterId() starts from the highest existing ID + 1,
* so these reserved IDs won't conflict as long as they're created first
* during setupZones().
*/
namespace CounterIds
{
constexpr int CommanderTax = 8;
constexpr int PartnerTax = 9;
} // namespace CounterIds
namespace CounterNames
{
constexpr const char *CommanderTax = "commander_tax_counter";
constexpr const char *PartnerTax = "partner_tax_counter";
} // namespace CounterNames
#endif // COUNTER_IDS_H