Create account / Log in

VASSAL 4 model description

Discussion area for the development team.

Moderators: Tim M, uckelman

VASSAL 4 model description

Postby uckelman » July 16th, 2011, 2:25 pm

In what follows, I will describe my design for the model portion of VASSAL 4.

In a model-view architecture, the model holds data, while views provide displays of that data. (There's also the controller, which handles input and notifies the model of changes, but for present purposes, you can think of that as part of any view which responds to user input.)

Anything which is relevant for the game state---i.e., anything which you would need to record in order to set up the game again after tearing it down---is a datum which should be represented in the model. Game data are essentially bundles of properties: Pieces have names, locations, angles, sides which are up, and possibly ownership, visibility, etc. Maps are similar. There might also be some global properties which aren't attached to physical objects, which one might say are properties of the Game, e.g., which player's turn it is. Call things like pieces, maps, and the game as a whole "game objects".

Capabilities we need in the model:

* getting/setting properties on game objects: Without these, we can interact with the model.

* the ability to add/remove property change listeners to objects: When data changes in the model, we want to be able to react to those changes.

There are at least two kinds of thing I'm envisioning as being change listeners: Views, and Scripts.

Views need to be notified when properties change, as views are responsible for displaying those changes in some way. The GUI is a view for each game object that it will be displaying. If a piece's location changes, the GUI needs to be told that so it can update itself.

Scripts are something new, but are in some ways similar to triggers in V3. Suppose that we have a control marker, which, when flipped over, should cause another marker on a victory point track to be moved. This could be accomplished by having a change listener on the control marker's "visible face" property which then modifies the location of the marker on the victory point track.

A property change listener might be something which we'd like to have fire just before or just after a property is changed---hence, property change listeners can be pre- or post-change listeners. It might also prove useful to have a way of "freezing" game objects so that their properties can be changed without triggering any of their property change listeners, or to defer all listener notifications until after a particular listener has finished, in order to prevent loops or cascades.

In V3, a trait can cause an entry to show up in a piece's context menu, or make some hotkey active for that piece. I'd like to generalize this to what I'm calling Action objects. An Action is an object consisting of:

* a hierarchical key
* a keycode (opt)
* a short text (opt)
* a description text (opt)
* a script

Game objects can have Actions attached to them. The hierarchical key, the keycode, the short text, and description text are intended to have a particular interpretation in the standard GUI view, namely:

* the hierarchical key is a branch in a context menu
* the keycode specifies a hotkey for triggering the action
* the short text is for the text in a context menu
* the description text is for something like a tooltip or status bar

The script attached to an Action is what lets an Action have effect. For example, a piece which can be rotated by a hotkey would have an Action with the appropriately set keycode and a script which adjusts the Piece's angle.

The model needs to provide a way of retrieving game objects by property. For example, if I want a list of all of the Pieces which are on a particular Map, I should be able to retrieve this. This capability is needed in modules which have automation which applies to groups of pieces. E.g., the module for The Longest Day has a button which flips all fired artillery back to its unfired side.

(Implementation note: We do this in V3 by iterating over all pieces to find the ones which meet the given criteria, which is embarrassingly inefficient. We could instead do this in (amortized) constant time by keeping an index after the first query, and using change listeners to maintain that index thereafter.)

There isn't much more to the model than this. The model is for storing data and managing the relationships among game objects.

Comments?
User avatar
uckelman
Site Admin
 
Posts: 8140
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: VASSAL 4 model description

Postby bdgza » July 16th, 2011, 3:10 pm

I see Actions are again called by keycodes, like in the VASSAL 3 model. Will it be possible to call Actions from a Script by name, rather than by keycode? Can you have an Action attached to a game object that is not listed in the contextual menu?
bdgza
 
Posts: 290
Joined: February 26th, 2010, 10:51 am

Re: [messages] [Developers] Re: VASSAL 4 model description

Postby uckelman » July 16th, 2011, 3:36 pm

Thus spake bdgza:
> I see Actions are again called by keycodes, like in the VASSAL 3 module.
> Will it be possible to call Actions from a Script by name, rather than
> by keycode? Can you have an Action attached to a game object that is not
> listed in the contextual menu?
>

Keycodes are optional.

I was not intending to force all Actions to appear in context menus, so
in the implementation we would either have a special kind of hkey which
excludes them, or not have the hkey double as the Action name.

--
J.
User avatar
uckelman
Site Admin
 
Posts: 8140
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: [messages] Edit: [Developers] Re: VASSAL 4 model descrip

Postby uckelman » July 16th, 2011, 3:41 pm

Thus spake bdgza:
>
> Will it be possible to call Actions from a Script by name, rather than
> by keycode?

I intend for the scripts attached to actions be be callable by name. I'd
been thinking of Actions as the data manifestation of something the user
can do in a View. The "doing" goes with the attached script, not the
Action. Maybe this makes "Action" a poor choice of name.

--
J.
User avatar
uckelman
Site Admin
 
Posts: 8140
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: VASSAL 4 model description

Postby Brent Easton » July 18th, 2011, 12:36 am

Joel,

Could you gove some examples of what a Hierachical Key will look like. I can see several problems with your proposal, including bdgza's concerns, that might become clearer if I know what a hierachical key looks like.

Think about the case 2 different 'Actions' without keycodes that are to be triggered at the same time by the same user event. What will the hierachical keys look like? What binds them together? The NamedKeyStrokes I did for 3.2 are essentiall an 'Activation Id' that other 'Actions' (ie. traits) can look for and act on

I am also unsure about your scheme to index 'by property'. What you seem to be saying is to index the property values of each possible property, so there would be one index for each possible Vassal property. You would need a database query optimizer to use that to help with a search for something like 'CurrentMap ~= Veghel* and Strength < 5 and Will >= 12 and (hp == 2 or hp == 3)'
User avatar
Brent Easton
 
Posts: 2757
Joined: December 21st, 2007, 3:06 am
Location: Berry, NSW, Australia

Re: [messages] [Developers] Re: VASSAL 4 model description

Postby uckelman » July 18th, 2011, 12:14 pm

Thus spake swampwallaby:
> Joel,
>
> Could you gove some examples of what a Hierachical Key will look like. I
> can see several problems with your proposal, including bdgza's concerns,
> that might become clearer if I know what a hierachical key looks like.

I was expecting that an item appearing as Foo > Bar > Baz in a contex
menu would have a key that reflected that, something like '/Foo/Bar/Baz',
or, maybe the levels represented as a list, to avoid having to parse the
string each time.

On reflection, its not necessary that this key serve as both as a name
and a menu location. Those could be separated if it would be problematic
to have them together.

> Think about the case 2 different 'Actions' without keycodes that are to
> be triggered at the same time by the same user event. What will the
> hierachical keys look like? What binds them together? The
> NamedKeyStrokes I did for 3.2 are essentiall an 'Activation Id' that
> other 'Actions' (ie. traits) can look for and act on

I suspect that I've misunderstood what you're saying for this one.

What the hkeys look like would depend on where and in what menu the
associated Actions were to appear in.

It should never be the case that two Actions are triggered at the same
time, because the user can't input two separate key events simultaneously
on one keyboard or select two menu items simultaneously.

> I am also unsure about your scheme to index 'by property'. What you seem
> to be saying is to index the property values of each possible property,
> so there would be one index for each possible Vassal property. You would
> need a database query optimizer to use that to help with a search for
> something like 'CurrentMap ~= Veghel* and Strength < 5 and Will >= 12
> and (hp == 2 or hp == 3)'

What I'm proposing w/r/t indices is that when a particular search is
done for the first time, we cache the result and install change
listeners to keep that cached result current. I don't see why that would
require a query optimizer. Running the same query a second time should
result in returning the cached list, not doing another search.

Following your example: this would involve adding a change listener
which looks at the values of the four properties in your query, to be
added after the first time the search is done. Subsequently, whenever
any of these properties change, the change listener would add or remove
pieces from the cached index as appropriate.

I suspect that this is better than keeping sorted per-property lists for
every property---doing that would put us in need of a query optimizer of
some sort, as there's no obvious way to retrieve lists of pieces which
satisfy complex queries there---because it will have us keeping indices
only for the exact queries which are actually used.

--
J.
User avatar
uckelman
Site Admin
 
Posts: 8140
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: VASSAL 4 model description

Postby rami » July 19th, 2011, 11:21 am

After reading the above the following things came into my mind. They may be off-topic or currently irrelevant, but I'll just list them here. Ignore them at will. ;)

Please also note that I do not know inner workings of the current VASSAL engine, so these points may have been answered by earlier design.

- Actions with scripts. A good idea, but I think there can be two kinds of Actions / scripts. The ones that are launched via the UI by the user (like context menu actions) and the ones that react to the model change without the aid of the user (scripts attached to the model by the current module?). These two kinds of actions may have different places in MVC.

- Is there just one script attached to an action or can there be many? Is it possible to change/swap the script entry on runtime? Each script should also have an undo equivalent to be able to undo moves if necessary (Command design patter should be useful).

- The actual module design affects a great deal of the core Model design. How the modules are added to the system? As plug-ins? If as plugins then each plugin could provide its own additional menus etc. However,

- Currently the available modules vary from card games to dice games to strategy games or even RPGs(?). That is a wide variety of games. All having different types of data and core functionalities. How does the Model take care of all of this variance? How does a module add functionality to the model? Or is the model just a common data repository ? If the Model is expandable, how is it done? Does it, for example, wrap around an "engine" that provides a common interface for all game types? There could be a base engine that would be inherited by card game engine, board game engine etc. that could in turn be expanded by the module developer. The module would the pass the proper engine object to the Model upon initialization..

- Animation is one of my personal PITA. Should the game be able to show actions in animated manner (including the ability to see what the other user is pointing at the moment etc.)). If animation is included then it probably will affect the model in some way.

