[messages] Edit: [Module Design] Re: Ownership Model

JustaBill martinson2005 at netscape.net
Tue Nov 8 13:14:15 MST 2011

[This message has been edited.]

Okay, let's start with this then.

__RfE: Piece Counters for Maps and Boards__

Each Map or Board can have a [Piece Counters] node (added via
right-click on the map or board node).
Each [Piece Counters] node could contain one _or more_ "Piece Counter"
components (again added via right-click).
Each "Piece Counter" would have the following attributes:

  * __Piece Counter Name__

  * __Visible to All Players:__ If not selected, visibility of counter
information reverts to visibility of the map or board (i.e., a private
window's counters could be hidden from opponents by leaving this
unchecked, but on the main map window the checkbox would be irrelevant
because that map is already publicly "owned").

  * __Matching Properties:__ The properties the piece must have to be
counted by this particular Piece Counter.  __Example:__ A board has one
Piece Counter called _Cosmic Cards_ with Matching Properties _Type =
Cosmic_, and another called _Reward Cards_ with Matching Properties
_Type = Reward_.  Each card contributes to the sum for the appropriate
counter based on its marker; cards that have _both_ markers are counted
by both counters.

  * __Property to Sum:__ This gives the module designer the freedom to
sum up either the _number_ of pieces or their _values_.  If blank, each
matching piece adds one to the counter's total regardless of its other
characteristics.  If not blank, the indicated property is used to
determine how much each matching piece contributes to the counter's
total (if the property's value can be interpreted as numeric). 
__Example:__ Some of the cards in the Red Hand private window represent
money in various denominations.  These kinds of cards have a marker of
type Dollars with a value of 1, 5, 10, or 20.  All other card types
(say, a bunch of Action cards) lack the Dollars marker (it is _not_
required that they define Dollars = 0).  Red Hand has a Piece Counter
called Wealth that has a Property to Sum of _Dollars_; this counter
maintains a running sum of the current amount of money in the Red Hand. 
The module designer could access this total using $Red Hand_Wealth$. 
Negative property values should be supported, and the counter's total
should be allowed to go negative.

  * __Hotkey to Refresh:__ If specified, pressing the hotkey will cause
the counter to be recalculated from scratch.  (In theory, this should
not be needed if the code to keep the counter updated is bulletproof,
but you never know when things might get out of synch because of
reloading a saved game from an old version or whatever.)

  * __Refresh Button Text__ / __Refresh Button Icon:__ If specified,
places a button on the map's toolbar to manually refresh the counter. 
(Should rarely be needed.)

  * __Include pieces in Decks:__ Checked by default. If unchecked,
pieces in decks are excluded from the total.

  * __Include pieces in Stacks:__ Checked by default. If unchecked,
pieces in stacks are excluded from the total.  (I'm not sure exactly how
stacks are managed and realize that it might not be practical to
implement this attribute.  I do not need it for my module, and included
it only for flexibility.  But I'm not really sure how often somebody
would even need to sum up only _unstacked_ pieces.)

  * __Report Format:__ A Message Format that, if supplied, will be
echoed to the Chat window whenever the piece counter's value changes. 
If multiple changes occur, only one message is echoed with the final

__Code behavior:__

  * Every Piece Counter automatically begins with a value of zero.  The
current value can be obtained using $MapName_PieceCounterName$ or
$BoardName_PieceCounterName$.  This value is read-only.

  * If the user sitting at the Vassal keyboard is not authorized to see
a particular piece counter (i.e., it is defined within a window that is
not available to his Side and it does not have its Visible to All
Players attribute checked), then $MapName_PieceCounterName$ or
$BoardName_PieceCounterName$ should probably return a blank or null.

  * For efficiency, piece counters are updated only when pieces
enter/leave the scope of the piece counter (or when their values change
if the piece counter has a Property to Sum).  Hopefully the code will
not zero and re-sum every piece counter in the module every time the
state of some piece changes.

  * When a piece enters a map or board (from somewhere other than that
map or board), all of that map's Piece Counter components that match the
piece are increased by 1 (or the piece's Property to Sum value).

  * When a piece leaves a map or board, all of that map's Piece Counter
components that match the piece are decreased by 1 (or the piece's
Property to Sum value).

  * Every possible activity that results in a piece entering or leaving
a map/board must be respected by the Piece Counters: drag and drop, Send
to Location, Return to Deck, Clone, Delete, Replace with Other,
instantiation of an at-start stack, loading a scenario, and everything
else I've missed!  Any action which alters the number (or value) of
matching pieces must increment/decrement the relevant counter(s)
appropriately.  Alternatively, _all_ Piece Counters can be brute-force
re-synched just before the players start playing, whenever a saved game
is loaded, etc.  However, for best performance, it would be ideal to
store and maintain the current values of all Piece Counters to avoid the
redundant calculations.

  * When any (numeric) Dynamic Property of a piece changes its value, if
that Dynamic Property is the Property to Sum for any relevant Piece
Counter, the difference between the DP's new value and old value is
added to every relevant Piece Counter.

  * The Matching Properties attribute should support as many properties
as possible, including such things as $OldBoard$.  This could (in
theory) be used to show the number of "newly added" pieces by having an
additional Piece Counter that includes in its matching properties
CurrentBoard != $OldBoard$ ... although I admit I can't certify the
viability of this example, since I have no idea how long the OldBoard
value persists for a given piece.  I assume that the first time a piece
is moved around _within_ the board it would lose its "new" status (since
OldBoard would now be the same as CurrentBoard), and of course if it
left the board it would no longer get counted.  That's the behavior I
would expect and want, anyway.  It seems like there is interesting
potential here.

It might also be helpful to support Piece Counters on _decks_.  In
Cosmic Encounter, for example, the discard pile is open information and
there are cards that access it in various ways.  Having an
auto-generated summary of the types and numbers of cards in the pile
could spare players from having to physically dig through the discards
just to determine whether it's worth playing such a card in the first
place, before having to dig through it again to get the card they want.

Read this topic online here:

More information about the messages mailing list