jeirmeister/Cockatrice
1
0
Fork 0
mirror of https://github.com/Cockatrice/Cockatrice.git synced 2026-11-13 05:20:00 -08:00
Code Issues Projects Releases Packages Wiki Activity Actions 4
Cockatrice/doc/continuumatrice-match-essence.md

5.5 KiB
Raw Blame History

Match Essence pools (Continuum Universes CCG)

Continuumatrice matches provide 16 independent Essence balances per player, using the canonical sequence:

M S O G E A Q C J B R L V T P N

J is Jasper; N is colorless. These are not Magic mana colors, and Essence is not primarily obtained by drawing land cards.

Behavior

The client displays a compact 4 × 4 Essence Pool in a reserved column beside each player's battlefield. The panel shows the user's installed icons/essence/<code>.svg artwork and the current quantity, including zero.

  • Left-click: add one Essence of that type (gain).
  • Right-click: remove one Essence of that type (spend), when the balance is positive.
  • Shift + left-click: set an exact nonnegative balance through a number dialog.
  • Other players and spectators can view the balances; only the player controlling the pool (or a judge) can modify it.

For example, generating three Jasper Essence from a card ability currently means clicking J three times or setting its balance. Likewise, paying two Jasper means decrementing its balance twice. Future automated card effects should call a validated resource transaction action rather than simulating mouse clicks.

What this change does not assume

It does not invent Essence generation rules, a land-based resource curve, turn-based Essence resets, automatic cost deduction, overdraft/Essence debt, or activation triggers. The core match tracks available resources, but gameplay effects are still manual. Define those rules separately before implementing them.

Server-authoritative state

The existing Cockatrice-derived counter protocol already supports all the required functionality. The fork's shared EssenceCounter helper (libcockatrice_utility/libcockatrice/utility/essence_counter.h) defines stable counter names and the canonical symbol order.

The server creates sixteen counters at game setup with IDs 1..16 and names essence:M, essence:S, ..., essence:N. The existing life counter retains ID 0. These names are protocol/storage identifiers; client gameplay displays the corresponding Essence symbols rather than exposing raw IDs.

Resource counters:

  • Start at 0, independently for every player.
  • Cannot go below 0 (validated by the server for increment and set commands).
  • Cannot be deleted or created a second time via the generic counter commands.
  • Are serialized to client snapshots, replay events, and reconnect state by the existing counter protocol.
  • Do not live on card ScriptableObjects, card metadata/XML, or a global static client singleton.

Server_Player implements this for both the self-hosted Continuum-Servatrice and the embedded/local game server because they share the same player server code. Both client and server must use a matching Continuumatrice build. The regular MTG Cockatrice client/server do not provide the native Essence Pool display.

Implementation map

File Responsibility
libcockatrice_utility/libcockatrice/utility/essence_counter.h Canonical Essence order, protocol names, nonnegative values
libcockatrice_card/libcockatrice/card/essence_types.h Card-cost parser uses the same source of symbols
libcockatrice_network/libcockatrice/network/server/remote/game/server_player.cpp Server counter initialization, updates, permanent-counter restrictions
cockatrice/src/game_graphics/player/essence_pool_item.h/.cpp Compact graphical resource display, manual controls, server-state observation
cockatrice/src/game_graphics/player/player_graphics_item.cpp Places Essence pool beside player's board and excludes it from the narrow ordinary-counter stack
tests/essence_types_test.cpp Protocol-name round trips and nonnegative value utility checks

The panel never owns the true resource quantities. It listens for CounterState::valueChanged and sends normal actIncrementCounter/actSetCounter commands through PlayerActions. Only the server authoritatively changes the stored balance, so remote clients and replays see the same values.

Build and tests

On the feature/continuumatrice-essence-match-pools branch:

cmake -S . -B build -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DWITH_CLIENT=ON -DWITH_SERVER=ON -DWITH_ORACLE=OFF -DTEST=ON

cmake --build build --target continuumatrice continuum-servatrice essence_types_test --parallel 16

ctest --test-dir build -R EssenceTypesTest --output-on-failure

./build/continuumatrice/continuumatrice

Functional acceptance checklist

  • In a new local game, each player has a 4×4 pool with exactly 16 Essence types and zero balances.
  • Gaining J leaves C, B, and N unchanged; right-clicking J at zero cannot make it negative.
  • Shift+left can set N (colorless) to a specific nonnegative amount.
  • The normal life counter still works; no default MTG W/U/B/R/G/X/Storm counters appear.
  • Both players see the same balance after a command is processed by the server.
  • A spectator can view but not modify another player's Essence.
  • Disconnect/reconnect restores all 16 values from the game-state snapshot.
  • Replay playback restores previously recorded Essence changes.
  • A remote game running Continuum-Servatrice matches the local game behavior.
  • The Essence panel does not overlap the three battlefield bands or Limbo/Refuge/Oblivion piles at normal zoom.

Current status: Source implementation committed. This server/client change has not been compiled or tested in a live match yet. The new browser and match UI need user-side smoke testing.