Need pointer to JAVA example or tutorial

Module Design
1

I would like to write an extension for my modules that on instantiation, would return one of 12 strings in the module to the log window. Bonus points if I can pass an int to the function to loop through it and return an array of strings to the log or one long string of how ever many strings I ask the module for.

MyJavaExtension(4)

Would return

“Engine room hit, primary gun hit, primary gun hit, hull hit”

Extra bonus is that on the selected ship I could deduct each hit from the appropriate dynamicProperty since each area of damage has a preset value that decrements as you play

2

Hi Matt,

Oracle - the owner of the Java platform - has a number of Java tutorials covering a lot of different topics.

Of course, these tutorials do not address the VASSAL Application Programming Interface (API) - you can find the documentation of that here. This is the API documentation and does not contain a tutorial.

That said, I’m not sure you are after is a tutorial on Java, nor the VASSAL API. Let me give a bit of context.

When VASSAL encounters an element in the module XML file, say

<Foo ...>
</Foo>

it will check to see if the Java class Foo is known or can be loaded from the module (or anywhere in the current class path, but that’s a detail). If so, it creates an object of that class (it instantiates an object - or instance - of the that class) passing appropriate parameters for the classes constructor. The Foo class could look like

class Foo 
{
    public Foo() {} 
    int _bar
}

in Java source code.

That object then exists as long as the module is loaded in the current Java virtual machine.

One can use this to make custom elements in the module, for example ObliqueHexGridNumbering creates a hex-number scheme which is oblique, unlike the VASSAL-provided more rectangular hex-number scheme.

What I think you are after, is really a tutorial on BeanShell. A general quick-start on BeanShell exists. The VASSAL BeanShell API is documented through the VASSAL Reference Manual.

For your specific question

I do not believe that it is easily possible to define a new BeanShell function from within a VASSAL module (I would love to know how myself). One could possible create a new element class, say BeanShellFunctionLibrary, which, on instantiation - i.e., when the module is loaded - get a hook to the BeanShell interpreter and add new functions to it.

So what I think you would like to do, is to create a prototype with appropriate DynamicProperty, Trigger, etc. traits. You can use a GlobalProperty to store the possible hits, and then by selecting (possibly at random), and an treat that as an array looking up the selected index. A Report trait can write your message to the chat. The prototype can then be added to any ship.

With the above suggested prototype you will get this more or less for free. Heck, you can even make the chat message contain the name of the ship.

Hope that helps.

Yours,
Christian

3

Christian. Thank you. Time to digest this now. I am going to try the new prototype route with the DynamicProperty, Trigger etc and see what I can get.

In the mean time my much more javaesque partner in Denmark thought it was a good idea and is building out a class to take care of all the gunnery and with very good results so far.

We are worried about how much to automate so that we don’t remove the fact that this is a wargame and not a computer game. The owner of the IP wants it to stay a dice rolling wargame. But we could drop out 50% or more of administration time so we shall see.

Thanks for the great explanation!

4

You’re welcome.

Suppose you have a Ship Prototype prototype.

  • That prototype has a Trigger trait reacting to some key command - say attacked.
    • This Trigger will in turn fire a Global Key trait that rolls a dice
    • Then a Dynamic Property that stores the die-roll result from Global Property 1d6_result
    • Then another Dynamic Property that calculates the results by cross indexes the die roll with the defensive strength of the ship (stored in a Mark trait). The result is whether the ship was hit or not and possible the damage inflicted.
  • A Report prototype that reports the result of the attack in the chat.

The trigger trait can be instigated through various means, such as a Global Key or the like.

You may want to take a look at some of my modules that implements a similar scheme, for example

The procedure implemented in these are all more or less the same

  • The player selects the attacking and defending units
  • Then the player initiates a global key - say declareBattle
    • This sends a command to a special hidden unit
      • The hidden unit clears global properties
      • It also increments the current battle counter
      • It then sends another global key command, say declareBattleNext
      • The global key command sends a command to selected units
        • The units add a battle marker on top of themselves and stores the battle number with it
        • The units updates attacking and defending factors (strength points), including terrain or feature bonuses and penalties
      • The hidden unit then calculates the battle “index” (look-up column in a CRT, or the combat differential)
      • The hidden unit then sends another global key - say declareBattleOdds
        • The global key sends a command to all selected units
          • The first defending unit that sees the command adds an odds marker on top of it self, and then deselects all units
  • The player may then right-click the odds marker (or use a global key) to resolve the battle
    • This then initiates a die-roll
    • The result of the die roll is cross indexed with the battle index in some way and the battle result is determined
    • The odds marker then replaces itself with a result marker
  • The player(s) must then implement the result (retreats, eliminations, advances, and so on).