Sorry if this was off topic or just plain silly.
rami
 
Posts: 3
Joined: July 19th, 2011, 7:22 am

Re: [messages] [Developers] Re: VASSAL 4 model description

Postby uckelman » July 19th, 2011, 1:22 pm

Thus spake rami:
> After reading the above the following things came into my mind. They may
> be off-topic or currently irrelevant, but I'll just list them here.
> Ignore them at will. ;)
>
> Please also note that I do not know inner workings of the current VASSAL
> engine, so these points may have been answered by earlier design.
>
> - Actions with scripts. A good idea, but I think there can be two kinds
> of Actions / scripts. The ones that are launched via the UI by the user
> (like context menu actions) and the ones that react to the model change
> without the aid of the user (scripts attached to the model by the
> current module?). These two kinds of actions may have different places
> in MVC.

The latter kind of script---the kind not directly triggered by the user---
are either attached to property change listeners or called from other
scripts.

> - Is there just one script attached to an action or can there be many?

I was thinking "one", but I don't have a compelling reason for that.

> Is it possible to change/swap the script entry on runtime?

It should be, yes.

> Each script
> should also have an undo equivalent to be able to undo moves if
> necessary (Command design patter should be useful).

Yes. Would be neat if that could be generated automatically.

> - The actual module design affects a great deal of the core Model
> design. How the modules are added to the system? As plug-ins? If as
> plugins then each plugin could provide its own additional menus etc.
> However,
>
> - Currently the available modules vary from card games to dice games to
> strategy games or even RPGs(?). That is a wide variety of games. All
> having different types of data and core functionalities. How does the
> Model take care of all of this variance?

