VassalModule

> == Preface ==
> **A new version of the piecepack module and a TON of new extensions has been released! See the progress on the bottom of this page. Please add any bugs or feature requests.**
> **Note:** This documentation is still a work in progress. --- JonathanDietrich
> **IMPORTANT:** Latest version can be found on its [http://www.vassalengine.org/community/index.php?option=com_vassal_modules&task=display&module_id=123&page=Files vassal page].
> <toc>
> == Introduction ==
> == Vassal ==
> VASSAL is an engine for building and playing Internet-capable versions of turn-based, human-vs-human games. Players move and manipulate game pieces via the mouse and keyboard shortcuts while typing accompanying text. Moves can be recorded into a log file and stepped through one at a time for email play. During live Internet play, all moves and text are automatically broadcast to other players in real time. Combining a live VASSAL session with a third-party Internet voice-chat tool (such as NetMeeting or TeamSpeak) allows you to play with people around the world at very close to face-to-face pace.
> === Where to Get It ===
> You can get the vassal engine at [http://Vassalengine.org vassalengine.org].
> === How to Use It ===
> Please read the [http://vassalengine.org/UsersGuide/index.htm Vassal User's Guide] before trying to use the program or the piecepack module. The guide explains how to install Vassal, and its basic functions. Information found there will not be duplicated in this documentation.
> == Piecepack Module ==
> This is the core piecepack module. It contains all you need to be able to play most 1-8 player games that require 1 or 2 identical piecepacks and or the card suits. The graphics are all based off of the JcdPiecepack set, but with some differences, including some colour! Also included in the main modules are some coloured //gems// which can be used as counters or additional pieces, post-it style notes for keeping information on the table, and a bunch of different playing boards.
> === Where to Get It ===
> [http://www.vassalengine.org/community/index.php?option=com_vassal_modules&task=display&module_id=123&page=Files Download the latest version]. On that page you may find two types of downloads: a big packaged zip, and smaller update files. For now, just grab the big packaged zip (the description should say it includes a bunch of stuff). This zip file is important, because it will also create the correct directory needed for all of the fancy features found in the extensions.
> Unzip this zip file somewhere. I suggest creating a modules directory inside of your VASSAL directory, and putting the contents of the zip file in there.
> Later, you may find that updates to specific extensions or brand new extensions are made available on that same page. You can download these and then add them to your piecepack installation.
> === How to Use It ===
> Once you have the vassal engine installed, you can start it. Choose {{{Play Module}}} and then select the piecepack module that you downloaded. The piecepack module should now be loaded and you are ready to go.
> This section is only going to cover the piecepack specific functionality. To find out how to log on to the server and play games against others online, please read the [http://vassalengine.org/UsersGuide/index.htm Vassal User's Guide]. It would be a good idea to open follow along as you read this, as it should help make things clear.
> ==== Starting Off ====
> To start a game, choose {{{File -> New Game}}}.
> This will prompt you to choose a side to join. The default option is <observer> which should only be used if you are observing other play. Choose a team, labelled Team A through Team H (that's 8 different teams if you are counting.)
> Now you will be asked to select a board. The standard piecepack module comes with a bunch including //Table Top//, //Table Top (No Grid)//, and 2 different chess boards. Future extensions may add additional boards. Select a board that is most appropriate for the game you intend to play and click {{{Ok}}}.
> You are now ready to start playing a game. You will now drag various pieces onto the game board to set up the starting conditions for your game. Once ready you can start playing.
> **Hint:** You can use the {{{File -> Save Game}}} to save your game before you start playing but after you have it set up. This will allow you to jump right in the next time you want to play.
> ==== The Tool bar ====
> The section running just under the menu is known as the tool bar. It contains an array of various buttons. Some of these buttons are built into the vassal engine, and others are created by the piecepack module or its extensions. When ever a button in the tool bar is referenced it will appear in this notation ({{{Tool bar -> button name}}}). Some of the buttons are graphical and so the {{{button name}}} may not appear as text, but it shouldn't be too hard to figure it out.
> ==== The Piece Pallet ====
> Some of the pieces can be found in the piece pallet. You can open it by clicking the Pieces button ({{{Tool bar -> Pieces}}}). Once the piece pallet is open, you can choose the section from the drop down list and then subsection from the right hand pane. This process will be indicated in the descriptions below using the following notation ({{{Pieces -> section -> subsection }}}). The pieces will then appear in the left pane. Pieces in the piece pallet can be dragged from the left pane and onto the board.
> ==== Right click ====
> Most, if not all, of the pieces have commands associated with them such as rotate or flip. In order to access these commands, right click on the piece and then choose the option. You will notice that some of the commands also have keyboard shortcuts listed after their title in the menu. These shortcuts will allow you quick access to the commands without having to right click first.
> ==== The Floating Deck ====
> Many games require that you draw a random tile or coin. In order to facilitate this the piecepack module uses a separate window to hold a couple of //decks//. This window can be opened or closed with {{{Tool bar -> Deck}}}. This window has four areas marked on it.
> The top two act like decks of cards. These are marked with black outlines and are entitled //Random Tiles// and //Random Coins//. Piles of pieces get placed in these spots, then when you drag a piece off of it, you get a random piece.
> These decks have the following options available in the //right-click// menu:
> * Draw multiple cards: allows you to draw multiple items from the deck
> * Face up / Face down: (only on //Random Coin// deck) turn all of the contents over
> The bottom two act like discard piles. They have red outlines and are entitled //Discard Tiles// and //Discard Coins//. This is where tiles and coins when they are //discarded// from the board.
> These decks have the following options available in the //right-click// menu:
> * Shuffle : shuffle the deck, leaving the pieces here.
> * Re-Shuffle: shuffle the cards back into the corresponding draw deck.
> * Face up / Face down:(only on //Random Coin// deck) turn all of the contents over
> * Reverse order: reverse the order of the contents of the deck
> * Draw multiple cards: allows you to draw multiple items from the deck
> * Draw specific cards : allows you to select specific items from the deck to be removed
> ==== The Pieces ====
> Description of where to find and how to use all of the pieces.
> ===== Pawns =====
> This module uses the star coins found in the JcdPiecepack as pawns. They are directional and have two states (ie can be flipped) They can be found in the piece pallet ({{{Pieces -> piecepack -> pawns}}}).
> Pawns have the following options available in the //right-click// menu:
>
> * Rotate CW (Ctrl + ]): Rotates the piece 45 degrees clock-wise.
> * Rotate CCW (Ctrl + [): Rotates the piece 45 degrees counter clock-wise.
> * Flip (Ctrl + F): flips this piece over
> * Delete (Ctrl + X) : delete this piece
> ===== Dice =====
> If a game requires you roll any of the piecepack dice, you can do so by clicking one of the dice buttons in the tool bar ({{{Tool bar -> dice button}}}) There are currently 4 such dice buttons: the four standard suit dice, the expanded suit dice, a standard suit selector die, and an expanded suit selector die. Clicking on one of the buttons will roll all of the dice depicted on the button. The faces of the dice will change to show the result, as well the results will be logged in the chat screen.
> If a game requires you to use the dice as pawns, or it is necessary to keep certain information stored on a die for future reference, you will have to use the dice found in the piece pallet ({{{Pieces -> piecepack -> dice}}}). These dice function as pieces and can be dragged on to the board just like any other piece in the pallet.
> Dice (on the board) have the following options available in the //right-click// menu:
> * Clone (Ctrl + C) : make a copy of this piece
> * Delete (Ctrl + X) : delete this piece
> * Rotate CW (Ctrl + ]): Rotates the piece 45 degrees clock-wise.
> * Rotate CCW (Ctrl + [): Rotates the piece 45 degrees counter clock-wise.
> * Increase (Ctrl + .): Changes the face of the die to the next higher value (looping from 5 to Null).
> * Decrease (Ctrl + ,): Changes the face of the die to the next lower value (looping from Null to 5).
> **Note:** The functionality of the dice unfortunately had to be split up. Although most games created for the vassal engine only require dice to generate a random event and do not function as possible pieces themselves, this is not true of the piecepack. Support for "unified" dice is therefore currently not possible but a feature request has been made, and it may one day be possible.
> ===== Tiles & Coins =====
> The tiles & coins can be found in the Tiles & Coins window which can be opened with {{{Toolbar -> T&C}}}. A second set of the basic tiles & coins are available in {{{Toolbar -> T&C (2nd)}}}. The expanded suit tiles & coins are in {{{Toolbar -> T&C (exp)}}}.
> When you start the piecepack module, the tiles & coins have been separated out into their suits. This makes it easier to grab sub-sets of tiles or coins. As well the piles (//decks// in vassal terminology) have some features that make it easy to get just the the tiles you want.
> Initial tile decks have the following options available in the //right-click// menu:
> * Shuffle : shuffle the deck
> * Send to Floating Deck : send the contents of this deck to the floating deck (see above)
> * Face up / Face down: turn all of the contents over
> * Reverse order: reverse the order of the contents of the deck
> * Draw multiple cards: allows you to draw multiple items from the deck
> * Draw specific cards : allows you to select specific items from the deck to be removed
> Tiles & coins themselves have the following options available in the //right-click// menu:
> * Discard to Floating Deck: sends this piece to the floating deck (see above)
> * Rotate CW (Ctrl + ]): Rotates the piece 45 degrees clock-wise.
> * Rotate CCW (Ctrl + [): Rotates the piece 45 degrees counter clock-wise.
> * Flip (Ctrl + F): flips this piece over
> * Peek (Ctrl + P): peeks at the piece, allowing you to see the other side, but not your opponents
> ===== Gems =====
> These are very simple pieces very much like the glass stones or gems you might find in some games. You can find them in the piece pallet ({{{Pieces -> miscellaneous -> gems}}}).
> Gems have the following options available in the //right-click// menu:
> * Clone (Ctrl + C) : make a copy of this piece
> * Delete (Ctrl + X) : delete this piece
> ===== Notes =====
> There are currently two types of notes in the piecepack module: vassal built-in, and a post-it style note.
> The vassal built-in has lots of functionality (which can be learned about in the [http://vassalengine.org/UsersGuide/index.htm Vassal User's Guide]. It can be found on the toolbar ({{{Toolbar -> note icon}}}).
>
> The post-it style note can be placed on the board and moved around just like any piece. It can be found in the piece pallet ({{{Pieces -> miscellaneous -> notes}}}).
> **NOTE:** this entry is not complete.
> == Extensions ==
> The Vassal engine allows module creators to release extensions that add new pieces and functionality to existing modules. The extensions available for piecepack are intended to allow even more games to be played.
> === Installation ===
> In the same directory as the main piecepack module, create a directory named {{{piecepack_ext}}} and then put the extension file in the {{{piecepack_ext}}} directory. Now whenever you load the piecepack module, it will also load the extensions.
> **NOTE:** Many extensions are included with the large zip file containing the piecepack module. In fact ALL modules created at the time that the specific piecepack module was created are included, and will therefore not require any special installation!
> === Icehouse ===
> IceHouse pyramids. I am very happy with how this worked out.. translucent, stackable, nestable, 10 colours (red, blue, green, yellow, cyan, orange, purple, white, black and ice). Although the opaque pieces are available, they can not be used for hiding information.
> ==== How to Use It ====
> This module adds an //icehouse// option to the pieces menu. {{{Pieces -> icehouse}}} will reveal a list of colours available on the right. Select a colour and grab your pyramids!
> ===== Icehouse Pieces =====
> Each piece has the following options available in the //right-click// menu:
> * Set Down / Stand Up (Ctrl + S) : If the piece is standing set it down and vice versa.
> * Delete (Ctrl + X) : delete this piece
> * Clone (Ctrl + C) : make a copy of this piece
> * Rotate (Any Degree) (Ctrl + R) : allows arbitrary rotation of the pyramid. The cursor will change, then click and drag to rotate the piece, and release to stop rotating.
> * Rotate CW (Ctrl + ]): Rotates the piece 45 degrees clock-wise.
> * Rotate CCW (Ctrl + [): Rotates the piece 45 degrees counter clock-wise.
> === Checkers, Black & White Reversible Pieces, Match Sticks ===
> This expansion introduces Checkers, Black & White Reversible Pieces, Match Sticks. These are all pretty basic pieces with functions similar to pawns.
> ==== How to Use It ====
> Install it using the above generic extension installation instructions. This will add {{{Checkers}}}, {{{Matches}}}, and {{{Reversible}}} to the {{{Pieces -> Miscellaneous}}} menu. Choose your section and drag the pieces to the board as you would any other piece in the pallet.
> == The Future ==
> Any ideas or suggestions are always welcome.
> === Ideas for future extensions ===
> * PiecepackDiceCards
> * PiecepackPaperDice [Done] {OK}
> * PiecepackPyramids (these may be tricky given their ability to hide info etc.)
> * Tarot cards (play a couple of IceHouse specific games using this) [Done] {OK}
> * Standard Playing cards [Done] {OK}
> * Dominoes [Done] {OK}
> * chess pieces [Done] {OK}
> * fairy chess pieces [Done] (well sorta.. because 5 colours of chess pieces have been created and all of them can be rotated, and all can support labels, this should meet all of your fairy chess needs, let me know if you want to see something else) {OK}
> * "blank" cards that can be set to anything [Done] {OK}
> * seasonal suits [Done] {OK}
> * black and white versions of stuff for easy, nice printing of screen shots [started, will rely on an upcoming update of VASSAL]
> * PiecepackCash [Done] {OK}
> * Buttons to simulate rolling other dice (d4, d6, d8, d10, d12, d20, d30, d100) [Done] {OK}
> * Hex boards for game play (8x8 and 14x14) [Done] {OK}
> * Actual pieces (instead of just buttons) for the other dice mentioned above (aka "poly dice") [Done] {OK}
> * "Blank" dice much like the "Blank" cards, allowing users to set images or text strings for as well as a reporting name for each side.
> === Bugs, Corrections, or Feature requests for Existing Pieces ===
> * Add free rotate and spin to more objects (dice, coins)
> * Add trails to more objects (checkers, dice, gems)
> * cards (blank, playing and tarot) should all be sure to report turning
> * tarot cards should be randomly rotated when shuffled (zero or 180 degrees since orientation is significant with them)
> == User comments ==