Note that the automation part (odds, battle results) are optional and can be disabled by the player.

I think it will be hard to implement what you are after as Java extensions. Ideally, you would want to make a new trait, and that can be done through a custom CommandEncoder class, plus some other code to handle the trait(s), but your module becomes vulnerable to changes in the VASSAL API.

That said, I would love to see what you come up with. Please consider to make your Java source code available (in the module, via some code repository, or the like), which will also help with VASSAL API changes.

The above procedures implemented in some of my modules can be a bit tricky to do through the regular VASSAL editor GUI. I have therefore developed a Python module pywargame that can process a VASSAL module, or even create a new one from scratch. This allows one to encode the various look-ups, tables, etc. by code rather than to type them out in the VASSAL editor.

There are a great many thoughts and feelings about automation in VASSAL modules, ranging from

  • No automation at all - modules are truly virtual components

to

  • Make VASSAL a full game engine that can handle all rules of a game

Most modules are closer to the top end of the spectrum (though they may use card shuffling, die rolls, etc.) - as far as I can tell from my limited experience. No modules fall in the latter end of the spectrum since it is virtually impossible to implement in the current VASSAL engine.

In the modules mentioned above, I’ve implemented something that is probably closer to the latter category, but I made sure that most of the automation is optional. That is, players do not need to use the automation if they don’t want to.

Personally, I would love if VASSAL would give the possibility to implement more rules, but as I said above, it is virtually impossible with current VASSAL. The main problem is that the module does not know the state of the game - for example, which units are where.

As far as I can gather from the various posts, VASSAL version 4 will give that possibility, but with no public preview or code to look at, it is hard to gauge.

What I would do, if I were to implement something like VASSAL would be

  • Use a scripting language - e.g., Python
  • Each module creates a sub-class of the class Game
    • This sub-class will define the board(s), pieces, etc. but with out specifying any particular UI
      • The back-end makes and instance of the module supplied Game class in two variants
        • A master which will handle the state and the rules
        • A slave for each client (player) which specifies UI elements and will handle user interface requests and send requests (not just UI requests) to the master.

E.g.,

class Game(vassal.Game):
    def __init__(self,master):
         super(Game).init(master)

    def buildUI(self):
        if self._master:
            raise RuntimeException("I'm the master, cannot do that")
        ...

    def pieces(self):
        return { 'German 1st Army': German(identifier=1,
                                           echelon=Echelon.Army,
                                           type=Type.Infantry,
                                           cf=3,
                                           mf=4), 
                  'Soviet 3rd Corps': ... }

    def handleRequest(self,request):
        if 'movment' in self._phase.lower:
            return self.calculatePossibleMoves(request)
        ...

    def calculatePossibleMoves(self,request):
        pieces = request.pieces 
        locations = [piece.location() for piece in pieces]
        for piece, location in zip(pieces,locations):
            movePoints = piece.leastMovementPoints()
            ...

For example, a player selects a unit or stack during the Movement phase.

  • The back-end asks the user supplied Game class slave object to process the selection
    • The object sends a select during movement request to the master
    • The master calculates the possible moves of the unit or stack using for example and A* algorithm. This will entail knowing the state of the game. For example, a unit could be forced to stop on entering EZOC, moving into a forest hex costs more MF’s for certain types, and the possible moves would be limited by that. It also means that the user supplied Game class must know the rules of the game.
    • The master returns a possible moves reply to the slave
  • The slave asks the back-end to visualise the possible moves.

Begin Rant
(Caveat: I’m not a laywer, judge, or similar)

I assume by “owner of the IP” you refer to the copyright holder of the game in question. “Intellectual Property” is a rather vague term, as it covers

  • Copyright, governed by law and international conventions
  • Patents, also governed by law and some international conventions
  • Trademarks, also governed by law and some international conventions
  • Secrets, for which there are no regulations as far as I know