Every game object in a physical game is logically just a bundle of
properties. The model stores those. The functionality comes from the
scripts and Actions.

> - Animation is one of my personal PITA. Should the game be able to show
> actions in animated manner (including the ability to see what the other
> user is pointing at the moment etc.)). If animation is included then it
> probably will affect the model in some way.

I don't see how this would affect the Model. Things like animations and
the position of the cursor are in the domain of the GUI View. (I would
very much like to make it possible to see the other player's cursor,
though.)

> Sorry if this was off topic or just plain silly.

These are all good and useful questions.

--
J.
User avatar
uckelman
Site Admin
 
Posts: 8140
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: [messages] [Developers] Re: VASSAL 4 model description

Postby bdgza » July 19th, 2011, 1:36 pm

uckelman wrote:(I would
very much like to make it possible to see the other player's cursor,
though.)


I would think that to show the opponents cursor or not should be at least a property attached to player sides (to switch it on/off for games), so that Observers for example don't show their cursor, and certain games can always hide the cursor.
bdgza
 
Posts: 290
Joined: February 26th, 2010, 10:51 am

Re: [messages] [Developers] Re: [Developers] Re: VASSAL 4 mo

Postby uckelman » July 19th, 2011, 1:47 pm

Thus spake bdgza:
>
> "uckelman" wrote:
> > (I would
> > very much like to make it possible to see the other player's cursor,
> > though.)
>
>
> I would think that to show the opponents cursor or not should be at
> least a property attached to player sides (to switch it on/off for
> games), so that Observers for example don't show their cursor, and
> certain games can always hide the cursor.
>

Yes, but it should be a property of a View, not a propery of anything
in the Modle.

--
J.
User avatar
uckelman
Site Admin
 
Posts: 8140
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: [messages] [Developers] Re: [Developers] Re: VASSAL 4 mo

Postby bdgza » July 19th, 2011, 1:54 pm

uckelman wrote:Thus spake bdgza:
>
> "uckelman" wrote:
> > (I would
> > very much like to make it possible to see the other player's cursor,
> > though.)
>
>
> I would think that to show the opponents cursor or not should be at
> least a property attached to player sides (to switch it on/off for
> games), so that Observers for example don't show their cursor, and
> certain games can always hide the cursor.
>

Yes, but it should be a property of a View, not a propery of anything
in the Modle.

--
J.


Won't game modules have any say on the / way to influence views?
bdgza
 
Posts: 290
Joined: February 26th, 2010, 10:51 am

Re: [messages] [Developers] Re: [Developers] Re: [Developers

Postby uckelman » July 19th, 2011, 2:08 pm

Thus spake bdgza:
>
> > Yes, but it should be a property of a View, not a propery of anything
> > in the Modle.
>
> Won't game modules have any say on the / way to influence views?
>

My typo above is confusing. It should be "Model", not to be read as
"module". Does that clear up what I'm saying?

--
J.
User avatar
uckelman
Site Admin
 
Posts: 8140
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Re: [messages] [Developers] Re: [Developers] Re: [Developers

Postby Tim M » July 19th, 2011, 2:12 pm

uckelman wrote:Thus spake bdgza:
>
> > Yes, but it should be a property of a View, not a propery of anything
> > in the Modle.
>
> Won't game modules have any say on the / way to influence views?
>

My typo above is confusing. It should be "Model", not to be read as
"module". Does that clear up what I'm saying?

--
J.


phew! :lol:
Tim,
Vassal Uber Geek/Guru

Problems? post your OS, Physical Mem, version of Vassal and Java plus the Module in question.
No developer can help with out that info, thx!
User avatar
Tim M
 
Posts: 1777
Joined: December 8th, 2007, 12:22 pm
Location: Earth

Re: [messages] [Developers] Re: VASSAL 4 model description

Postby rami » July 19th, 2011, 9:35 pm

uckelman wrote:> - The actual module design affects a great deal of the core Model
> design. How the modules are added to the system? As plug-ins? If as
> plugins then each plugin could provide its own additional menus etc.
> However,
>
> - Currently the available modules vary from card games to dice games to
> strategy games or even RPGs(?). That is a wide variety of games. All
> having different types of data and core functionalities. How does the
> Model take care of all of this variance?

Every game object in a physical game is logically just a bundle of
properties. The model stores those. The functionality comes from the
scripts and Actions.


So Model in this case is just a repository for handling data with various properties and the actual game module offers (somehow) the game logic in form of scripts? It was bit confusing for me at first as I have always put the engine part in the Model so that the application control is in one single place.

uckelman wrote:> - Animation is one of my personal PITA. Should the game be able to show
> actions in animated manner (including the ability to see what the other
> user is pointing at the moment etc.)). If animation is included then it
> probably will affect the model in some way.

I don't see how this would affect the Model. Things like animations and
the position of the cursor are in the domain of the GUI View. (I would
very much like to make it possible to see the other player's cursor,
though.)


Sorry, I can't say what I was after with that one. :?


In VASSAL, when playing FtF, the other player is the master with the model and the other player is a slave? Or does both have their own models that are kept in sync? Or (very unlikely) is the model completely separated and shared between the clients on the server side?

--
Rami
rami
 
Posts: 3
Joined: July 19th, 2011, 7:22 am

Re: [messages] [Developers] Re: [Developers] Re: VASSAL 4 mo

Postby uckelman » July 20th, 2011, 10:51 am

Thus spake rami:
>
> So Model in this case is just a repository for handling data with
> various properties and the actual game module offers (somehow) the game
> logic in form of scripts? It was bit confusing for me at first as I have
> always put the engine part in the Model so that the application control
> is in one single place.
>

My reason for wanting this separation is to keep the purely
presentational aspects of games from being entangled with the logical
ones.

>
> In VASSAL, when playing FtF, the other player is the master with the
> model and the other player is a slave? Or does both have their own
> models that are kept in sync? Or (very unlikely) is the model completely
> separated and shared between the clients on the server side?
>

We could do any of those by having Views which supported the right
operations (such as querying a remote Model). I was supposing that each
user would have a Model locally, though, as rendering in the standard
GUI View will need to retrive quite a bit of information from the Model.

--
J.
User avatar
uckelman
Site Admin
 
Posts: 8140
Joined: December 10th, 2007, 9:48 am
Location: Durham, England

Next

Return to Developers

Who is online

Users browsing this forum: No registered users and 0 guests