For games, and other similar products, there are a number of things to be aware of.

  • Trademarks: These can be enforced. That is, a trademark holder may say that you cannot use a trademark (name, logo, etc.) on your project that falls within the same category of utility. E.g., LEGO can prevent other toy manufactures from using the LEGO name and branding on their toys, up to and including statements such as “LEGO compatible”. Thus, a game developer of Battle of New York may claim a trademark on that name, and can oppose you from using that name on a VASSAL module. Trademarks need not be declared and never expire as long as they are in use.

  • Patents: A patent must be granted by a patent authority. Patents are granted to ideas that are sufficiently novel and of general interest to the public. Patents, including a description of the patented idea, are made public and are not secret. Patents do not prevent anyone else from implementing the idea, but the patent holder may seek compensation or injunction. Patents can generally be enforced through ligetation and expire after a set number of years. Patents are typically not granted for things like games (but for obvious things like the like-button), or game mechanics since novelty can be hard to show (note, Monopoly and Magick - The Gattering did have patents) - for example, one could not patent combat resolution via a Combat Resolution Table since there is plenty of prior art, and specific tables would probably fail to meet a non-obvious requirement.

  • Copyright: Copyright covers artistic and original forms of expression. Typically, the bar for artistic means that it is not something who is competent within the field could easily come up with. Originality means that it not done before. Note that it is only expressions that can be copyrighted - ideas cannot. Copyright is granted whether the author claims it or not. Unless the author grants specific permissions, or explicitly waives copyright, it is not permissible to use others copyrighted materials. Copyright expires typically after 75 years after the original authors death. For games, this means that

    • Mechanics of a game cannot be copyrighted - it is not an artistic expression
    • The graphics (exact boards, pieces, etc.) is copyrighted
    • The exact formulation of rules may be copyrighted if they are artistic expression.

    In short, a game developer cannot prevent others from implementing a game with the exact same mechanics as their game. They can prevent others from using the graphics and possibly verbatim copies of text.

  • Secrets: If some developer or the like has some internal documents (broadly understood), which they have not divulged to the public, and these gets stolen then that is just regular theft. If these internal documents enables the owner to produce some product, there’s no legal prevention for someone else to try to reverse-engineer those documents. The author may claim that their use license exclude people from doing so, in which case a clean-room implementation could do reverse-engineering. However, it is questionable. if even a non-clean-room implementation can legally be prevented by an end-user license. Note that patents are not really secrets and a prerequisite for obtaining a patent is to make it public.

For VASSAL module developers, this all means that

  • You can implement a module of game as long as
    • You either have permission to use the graphics material or you make your own
    • You either have permission to use verbatim copies of the text or you write your own
    • You have permission to use any claimed trademarks

(This is why I generally have re-written rules and made my own graphics for the various Print’n’Play and VASSAL module games I’ve made.)

For you that means that you can give a rat’s ar*e about what the game developer thinks about automation in VASSAL, as long as they do not prevent you from using any claimed trademark.

See also this thread on BGG or this

Both game and module developers as well as VASSAL moderators would do well to understand these issues.

  • A claim of “all rights reserved” does not prevent someone else from implementing a game. For example, Hasbro could implement MBT as long as they do not infringe trademarks, and use their own graphics and text.
  • Copyright only limits what you can do with original, artistic forms of expression. Without explicit permission (for example via a license) you cannot modify the copyrighted materials, even if you bought a copy. If you bought a copy of a book, you effectively bought a license to use that material, same for things like software. However, that does not entitle you to change nor copy that material. If you have a painting by Andy Warhol, you do not have permission to change that painting - Andy Warhol still has the copyright even if you own the only physical copy.

Of course everyone should act in good faith. It may be a good idea as a VASSAL module developer, even if not using copyrighted materials, to contact the game developer and ask if they have any objections. Heck, one might even gain some benefits through collaboration.

(I’ve personally withheld some Print’n’Play versions of games because game authors - who shall remain nameless - have asked me not to publish them after I contacted them - not that I was obliged to. For the things I do publish, I do so with an Creative Commons Attribution-ShareAlike license so that there’s no doubt what users may or may not do - they can do anything as long as they give credit and do so under the same license - e.g., some one is selling a copy of Port Stanley on eBay with a copy of my rules, which is fine - except perhaps that they put their own logo on it if they do not point that out - anyways a bad deal when you can get the whole thing for free).

End Rant

Again, you are welcome.

BTW, if you believe your problem has been solved, please close the topic by selecting the solution. That helps users of the forum to see what has a solution and the administrators become less anxious about too many open topics :slight_smile:

Yours,
Christian