1 Introduction

Tor Mohling is a System Administrator who works for the Department of Computer Science at the University of Colorado. In his spare time he developed a simple prototype of the board game TITAN. Due to time and work constraints the prototype is no longer being worked on. To correct this problem Tor has submitted a senior project proposal to the Department of Computer Science that has been accepted.

Because of increased nostalgia for this particular board game, the fact that it is currently out of print, and the unavailablility of it in the market place, a computerized version of TITAN is in high demand. The new computer version of TITAN will have network support, artificial intelligence that controls computer opponents, and a simple yet robust interface to facilitate game-play.

The purpose of this paper is to clearly identify the design specifications of the Cronos project. The first section will examine the user interfaces, their options, and how the user interacts with them. The next section gives a high level overview of the design in the cronos project showing the relationship between the client, server, AI, and network. The network specification is then discussed giving examples of message command formats and their usage. Next, the classes section describes the interfaces and implementation of each module and its methods. The File Formats section describes the layout of the "Saved Game" and "RC" files. Lastly the paper will wrap up with a summary, glossary, and a supporting documents section.

2 User Interfaces

• 2.1 Help/Rules

  A help menu will be provided to assist users. When selected, help will send the appropriate rules section to the user's web browser. The user may need to specify browser information in the game configuration file.

• 2.2 File Menu

  A file menu will be provided with menu items, connect, disconnect, save, quit.

• 2.3 Edit Menu

  An edit menu will be provided with a preferences menu item.

• 2.4 Main Window/Board

  The main window will show the main board and game state information. The board shows:

  • Disguised stacks - A stack cover which shows the location of a stack on the board.
  • Possible moves - When a stack is selected using the possible-moves mouse-key combination the GUI will highlight those hexes to which the stack can be moved on the current move roll. This feature is only available during the movement phase.
  • Terrain features - Different hexes have different colors and labels, as seen in the picture. These indicate the type of terrain that hex contains.
  Around the board will be displayed:
  • Player scores - Each player's color coded name and score will be displayed in a turn-orderded list in the top left corner of the main window.
  • Game State - The current round number, player turn and phase will be displayed on the top right corner of the window with the identifiers "Round:", "Turn:", and "Phase:."
  • Movement die roll - The last movement die roll result will be shown in a box on the top right of the board, below the game state information, with the identifier "Move:"
  
  Figure 4, below, shows much of this information.

  There is also a contextual menu which can be accessed by the correct mouse-key comination. The basic form of this menu will be empty in the basic design but items may be added to during the optional features stage of development.
  If the menu is brought up while the mouse is over the board it will have items: Native Creatures, Mustering Table.
  If the menu is brought up over a stack on the board you will have additional menu items: View Stack, Mustering Possibilities, Stack Size.
  If the current phase is the movement phase, and the mouse is over a stack then the following additional menu items are available: Possible Moves, Move stack.
  

  
  

• 2.5 Stack Manipulator

  The stack manipulator will allow a user to split and examine stacks. The user can select the monsters to be included in each stack as well as the stack cover. For the examine stack window the user will have a pop-up window that shows the images of the cover, creatures, and any empty places in the stack. There will be no way of changing any of the stack content from this screen and it will simply have "OK" and "Dismiss" buttons to close the window. Figure 5, to the right, shows the stack examiner window in action.

  The second window will control the initial setup of the two starting stacks along with stack splitting. The user will get a window consisting of two to three rows, each row containing five drop down menus. Each row represents a stack, the first drop down menu allows selection of the cover that will go with that stack, and subsequent drop down menus will allow selections of available monsters. This pool of available monsters is either decided by the Law of Titan for starting stacks, or by the current stacks contents in the case of splitting.There will be an "OK" button for confirmation of the changes and a "Dismiss" button

  
  

• 2.6 Battle

  When a battle occurs, the clients of the players involved will pop up a battle window. This window will show the battle map for the home terrain. In this window players can:

  • Have damage taken displayed for each monster.
  • See the turn displayed on the bottom of the screen.
  • Move monsters around the battle map.
  • Attack monsters.
  • See the special rules for the terrain on the battle map.
  
  The lower three features will be accessed through a contextual menu accessed through a mouse-key combination. Figure 6 below shows an example battle map.
  

• 2.7 Chat/Log

  The client will display a window that logs all game actions. This window may also be used by players to send messages to one another. The user may also output this chat/log window to a file. The window should look like a normal chat window with a couple of lines to type into and the majority of the window taken up displaying the above information. If the user chooses, the log may be sent to a separate window.

• 2.8 Stack View

  This is a simple window which displays a picture of each creature in a stack, if it is an opposing player's stack then the pictures will be blank.

• 2.9 Mustering Possibilities

  This will be a simple window which displays all monsters that can be musterd on a hex with the selected stack.

• 2.10 Native Creatures

  This is a table which contains all creatures native to the selected terain.

• 2.11 Mustering Table

  This window displays all the creatures which can be mustered on a hex and what it takes to muster them.

• 2.12 Contextual Popup Menus

  With the proper key-click combination, the user will be able to pop up a contextual popup menu. This menu will show information about the object or area clicked on and may allow the user to take certain actions. For instance, the popup menu for a stack will show the contents of the stack and what can be mustered. It will also have a "Move Stack" menu item which will allow the user to click elsewhere and move the stack. The contents of these menus is described under the relevant modules.

3 Design Overview

• 3.1 High-Level Modular Decomposition

  The high-level modular decomposition is shown in Figure 1 below. Cronos is composed of three major modules, server, client, and artificial intelligence.

  
  

• 3.2 Server Module

  The server module maintains a master copy of all game state information. Clients and AI players send commands to the server; the server then updates game-state information and sends the updates to all clients and AI. Figure 2, below, shows interactions within the server.

  
  

• 3.3 Client Module

  Human players use a client with a graphical interface. The client displays game state information provided by the server. The client provides several tools for manipulation of the game state. When the user approves a set of modifications (as per the Turn Structure), the client sends changes to the server. The client is responsible for display of all interfaces described in the User Interfaces section. Figure 3, below, shows interactions within the client.

  
  

• 3.4 Artificial Intelligence Module

  Computer players will be implemented through an API which allows programmers access to game state information and manipulation. To the server, an AI player is functionally equivalent to a human player. The AI will be implemented as part of the client program.

4 Network Protocol

• 4.1 Message Format

  Every command that is registered will be required to accept a string as a parameter. This string is the remaining string after the first word is removed by the Network module. The first word is the "command" and it used by the network module to parse the message and send it on to the correct method. The Network module will strip any newlines before sending the message and will then append a newline to the message. <player> as the first argument to a message is only meaningful when the message is sent from the server to the client. The server will ignore that field when it receives such messages. The response messages inform the client whether the command succeeded or not (whether <ack> is true or false).

• 4.2 Network Commands

  This is a list of all the network commands and the arguments they expect to recieve. All arguments are assumed to be words unless otherwise stated. The acknowlegements to each command (where applicable) are true or false, depending on whether or not the command was successful or not. If the call was not sucessful, then after the word "false" will be an explanation of why the call did not succeed. The first word is the command, and it must not have any white space. Angle brackets denote that the term should be replaced by the value. Square brackets denote an optional parameter. On the server side, ALL handlers recieve a player name as a second argument.

  • battle_attack <monsterid1> <monsterid2> <damage> - Monster1 should attack monster2, and do damage, damage
  • server_battle_attack <monsterid1> <monsterid2> - Monster1 should attack monster2
  • battle_concede - Concede the current battle
  • battle_init <hex> <attack_side> <attacking_stack>(<monster1>,<monster2>,...<monsterN>) <defending_stack>(<monster1>,<monster2>,...<monsterN>) - Starts the battle on hex.
  • battle_move <monsterid> <hexnum> ... <monsteridn> <hexnumn> - Move the monter with id, monsterid, to the hex with number, hexnum
  • battle_muster <monsterType> - muster the monster with type, monsterType to this battle
  • server_battle_range <monsterid1> <monsterid2> - Monster1 should attack monster2 with a ranged strike
  • battle_range <monsterid1> <monsterid2> <damage> - Monster1 should attack monster2 with a ranged strike and do damage in hit points.
  • battle_result <playername of winner> <losercover>
  • battle_summon <angelType> <cover> - Summon the angel with type, angelType, from the stack with cover, cover, to this battle
  • begin_battle [<battlehex1>]...[<battlehex>] - The battle phase has started
  • begin_game <startlocation> - The client the game has started, and to place initial 2 stacks at startlocation.
  • begin_move - The move phase has started
  • begin_muster - The muster phase has started
  • begin_split - The split phase has started
  • chat <sender> <message string> - Send message string to all players
  • connect <playername> - Connects to the server
  • creategame <gamename> [(<option>:<value>;...:<option>:<value>)] - Creates a new game on the server
  • destroystack <player> <cover> - Removes the stack with cover, cover, from the game.
  • end_battle <player> - The battle phase is over
  • end_game <player> - The game is over. This is sent to all players notifying them the given player is out of the game.
  • end_gamestart <player> - The client has finished the initial creation of stacks.
  • end_move <player> - The move phase is over
  • end_muster <player> - The muster phase is over
  • end_split <player> - The split phase is over
  • findgame [gamename <playername> <player2name> ... ] [game2name <playername> ... ] - Returns a list of games that can be joined, and the players in each game
  • gamestate <yourname> options(<option1>:<value1>;...;<optionX>:<valueX>) players(<player1>:<score>,<color1>-<color2>;...;<playerX>:<score>,<color1>-<color2>) state(<curplayer>,<turnnum>,<phase>) yourstacks(<cover1>:<hexnum>,<monster1>,...,<monsterN>;...;<coverX>:<hexnum>,<monster1>,...,<monsterM>) stacks:<player1>(<cover1>,<size>,<hexnum1>;...;<coverN>,<size>,<hexnumN>) ... stacks:<player1>(<cover1>,<size>,<hexnum1>;...;<coverN>,<size>,<hexnumN>) availmonsters(<type1>:<num1>;...;<typeN>:<numN>) - The entire game state
  • joingame <gamename> <preferred color> - Join a game on this server.
  • leavegame <gamename> - Leaves the current game before it starts.
  • loadgame <filename> - Loads a game from the file
  • move <cover> <hexnum> ... <cover> <hexnum> - Move stacks to new locations
  • muster <cover>:<monstertype>(<creature>,<creature>...) - Adds monsterType to the stack with the cover. The creatures that allowed the musters are supplied in parenthesis.
  • newstack <player> <cover> <location> <monster1> [<monster2>...<monstern>] - Creates a new stack
  • players <gamename> [<color>:<playername> ...] - A list of players in gamename. Server sends this to all players in the game when a client joins or leaves. A client can send this request, supplying just gamename.
  • privatechat <sender> <recipient> <message string> - Send a private message from sender to recipient with content the rest of the command.
  • refresh <playername>- The server responds with the complete game state
  • remove <player> <cover> <monsterName> - Removes a creature, monster, from the stack with cover, cover.
  • savegame - Save the game to a file
  • response:battle_attack <results> - Returns the damage done to monster2, or why it could not attack
  • response:battle_concede <ack> - Acks the concede took place
  • response:battle_init <ack> - Acknowledges that the battle has been initiated
  • response:battle_move <ack> - Acknowledges that the monster has been moved
  • response:battle_range <results> - Returns the damage done to monster2, or why it could not do it
  • response:battle_summon <ack> - Acknowledges that the summon was successul
  • response:chat <ack> - Acknowledges that the chat message was sent
  • response:creategame <ack> - Acknowledges a new game has been created
  • response:destroystack <ack> - Acknowledges that the stack was removed from the game
  • response:findgame [<game1>:<game2>:....:<gameN>] - Returns a list of current available game names
  • response:joingame <ack> - Acknowleges that the game has been joined
  • response:loadgame <filename> - Confirms that the game 'filename' has been loaded in the server
  • response:move <ack> - Acknowledges the move
  • response:muster <monsterID> - Gives the monster ID back to the client.
  • response:newstack <ack> - Acknowledges the stack was created
  • response:privatechat <ack> - Acknowledges that the privatechat message was sent
  • response:remove <ack> - Acknowledges that the monster with monster ID was removed from the stack
  • response:roll <@results> - A list of results from the roll command
  • response:splitstack <ack> - Acknowledges that the stack was split
  • roll [<numberdice>] - Roll nuberdice dice and respond, if numberdice is omitted roll 1 die.
  • score <player> [<value>] - When sent to the server the value is left off and the server responds with the same message with the value added.
  • splitstack <cover> <newcover> <monster1> [<monster2>...<monstern>] - Removes the monsters from the stack with stack cover, cover, and puts them in a new stack with stack cover, newcover.
  • startgame <gamename> - Start the game 'gamename'
  • startgame:startgame <ack> - Acknowleges that the current game has been started.
  
  
  

• 5 Cronos Classes

  5.0 Example -- Example module.

  This section demonstrates the conventions used in modules described later in this document. Cronos classes (also referred to as modules or packages) are set up according to perl conventions. All packages have TITAN:: as the first part of their identifier. Thus, the Example package identifier is TITAN::Example. TITAN:: has been dropped from this document for clarity and reduced typing. The Example class is defined in a file named Example.pm in a directory named TITAN. While perl technically allows packages to manipulate "private variables" of other packages, all accesses will be made through publically documented subroutines.

  Registers network handlers:

  examplemsg

  Example handles the command when the Network module receives an examplemsg message.

  Methods

  $obj = new Example(val1 => $foo, val2 => $num, array => @foo)

  Create a new object of type Example, taking three named parameters.

  $ret = $obj->METHOD($arg1, \@arg2)

  A Example object method that returns $ret and takes a scalar argument and an array reference.

  Any notes about implementation, such as member variables that are accessed with get and set methods.
  5.1 Dispatcher -- Helps to facilitate high level network game requests.

  The purpose of Dispatcher.pm is to process high level network game requests. Clients connect to the Dispathcer is connected to by a client. After connecting the dispatcher allows a player to create a new game, join a game that has not been started yet, and load a saved game for continuation. Once the game is started, or resumed from the point where it was saved, the dispatcher is done. In most instances the dispatcher will be called from either the titand application or the Network module. When it is done it should pass control to ServerFlow.

  Registers network handlers:

  connect

  This handler will create a connection with the client.

  creategame

  Creates a new game with the options specified. The only person who can modify the game settings after the game has been created is the person who created the game.

  startgame

  Starts the game with the current players, only legal after a game has been created. Only the creator of the game may start it.

  joingame

  Join a game that has been created before that game has been started. The player must specify what color they wish to join as, or a default value will be given. After a player creates a game, they then must join the game, givin a color.

  findgame

  Returns to the client a list of games which can be joined.

  leavegame

  Removes the player from a game before it is started.

  loadgame

  Loads a game from the specified game file,and starts the game immediately. All players have joined the game in order to load and start the game.

  Methods:

  No Implementation Notes
  5.2 Network -- Performs the work of registering handlers and sending information over the network.

  Network.pm takes care of all network activity. Modules send messages via the Network module. Modules may also register handlers to receive incoming commands.

  Methods:

  $network = new Network()

  Creates a new Network object.

  $bool = TITAN::network->registerHandler($command, \&subroutine, $object_or_class)

  When a module is loaded, it calls this method for each network command it wishes to receive. The supplied subroutine will be called when the command $command comes over the network. Every handler is required to accept one argument which is the command string after $command. The player sending the command will be supplied as the second argument, when the server receives a message. If the third argument is present, &subroutine will be called as a method of that object or class.

  $bool = TITAN::network->connect($hostname, $port)

  This method is called by the client to connect to the server, it connects and then sets the socket to an internal variable for the send command.

  $message = TITAN::$network->send($command, $message, @recipients)

  This method sends a message to everyone listed in the recipients array. It returns the message it was sent. @recipients contains Player references, and is ignored when run from the client, which sends all messages to the server.

  $message = TITAN::$network->sendall($command, $message)

  This method sends a message to all players connected. It returns the message it was sent. If the client calls this function, it will (should) work just like send.

  Every module that sends to the network needs to register a response message handler corresponding to the message sent.
  5.3 Player -- This module keeps track of a single player's information.

  This module represents a single player and all of their game information. Player.pm keeps track of the player's name, score, color, stacks, unused covers, order of play, number of Angels, and Titan strength.

  Methods:

  $player = new Player($name, $color)

  Creates a new Player object and sets the name and color variables for the player. It also updates the playerOrder array by adding a new name to it, at the end.

  $nextPlayerName = $player->nextPlayer($currentPlayerName)

  This method takes the name of the current player and then looks up the next player's name by looking through the playerOrder array.

  $stack = $player->newStack($location, $cover, @monsters)

  This method takes a list of monsters and creates a new stack instance containing them and with stack cover $cover. It also adds the new stack to $player's list of stacks. This method returns the created stack, or false on failure.

  $bool = $player->destroyStack($stack)

  Destroys the stack that corresponds to the specified object. Returns number of stacks player has for success or false for failure.

  $stack = $player->splitStack($stack, $newCover, @creatures)

  This method splits the stack and associates the $newCover and @creatures variables with the new stack. It returns the new stack.

  $name = $player->getSocket()

  This method returns $player's socket.

  $name = $player->setSocket($socket)

  This method sets the socket member variable and returns it.

  $name = $player->getName()

  This method returns $player's name as a string.

  $name = $player->setName($name)

  This method sets the name member variable and returns it.

  $score = $player->getScore()

  This method returns $player's score.

  $score = $player->setScore($score)

  This method sets the score member variable and returns it.

  $color = $player->getColor()

  This method returns $player's color name.

  $color = $player->setColor($color)

  This method sets the color member variable and returns it.

  @stacks = $player->getStacks()

  This method returns a list of Stacks controlled by $player.

  @unusedCovers = $player->getUnusedCovers()

  This method returns a list of unused stack cover strings.

  $numAngels = $player->getNumAngels()

  This method returns the number of Angels $player has available to add.

  $num = $player->setNumAngels($numAngels)

  This method sets the number of Angels $player has available to summon and returns it.

  $titanStrength = $player->getTitanStrength()

  This method returns $player's Titan strength.

  $strength = $player->setTitanStrength($titanStrength)

  This method sets $player's Titan strength and returns it. This function should not be used now!

  @getPlayerOrder = $player->playerOrder()

  This method returns an ordered list of

  @setPlayerOrder = $player->playerOrder(@playerOrder)

  This method sets the player order and returns it.

  Member Variables:

  • $name -- The name of the player.
  • $score -- The score of the player.
  • $color -- The color of the player.
  • @stacks -- A static variable that contains references to all stacks in the game.
  • @unusedCovers -- The available covers for a player.
  • $numAngels -- The number of angels that the player has.
  • $titansStrength -- The currect strength of the player's Titan.
  • @playerOrder -- A static variable the keeps track of the order of all players.
  5.4 Stack -- Keeps track of all stack properties.

  Manages creatures, adding creatures, splitting, location, cover, and the stack owner.

  Methods:

  $stack = new Stack()

  Creates a new Stack object.

  $stack = new Stack($owner, $location, $cover, @creatures)

  Creates a new Stack object with owner(player reference), location(hex num), cover(name) and @creatures(string names).

  $bool = $stack->destroy()

  This method will destroy the stack. First it will remove all monsters from the stack and return them to the monster pool by calling monster::returnMonster(@monsters). Next it will deallocate the cover and set all member variables to "". On success a value of true is returned. If there were any problems a value of false is returned and the stack is intact.

  $newstack = $stack->split($newCover, @creatures)

  This method creates a new stack with cover $newCover, contents @creatures, and the owner and location set to that of the original stack. The monsters in @creatures are removed from $stack. $newstack is in the same space as $stack. If the split would be illegal, this method returns '', otherwise it returns the new stack. Most modules should not call this function directly, but instead call Player::splitStack(), so that the player object knows about the new stack.

  $monster = $stack->muster($creature)

  Muster $creature (passed as a string) into $stack. This method checks if the stack can legally muster $creature from its current location. If the muster is legal it returns the monster string and adds the monster into the stack. If the muster would be illegal, this method returns false.

  @creatures = $stack->determineMuster($terrain, @creatures)

  DetermineMuster accepts a $location string that can either be a valid hex location or a terrain type. It also accepts @creatures which is an array of monster type strings. It will check to see what possible creatures can be mustered based on @creatures and $location. The possible monsters will be returned (as monster type strings) if there are any, otherwise the array will be length 0.

  @added = $stack->add(@creatures)

  The method adds all the passed creatures to the stack. It returns a list of creatures added. This list will be identical to @creatures on success and will have length 0 if the addition would be illegal. In most cases, $stack->muster() should be called instead.

  @added = $stack->addWithParents($creature, @parents)

  Add $creature to the stack. For any creature in @parents, if we don't know that it's in the stack, replace a dummy with it.

  @removed = $stack->remove(@creatures)

  Remove the supplied creatures from $stack. It also takes the removed creatures and returns them to the "creature pool" by calling Monster::returnMonster(@monsters). Returns a list of creatures removed, which is either identical to @creatures or has length 0 if at least one creature could not be legally removed.

  $size = $stack->size()

  This method returns the number of creatures in the stack.

  $location = $stack->setLocation($hexnum)

  This method moves $stack to $hexnum and returns its new location, which is its original location in case of an error. In most cases, Board::moveStack() should be called instead of this method.

  $location = $stack->getLocation()

  Returns the location (hex number) of $stack.

  @contents = $stack->setContents(@creatures)

  Sets $stack's contents to the supplied creature list and returns its contents. This method does no rules-checking. $stack->muster() and $stack->remove() should be used in favor of this method most of the time.

  @creatures = $stack->getContents()

  This method returns a list of monsters in $stack.

  $cover = $stack->setCover($cover)

  This method sets the cover of $stack and returns it. Make sure the appropriate Player object has $cover point to $stack.

  $cover = $stack->getCover()

  This method returns $stack's cover name.

  $owner = $stack->setOwner($owner)

  This method sets $stack's owner, a Player reference, and returns it.

  $owner = $stack->getOwner()

  This method returns $stack's owner, a Player reference.

  $stack = Stack::coverToStack($cover)

  Returns the Stack represented by $cover. If there is no corresponding stack, returns false.

  @covers = Stack::unusedCovers(@colors)

  Returns a list of covers that are not currently in use. The list contains only covers of those colors passed to the method, or all unused covers if no colors are provided.

  @unused = Stack::deallocateCovers(@covers)

  Deallocates the provided list of covers by adding them to the internal list of unused covers. It also removes all the creatures for each stack and returns them to the possible monster pool by calling Monster::returnMonster(@monsters). Returns a list of covers successfully deallocated. A cover currently not in use is not returned.

  @covers = Stack::allCovers(@colors)

  Returns a list of all covers of the given colors (strings), or all covers if no colors are passed.

  Stack cover strings are of the form "color_picture_description" where color is one of {black, blue, brown, gold, green, red}. Examples: red_flaming_sword, black_hand, gold_snake_and_sword.

  Member Variables:

  1. $location -- The current hex location of the stack.
  2. @contents -- An array of monsters that the stack contains.
  3. $cover -- The name of the current cover of the stack.
  4. $owner -- The current owner of the stack (a player reference).
  5. %coverToStack -- A static hash that has a cover name as its key and a stack reference as the value.
  6. %covers -- A static hash, containing the six colors as keys and an array of stack strings (color included) as values.
  5.5 GStack -- Displays stacks graphically.

  The GStack module displays the stack on the game board, allowing the player to split, muster, view and change the stack. GStack is a subclass of Stack.

  Methods:

  $stack = new GStack()

  Creates a new GStack object.

  $stack = new GStack($owner, $location, $cover, @creatures)

  Creates a new Stack object with owner(player reference), location(hex num), cover(name) and @creatures(string names).

  $bool = GStack::initialBuilder($startLocation)

  Creates a window where a player can decide the contents of his initial stacks when the game begins. Returns true if the window was successfully created, false otherwise. Updates the $main::ME to have the two new stacks, sends "newstack" across the network, and places the stack at the starting location.

  $bool = $GStack->splitter()

  Gives a graphical view of a stack, and lets the player choose which monsters go to which stack. Also allows the player to choose which stack cover goes on the new stack. Shows the members of the stack in a sub menu of the pop up menu. Returns true if the window was successfully created, false otherwise. Updates $main::ME and $main::GBOARD for the newly splitted stack.

  $bool = $GStack->examiner()

  Opens a window which displays the contents of the stack, as described under Stack Manipulator UI. Returns true if the window was successfully created, false otherwise.

  $bool = $GStack->sizer()

  Opens a window which display the size of the given stack.

  $bool = $GStack->musterer()

  This window shows which monsters are available to muster from any given terrain, given what $stack contains. This function will usually be called from popupMenu. If the user may muster something into $stack, this window allows them to do so.

  $menuItems = $GStack->popupMenu()

  Returns a menu handle. The menu contains information about $stack as described in the Popup Menu UI description.

  $newloc = $GStack->move($hexnum)

  Moves $stack to hex $hexnum. This is funneled through GBoard::moveStack(). If that is successful, this method sets member variable $movedYet and $location and returns its new location. On failure, this method returns its original location, at which it remains.

  $bool = $GStack->setMovedYet($movedYet)

  Sets whether $stack has moved this turn or not and returns that value.

  $movedYet = $GStack->getMovedYet()

  If $stack has moved during the current turn, returns true. Otherwise, this method returns false.

  $photoRef = GStack::getCoverImage($coverName, $size)

  This method takes the $coverName and the $size and returns a Photo ref to the correct cover image. Two catches though, you must have at least one instantiated GStack and $size must be one of the following "lg" or "sm".

  $photoRef = GStack::getMonsterImage($monsterName, $color)

  This method takes the $monsterName and the optional $color value and returns the correct photo refrence to it. $color is only needed when the monster type is a titan or angel.

  Member variables:

  • %coverFile -- A hash that correlates stack cover names to file names that are a picture of that stack cover.
  • $movedYet -- 'true' if the stack has moved during the current turn, and 'false' if not.
  5.6 Monster -- Stores information about monsters.

  Holds information about the monster strength, power, skill, name, damage and other stats.

  Methods:

  $monster = new Monster($owner, $type)

  Creates a new Monster object, the monster of type $type, and stores a refrence to the player $owner.

  $bool = $monster->setAvailableMonsters(\%availableMonsters)

  Takes the availableMonsters hash, which holds information about which monsters are currently in use in the game, and edits this hash to update the current state of the monster distribution. This will be called after a monster is created. Returns true on success or false for failure.

  %availableMonsters = $monster->getAvailableMonsters()

  Gets a copy of the availableMonsters hash.

  $numavail = Monster::available($creature)

  Returns the number of monsters of type $creature available for mustering.

  @monsters = Monster::returnMonster(@monsters)

  If the replenish_monsters option is set, this static method makes the passed monsters available for later mustering. Arguments can be either Monster references or strings representing monster types. Returns a list of monsters successfully returned to the pool.

  ($type, $power, $skill, $damage, $location) = $monster->getStats()

  Returns a list of attributes of $monster. The values of $damage and $location are undefined outside of battle. This method may also be invoked as Monster::getStats($type), where type is a monster string like "ogre" or "hydra" and is identical to the returned $name.

  $power = $monster->getPower()

  Returns the monster's power. May also be invoked as Monster::getSkill($type).

  $skill = $monster->getSkill()

  Returns the monster's skill. May also be invoked as Monster::getSkill($type).

  $type = $monster->getType()

  Returns the monster's type. This is a string such as "gargoyle" or "warlock". May also be invoked as Monster::getSkill($type).

  $damage = $monster->setDamage($damage)

  Changes the value of the damage to $monster. Returns the new value.

  $damage = $monster->addDamage($hits)

  Increases the damage of $monster by the given amount. Returns the amount of damage the $monster has after these hits.

  $damage = $monster->getDamage()

  Returns the amount of damage $monster has suffered in this battle.

  $hexnum = $monster->getLocation()

  Returns the value (hex number) of $monster's location on the battle map.

  $hexnum = $monster->setLocation($hexnum)

  Sets the value (hex number) of $monster's location on the battle map and returns it.

  $id_num = $monster->getId($monsterRef)

  Returns the unique id that the monster posesses.

  $monsterRef = TITAN::Monster->idToRef($id)

  Returns a reference to the monster with the unique id $id, if it does not exist, "" is returned.

  $result = TITAN::Monster->resetId()

  Resets the internal variable that keeps track of the next monsterID.

  $range = TITAN::Monster->range()

  Returns the range number that corresponds to the monster. A 0 is returned if there is no range option.

  $bool = $monster->setMoved($moved)

  This methods sets the internal moved member variable to the value passed in and returns true on success or false on failure. The value in $moved must be a 0 or a 1.

  $moved = $monster->getMoved()

  This method returns the current value of the internal member variable moved.

  $bool = $monster->setStruck($struck)

  This methods sets the internal struck member variable to the value passed in and returns true on success or false on failure. The value in $struck must be a 0 or a 1.

  $struck = $monster->getStruck()

  This method returns the current value of the internal member variable struck.

  Member variables:

  • %availableMonsters -- A hash table representing every monster in the pool of monsters, telling if they are currently in use or not.
  • %monsterStats -- Gives general information on the different classes of monsters, holding power, skill and over features.
  • $power -- The power of the monster object.
  • $skill -- The skill level of the monster object.
  • $name -- Holds the name of the current monster, or the monster type.
  • $damage -- How much damage has been done to the monster in this battle.
  • $location -- If the monster is on the battle map, this variable holds the hex number he is in.
  5.7 GMonster -- Graphical aspects of monsters.

  This subclass of Monster handles graphical aspects of monsters.

  Methods:

  $monster = new GMonster($monsterObject)

  Creates a new GMonster object to represent $monsterObject.

  $file = $monster->filename()

  Returns the filename of the image of this monster. This subroutine may also be called statically as GMonster::filename($type).

  $bool = $monster->battleDisplay($Monster)

  Displays $monster (its picture overlayed with the amount of damage it's taken) on the current battlemap. Returns a true on success or false for failure.

  $menu = $gMmonster->popupMenu()

  Displays a pop up menu that shows options and actions associated with a particular monster. Popup menus are described in the Popup Menu UI section. Returns a handle to the popup menu.

  void = $gMonster->displayDamage($TKButton)

  Displays the damage for the monster in the top left corner of the button that is passed. Please make sure the button corresponds to the correct gMonster.

  Member variables:

  • %monsterFile -- Maintains a mapping between monster types and the picture files associated with them.
  5.8 Board -- Representation of the main board and stack placement.

  Holds locations of each stack, can move stacks and give terrain information. All locations are expressed as hex numbers.

  Methods:

  $board = new Board()

  Creates a new Board object.

  $location = $board->moveStack($stack,$newLocation)

  Takes a stack ref and moves it to a new location. This method checks the move for legality in that it checks for friendly units on target hex. Returns the hex number the stack ends up on, which is either $newLocation or $stack's original location. Calling Function should only call this after comparing $newLocation with list of legal moves from Board->possibleMoves or Board->possibleTeleports. (this function also replaced teleportStack())

  @legalMoves = $board->possibleMoves($hexnum, $startingOrInTransit,$movesLeft, $previousHex, $player)

  This method recursively searches for possible moves. If movesLeft is 0, it will return its current hex. Otherwise, it will return a list hexes obtained by calling possibleMoves($hex, 0, $movesLeft -1, $thisHex) on each hex that may be moved to from the current hex. $startingOrInTransit is true if the hex begins its move in $hexnum, false if it is passing through or landing there. This method stops recursing when the stack would encounter an enemy stack. Some moves may not be legal until another of the player's stacks has been moved out of the way. $player is a reference to a player object.

  @legalMoves = $board->possibleTeleports($stack)

  Given a stack location, and assuming a six was rolled, will determine where a titan or stack may teleport and high-light the legal moves. Returns an array of legal locations.

  $terrain = $board->terrain($hexnum)

  Will return the terrain type of the hex number in hexnum, for example if hex num is 45, and hex 45 is a swamp, it will return 'swamp'.

  @stacks = Board::stacksAt($hexnum)

  Returns a list of stacks residing at $hexnum. In scalar context, returns one stack at $hexnum.

  $location = Board::addStack($stack, $hexnum)

  Given a stack and a hex number, addStack will add the stack to the board and return the hex number of the stack it just added. If an enemy is at the given location, addStack will return "". This function will set the given stacks location on both the %stacksAt data structure and in the data structure $stack points to.

  $location = Board::removeStack($stack)

  Given a stack, removeStack will remove the stack from the board and return the hex number (locale) of the stack it just removed. This function will set the given stacks location to undefined on both the %stacksAt data structure and in the data structure $stack points to. NOTE: Calling function should also release $stack's monsters and stack cover!

  Member variables:

  • %stackAt -- A hash table that maintains the location of every stack on the board.
  • %hexes -- A hash table that maintains information about every hex on the board, holding such information as the terrain type, movement rules and muster capability.
  5.9 GBoard -- Visual representation of the game board

  This subclass of Board shows locations of each stack, can move stacks and give terrain information.

  Methods:

  $board = new GBoard()

  Creates a new GBoard object.

  $bool = $board->draw()

  Draws hexes on the screen and fills them in with the appropriate color. Then draws stacks in their hexes. Returns true on success or false for failure.

  $bool = $board->possibleMoves($stack)

  Highlites the moves found by Board::possibleMoves. Returns true on success or false on failure.

  $bool = $board->possibleTeleports($stack)

  Highlites the moves found by Board::possibleTeleports. Returns true on success or false on failure.

  $bool = $gBoard->popUpMenu($hexnum)

  Will pop up a menu that gives the player options, such as view the hex type. Returns true on success or false for failure.

  No Implementation Notes
  5.10 Dice -- Randomly generates numbers.

  Rolls six sided dice, determines move length and battle statistics.

  Registers network handlers:

  roll

  Rolls a specified number of dice and responds.

  Methods:

  $result = Dice::rollOne()

  Will 'roll one die' (generate a random number from 1-6) and return the result.

  @sortedArray = Dice::roll($numDice)

  Will 'roll' numDice die and return a sorted array of the results.

  $numSuccess = Dice::rollWithTolerance($numDice, $threshold, \@results)

  Used in battle, rolls numDice dice and returns the number that are >= $threshhold. If @results is passed by reference, it is filled with the actual numbers rolled, both successes and failures.

  No Implementation Notes.
  5.11 Chat -- Messages sent between players

  Chat.pm provides the underlying framework for messages to be sent among players. These messages originate from the players and are equivalent to discussion during a real-world game. Messages generated by the software itself are handled by Log. Chat messages may be private, sent from one player to another, or public, broadcast to all players.

  Registers network handlers:

  chat

  Sends a message to all players.

  privatechat

  Sends a message to specified player.

  Methods

  $chat = new Chat($Network, $Player)

  Creates a new Chat object. $Network and $Player are refrences to Objects.

  $sent = $chat->tell($Player_str, $Message_str)

  Sends a private message with content "Message" to Player1. The message sent is returned. This method is to be invoked by the client, and sends a network privatechat message to the server.

  $sent = $chat->broadcast($Message_str)

  Sends a message with content "Message" to all players. The message sent is returned. This method is to be invoked by the client, and sends a network chat message to the server.

  No Implementation Notes.
  5.12 GChat -- Client chat GUI

  GChat.pm provides players with a window and text input box so that they can send and receive chat messages. GChat is a subclass of Chat and is described in the User Interface section.

  Methods

  $chat = new GChat(@playerNames,@playerColors)

  Creates a new GChat object.

  $msg = $chat->writeprivate($player, $message)

  Writes a private message from $player (a string). Returns the message written.

  $msg = $chat->writebroadcast($player, $message)

  Writes a broadcast message from $player (a string). Returns the message written.

  $msg $chat->writelog($message)

  Writes a log message. This message will look distinct from private and broadcast messages.

  No Implementaion Notes
  5.13 ServerChat -- Chat facilitation

  ServerChat.pm takes messages to be sent and delivers them to the appropriate players. See Chat for more information.

  Methods

  $schat = new ServerChat

  Creates a new ServerChat object.

  $sent = $chat->tell($player1, $player2, $message)

  Sends a private message with content $message to $player1 from $player2. The message sent is returned. This method dispatches a network privatechat message to $player1's client.

  $sent = $chat->broadcast($player, $message)

  Sends a message with content $message to all players. The message sent is returned. This method dispatches a network chat message to each client.

  No Implementation Notes.
  5.14 Log -- Log of game actions and software activity.

  Log.pm takes messages generated by other modules and outputs them. The log may be displayed to the user, either through the chat window a separate window, output to a (titan.log), or ignored. These methods will normally be called as class methods (Log->log("foo")), but code sections can create their own Log objects for debugging (or other purposes).

  Methods

  $log = new Log(toFile => $filehandle, toChat => $bool2, toWindow => $bool3, toStderr => $bool4)

  Creates a new Log object. If a destination is not supplied, it is assumed false.

  $sent = $log->log("Message", @classes)

  Logs the given message with newline added. If @classes is present, only logs the message if at least one of @classes is set to be logged by logClass.

  $boolean = $log->toFile($filehandle)

  Turns logging-to-file on or off and returns its new state. If no argument is specified, returns current state.

  $boolean = $log->toChat($bool, \$gchat)

  Turns logging-to-chat-window on or off and returns its new state. If turned on, supply a ref to the gchat object. If no argument is specified, returns current state.

  $boolean = $log->toWindow($bool)

  Turns logging-to-separate-log-window on or off and returns its new state. If no argument is specified, returns current state.

  $boolean = $log->toStderr($bool)

  Turns logging-to-stderr on or off. If no argument is specified, returns current state.

  $boolean = $log->logClass($identifier, $bool)

  Sets logging of $identifier type messages to $bool. If $bool is not present, returns the current value. This function allows classes of messages to be logged or not with little intervention. For instance, graphical modules could check logClass("graphical") and, if true, log their message.

  Log classes:

  • debug - general debugging
  • graphical
  • network
  • action - stuff that happens in the game
  • all - doesn't need to be included in log()
  5.15 GLog -- Log window

  This module provides a window for the user to see log messages.

  Methods

  $glog = new GLog

  Creates a log window.

  $msg = $glog->message($message)

  Displays $message at the bottom of the log window.

  Implementation Notes
  5.16 Battle -- Allows two stacks to engage in battle.

  When a stack lands on a hex occupied by an opponent's stack, the two stacks enter battle. Battle.pm implements starting a battle, moving, attacking, summoning and other battle functions.

  Registers network handlers:

  battle_init

  Upon recieving this message, a new Battle object will be created and initialized.

  battle_move >monsterid&ls; >hexnum&ls; ... >monsteridn&ls; >hexnumn&ls;

  Upon recieving this message, the $battle object will move the monsters to the specified hexes.

  battle_range

  Will initiate a call to the 'range' function.

  battle_attack

  Will initiate a call to the 'attack' function.

  battle_summon

  Will initiate a call to the 'summon' function.

  battle_muster

  Will initiate a call to the 'muster' function.

  battle_concede

  Will initiate a call to the 'concede' function.

  battle_next_phase

  Will initiate a call to the phase advancement function.

  server_battle_attack

  Will initiate a call to the server 'attack' function.

  server_battle_range

  Will initiate a call to the server 'range' function.

  Methods

  $battle = new Battle(attacker => $player1, defender => $player2)

  Creates a new Battle object with an attacker and defender.

  $board = $battle->initialize($mainboardhexnum, $attacker_side, $attackerstack, $defenderstack, \@attackermonsters, \@defendermonsters)

  Initializes the BattleBoard object with the attacker, defender, where the battle is taking place, and the monsters in each player's stack. Returns a BattleBoard.

  $location = $battle->move($monster, $hex)

  Moves $monster to the given hex. Returns the monster's new hex, or if the monster can't move there it returns error. If $monster is omitted, moves the monster in the first hex argument.

  $numhits = $battle->range($monster1, $monster2)

  $monster1 range-strikes $monster2. The number of hits inflicted is returned.

  $result = $battle->attack($monster1, $monster2)

  $monster1 attacks $monster2. The number of hits inflicted is returned.

  $bool = $battle->canSummon()

  Returns true if the attack can summon an angel right now!

  @possibleSummons = $battle->possibleSummons()

  Returns a list of 'sourcestackcovername', 'angeltype' the attacker can summon angels from.

  $monster = $battle->summon($angelType, $angelsourcestack)

  If legal, summon $angelType('angel' or 'archangel' into this battle from $angelsourcestack cover name stack. Should not be called directly form the client instead send a battle_summon network message.

  $bool = $battle->canMuster()

  Returns true if the defender can muster right now!

  @monsters = $battle->possibleMusters()

  Returns a list of monsters that the defender can muster right now.

  $monster = $battle->muster($monsterType)

  If legal, muster $monsterType into this batter on the defenders side. Should not be called directly form the client instead send a battle_muster network message.

  @monsters = $battle->getAttackerMonsters( )

  Returns a list of the Monsters owned by the Attacker.

  @monsters = $battle->getDefenderMonsters( )

  Returns a list of the Monsters owned by the Defender.

  $result = $battle->concede($who)

  If a player wishes to concede a battle, $who should be either 'attacker' or 'defender'. The player may only concede at times specified in The Law of Titan or official clarifications. Returns true on success, false if concession was not possible.

  Member variables:

  • $stage -- The phase of the battle.
  • $turn -- The turn of the battle.
  • %attacker -- Has keys monsters (array), player (Player object), stack reference, value for side attacker enters battle from.
  • %defender -- Has keys (monsters array), player (Player object), stack reference, value for side defender enters battle from.
  • @monsters -- List of monsters at locations
  • $board -- BattleBoard object where the battle takes place
  • $mainhex -- Number of the hex on the main board where the battle occurs
  5.17 BattleBoard -- Represents the terrain where a battle takes place

  This module provides information about the type of terrain that battle is taking place on, including hex terrain and handicaps.

  Methods

  $battleboard = new BattleBoard($terrain)

  Creates a BattleBoard object for $terrain.

  $location = $battleboard->move($start, $end)

  If legal, moves the creature at $start to $end and returns the creature's location ($start on failure, $end on success).

  $location = $battleboard->place($monster, $entryside)

  Places a monster on the "staging area", so it is ready to move onto the board. $entryside must be 0-5, corresponding to the entry side of the battle board for the monster's owner.

  $location = $battleboard->remove($monster)

  If monster exists, removes the given monster reference from the monsterAt hash.

  $monster = $battleboard->getOccupant($hexnum)

  Returns the Monster object that resides on $hexnum.

  @sides = $battleboard->getSides($hexnum, [$side])

  Returns what is on each side of a hex terrain (e.g. 'uphill', 'downwall') or on $side. Side 0 is up and side numbers increment clockwise.

  $side = $battleboard->findSide($hexnum1, $hexnum2)

  Returns the side # that hexnum2 borders hexnum1 on. (for example, if hexnum2 is directly above hexnum1, a 0 is returned. Recall that side numbers start at 0 (top) and increase clockwise.)

  $terrainType = $battleboard->getFeature($hexnum)

  Returns the terrain feature $hexnum has, e.g. 'bramble', 'sand', etc.

  @legalMoves = $battleboard->possibleMoves($monster)

  Returns an array of all possible moves for this monster.

  @legalMoves = $battleboard->movesSearch($hexnum, $movesleft, $monster)

  Returns an array of all possible moves for this monster from this hex. This method is called by possible moves as its recursive call, and should not be called by other functions external of BattleBoard.pm.

  $bool = $battleboard->canMove($monster, $endhex)

  Returns true if the $monster can move from $starthex to $endhex, false if it is not legal.

  @path = $battleboard->rangeStrikePath($monster1, $monster2)

  Returns false if monster1 can not range strke monster2, otherwise returns the best path from monster1 to monster2 for the ranged strike, where less terrain is better and the path includes the monster2 hex but not the monster1 hex.

  $bool = $battleboard->canStrike($monster1, $monster2)

  Returns false if monster1 can not strke monster2, and true if monster1 can strike monster2.

  @monsterlocs = $battleboard->possibleStrikes($monster1)

  Returns an array of all monster locations the given monster can strike.

  @monsterlocs = $battleboard->possibleRangeStrikes($monster1)

  Returns an array of all monster locations the given monster can range strike.

  $bool = $battleboard->isNative($monster, $feature)

  Returns true if the $monster is native for the $feature. Valid features are: bog, sand, bramble, drift, volcano, updune, downdune, upslope, or downslope.

  Member variables:

  • $terrain -- The name of the terrain in the battle.
  • @hexes -- each has a hash with keys occupant (Monster object), feature (string), sides (array with {hill, cliff, flat} for each of six sides).
  5.18 GBattleBoard -- Visual interface to battle and terrain

  A graphical representation of the battle terrain, allowing the user to interact with the board and individual monsters.

  Methods

  $board = new GBattleBoard($battle, $terrain)

  Creates a GBattleBoard object.

  $bool = $board->drawBoard()

  Draws the board on the screen. Returns true on success, false on failure.

  $menu = $board->popupMenu($hex)

  Displays a pop up menu on the GBattleBoard with the battle options.

  Has underlying BattleBoard and Battle objects.
  5.19 ServerFlow -- Controls the flow of function calling for the server process.

  ServerFlow.pm runs the game on the server side, invoking methods of other modules when the time comes.

  Registers network handlers: *NOTE: Most handlers on the server side require the first word in the passed string be the sending player's name.

  newstack <player> <cover> <location> <monster1> [<monster2>...<monstern>]

  will add stack to the board. If this is the start of the game, sends begin_split to first player after everyone has added 2 stacks.

  destroystack <player> <cover>

  destroys stacks and sends notification to others.

  refresh <playername>

  Responds with a gamestate message to the requesting client.

  savegame <gamename> <comment>

  Save the game. Default save game name is the day of the week (Sun.titangame)

  loadgame <gamename>

  Load a saved game.

  move <cover> <hexnum>...<cover> <hexnum>

  moves stacks to legal location, sends response to sending client and notification to all others.

  muster <cover>:<monstertype>(<creature>,<creature>...)

  musters given creatures to a stack if legal, sends response to sending client and notification to all others.

  roll <numdice>

  rolls a number 1-6, sends response to all clients and notification to the log. (Should be replaced by a call to TITAN::Dice once we code it. Currently, this network message is not very useful, only basically functional.

  splitstack <cover> <newcover> <monster1> [<monster2>...<monstern>]

  Removes the monsters from the stack with stack cover,splits a stack, sends response to sending client and notification to all others.

  battle_init <hex>

  Calls $battle = TITAN::Battle->new($attacker, $defender), battle->initialize($mainboardhexnum, $attacker_side, $attackerstack, $defenderstack, \@attackermonsters, \@defendermonsters).

  end_gamestart <playername>

  notifies server of initial stack choices, sends response to sending client and notification to all others. If all clients have sent this message, sends begin_split message to first player.

  end_move <playername>

  moves stacks to legal location, sends response to sending client and notification to all others. If an illegal move is encountered, respond with a failure. Starts sending client's battle phase.

  end_muster <playername>

  notifies server of end of muster phase, sends response to sending client and notification to all others. Starts the next player's split phase.

  end_split <playername>

  ends the split phase, sends response to sending client and notification to all others. Begins the move phase.

  end_battle <playername>

  ServerFlow will end the current player's battle phase and start the muster phase for that player. All players will be notified of the phase change. This function should check to see if there is only 1 player with stacks left. If so, declare him winner and send end_game message to all clients.

  Methods

  ServerFlow->setupGame(\%players, @startlocations)

  Sends begin_game <startlocation> message to all clients. Dispatcher calls this after all players have submitted their names and given initial information. This function is passed a reference to a hash of player names to player references. @startlocations is an array ordered the same way as @playerorder (which is accessed from Player) , containing the start locations 600, 500, ..., 100. Note that since the highest tower (start location) goes first, @startlocations should always be ordered from highest to lowest start position. If the startlocation array is not ordered, setupGame will re-order it. If @startlocation is not provided or contains invalid start locations, setupGame will simply assign 600 to the first player, and try to space the rest of the players evenly around the board.

  ServerFlow->battleOver($winner, $attackStack, $defendStack, $attackTitanDead, $defendTitanDead, $canMuster, $winnerPreviousScore)

  Takes care of removing stacks and allocating points in case of a titan death. $winner is "attacker" "defender" or "tie" $canMuster is true if the winner can muster. $winnerPreviousScore is the winner's previous score. must set variables in ServerFlow to allow winning player to do the out-of-turn muster / angel summon. This function prepares ServerFlow for the out-of-turn muster network request.

  ServerFlow->loadGame(\%players, $filename)

  Loads game stored in $filename. If all and only those players currently connected to game $filename were in the saved game, sends a gamestate message to all players. The server is ready to continue the game.

  Member variables:

  • @playerorder -- An array of the complete list of Players.
  • %players -- A hash of playernames to player references.
  • $curplayer -- The player whose turn it is.
  • $curphase -- The current phase of the turn.
  • $board -- The Board object to operate on.
  • $battle -- The current BattleBoard object.
  • $movementroll -- The die roll for movement for the current phase.
  5.20 ClientFlow -- Phase transitions for the player

  ClientFlow.pm runs the game on the player's side, invoking methods of other modules when the time comes.

  Registers network handlers:

  battle_init

  Starts the battle on the specified hex.

  begin_battle

  Tells the client to start the battle phase. This updates the $curPHase variable to "begin_battle", and the $curPlayer to $me.

  begin_game <startlocation>

  Tells the client to move into the first phase of the first player's turn. This is used for the unique instance that clients are creating their initial stacks at the start of the game. Sets $curPhase to "begin_game", $curPlayer to $me. This happens at the same time for all players. The initial 2 stacks should be created at the start locations assigned.

  begin_move

  Tells the client to start the movement phase. Updates $curPhase to "begin_move" and $curPlayer to $me.

  begin_muster

  Tells the client to start the muster phase. Updates $curPhase to "begin_muster" and $curPlayer to $me.

  begin_split

  Tells the client to start the split phase. Updates $curPhase to "begin_split" and $curPlayer to $me.

  end_battle

  Tells the client that another client's battle phase has ended. Updates $curPhase to "begin_muster" and $curPlayer to the player name sent.

  end_game

  Tells the client that a client's game has ended (could be this client as well). If it's this client, then it sets $curPhase to "end_game" and $curPlayer to $me. This will signal the G-modules that this client can no longer play. If it's a different client all internal variables representing the client will be removed and updated accordingly. $curPhase will be adjusted to "begin_split" and $curPlayer to the next player if the client whose game has ended was currently playing. Otherwise $curPhase and $curPlayer stay the same.

  end_move

  Tells the client that another client's move phase has ended. This updates $curPhase to "begin_battle" and $curPlayer to the passed in player.

  end_muster

  Tells the client that another client's muster phase has ended. This updates $curPhase to "begin_split" and $curPlayer to the player after the passed in player.

  end_split

  Tells the client that another client's split phase has ended. This updates $curPlayer to "begin_move" and $curPlayer to the passed in player.

  destroystack

  Updates the clients internal variables for the destroyed stack. Calls GBoard->removeStack to update the GUI.

  gamestate

  The game state is the argument recieved, it contains the entire game state so the client can do a total refresh of its data. It first checks to see if the instances exist, if so it updates them accordingly. If not it creates them with the correct information.

  move

  Updates the positions on the stacks for the clients internal variables. Also calls GBoard->moveStack() to update the GUI.

  muster

  Updates the stack contents for the clients internal variables. Shouldn't have to call and G modules since contents are displayed on demand.

  newstack

  Creates a new stacks and updates all necessary internal variables of the client. Also calls GBoard->addStack to update the GUI.

  remove

  Removes monsters from a stack and updates the clients internal variables. Should not have to call any G modules since contents are displayed on demand.

  score

  Updates a players score for the clients internal variables.

  splitstack

  Splits a stack and updates all necessary client internal variables. Also calls GBoard->addStack to update the GUI with the new stack.

  Methods

  ClientFlow::setPlayers(@players)

  Sets the clients internal @players arrays to what was passed in @players. @players is a valid array of Player references that are in order. Returns @players on success, else an empty string.

  ClientFlow::getPlayers()

  Returns the internal @players array if it's defined, else an empty string.

  ClientFlow::setCurrentPlayer($player)

  Sets the clients $curPlayer to the passed in player name. This is the player whose turn it currently is. Returns $curPlayer on success, else an empty string.

  ClientFlow::getCurrentPlayer()

  Returns the value of $curPlayer if it's defined, else an empty string.

  ClientFlow::setCurrentPhase($currentPhase)

  Sets the internal $curPhase variable for the client if $currentPhase is a valid phase. The name of the phases correspond to the handler names, see below. Returns $curPhase on success, else an empty string.

  ClientFlow::getCurrentPhase()

  Returns the value stored in $curPhase of the client if it's defined, else an empty string.

  ClientFlow::setMe($player)

  Sets the internal variable $me to the player reference. This is who this client represents. Returns $me on success, else an empty string.

  ClientFlow::getMe()

  Returns the value stored in $me of the client if it's defined, else an empty string.

  Member variables:

  • @players -- An array of the complete list of players in turn order.
  • $me -- The player name that this client represents.
  • $curplayer -- The player's name whose turn it is.
  • $curphase -- The current phase of the turn. These are named following the handler names (begin_game, begin_split, begin_move, begin_battle, begin_muster, end_game).
  • $curBattle -- The current Battle.
  • $board -- The GBoard object.
  • $battleboard -- The current GBattleBoard object.
  5.21 AIFlow -- Invoke the proper AI methods

  The AI needs move through the different phases of the game by calling different modules. This module is responsible for calling the phase modules in order for each players turn.

  AIFlow.pm runs the game on the artificial player's side, invoking methods of other modules when the time comes.

  Registers network handlers:

  gamestate

  The game state is the argument recieved, it contains the entire game state so the client can do a total refresh of its data.

  begin_game <startlocation>

  This tells the AI to move into the first phase of the first player's turn.

  begin_split

  AI starts the split phase.

  rolled

  The argument is the value that was rolled by the server.

  begin_move

  AI starts the movement phase.

  begin_battle

  AI starts the battle phase.

  begin_muster

  AI starts the muster phase.

  Methods

  AIFlow::runGame

  Creates a new game and runs it. All needed information will be acquired by a refresh network command.

  Member variables:

  • @players -- An array of the complete list of players in turn order.
  • $curplayer -- The player whose turn it is.
  • $curphase -- The current phase of the turn.
  • $board -- The Board object.
  • $battle -- The current Battle.
  • $battleboard -- The current GBattleBoard object.
  • $ai -- The current AI strategy.
  5.22 AI -- Interface class for AI strategies

  AI.pm presents an interface that implemented AI strategies must support. Methods in AI.pm do nothing.

  Methods

  $ai = new AI

  Creates a AI object.

  $bool = $ai->beginGame()

  This needs to decide what goes in what stack. Returns true until we know what failure is in this case.

  $ret = $ai->beginSplit()

  This needs to be implemented to decide what stacks need to be split and how. Returns true until we know what failure is in this case.

  $ret = $ai->beginMove($roll)

  This needs to be implemented to decide where to move the stacks and move them. Returns true until we know what failure is in this case.

  $ret = $ai->beginBattle($hex)

  This needs to be implemented to play out the battle at $hax. Returns true until we know what failure is in this case.

  $ret = $ai->beginMuster()

  This needs to be implemented to decide which monsters to muster in the different stacks. Returns true until we know what failure is in this case.

  No Implementation Notes
  5.23 AI::<ainame> -- AI strategy

  AI strategy foo will be in package AI::foo and will implement the methods described in the AI module.

  No Implementation Notes
  5.24 GameOptions -- Optional game settings

  This non-instantiated class allows the user to get and set the optional game settings. These are the settings which must be configured before the game is started. The player who starts the game on the server sets these options.

  Methods

  $val = get($option)

  The value associated with $option (a string) is returned.

  %options = getAll()

  Return a hash of all game options.

  $val = set($option, $value)

  The $option value in the hash is set to the passed $value. The new value is returned.

  %options = setAll(%opts)

  Set all game options to the provided hash. Does not alter options not passed.

  Member variables:

  • %options -- A hash of the game options.
  5.25 Preferences -- Gets and set the user preferences

  This non-instatiated class allows the user to get and set preferences for their client. These are settings which can be changed at any point during the game.

  Methods

  $bool = readFromFile($titanrcfilename)

  Load preferences stored in the supplied titanrc file, or ~/.titanrc if none is supplied. Returns true on success, false on failure and sets $!.

  $bool = saveToFile($titanrcfilename)

  Save preferences to the supplied titanrc file, or ~/.titanrc if none is supplied. Returns true on success, false on failure and sets $!.

  $val = get($pref)

  The value associated with $pref is returned.

  $val = set($pref, $value)

  The $option value in the hash is set to the passed $value. The new value is returned.

  Member variables:

  • %prefs -- A hash of the current preferences for this client.
  5.26 GOptions -- This module displays the pop-up windows that allows the user to change game options and preferences.

  Methods:

  $bool = GOptions->choiceWindow($choice)

  Generates either the game options window of the preferences window based on the value of $choice that is passed. $choice must be either the word "options" or "preferences". It then dynamically builds the window from the Default.pm for Game Options.

  No Implementation Notes
  5.27 titan -- Program client executes

  Command line parameters: --rcfile location --ai strategyname

  Member variables: These are available to modules via $main:var

  • $SERVER = 0
  • $CLIENT = 1
  5.28 titand -- Program the server executes

  Command line parameters: --rcfile location --port num.

  Member variables: These are available to modules via $main:var

  • $SERVER = 0
  • $CLIENT = 1
  
  
  

• 6 File Formats

  • 6.1 Save File

    The goal of the save game file is to have it formatted in such a way that a user would be able to open it, read it, and understand the format. This way the user can create his/her own save game file based off of an actuall session of the boardgame version of Titan. As such the file needs to have a basic structure for the titan program to understand without any unnecessary syntax or naming conventions which could possible confuse the user. All fields will be white space delimited with each entry on a single line. All fields that have a name value will have an "_" instead of a space as to not confuse the parser. Any options that aren't specified in the save game file will simply be assigned a default value. Below is the general format of the same game file. Please note the "...." implies repetition of the format for the context that it is in.

    • comment <comment string>
    • number_of_players <number>
    • player_order <name> <name> <name>
    • current_player <name>
    • options
      • <option name> <value>
      • <option name> <value>
      • ....
      • <option name> <value>
    • player <name> <color> <score>
      • stack <cover name> <hex location> <creature 1> <creature 2> .... <creature n>
      • stack <cover name> <hex location> <creature 1> <creature 2> .... <creature n>
      • ....
      • stack <cover name> <hex location> <creature 1> <creature 2> .... <creature n>
    • player <name> <color> <score>
      • stack <cover name> <hex location> <creature 1> <creature 2> .... <creature n>
      • stack <cover name> <hex location> <creature 1> <creature 2> .... <creature n>
      • ....
      • stack <cover name> <hex location> <creature 1> <creature 2> .... <creature n>
    • ....
    • player <name> <color> <score>
      • stack <cover name> <hex location> <creature 1> <creature 2> .... <creature n>
      • stack <cover name> <hex location> <creature 1> <creature 2> .... <creature n>
      • ....
      • stack <cover name> <hex location> <creature 1> <creature 2> .... <creature n>
    
    

  • 6.2 RC File

    This file is used to save basic preferences for the user. It can contain values pertaining to the user's choice of color, name, and game options. The file is an optional argument to either the titan or tiand program. If specified the envoked program will read and parse the file and setup the given parameters in the game automatically. This file also tries to be user friendly and as such tries to stay away from confusing naming conventions and symbols. All fields will be white space delimited with each entry on a single line. All fields that have a name value will have an "_" instead of a space as to not confuse the parser. Any options that aren't specified in the RC file will simply be assigned a default value. Below is the general format of the RC file. Please note the "...." implies repetion of the format for the context that it is in. Improperly formatted lines are silently ignored.
    
    

    • # comments are ignored
    • preferred_color <color>
    • preferred_name <name>
    • preferred_options
      • option_<option name> <value>
      • option_<option name> <value>
      • ....
      • option_<option name> <value>
  
  
  

• 7 Summary

  This document is intended to give a detailed description of the design of the Cronos project. It provided a detailed description of the user interface, and discussed the modular decomposition of the software. The object-oriented design of the Cronos Graphical User Interface was described in a detailed discussion of the classes comprising Cronos. This discussion included the methods provided by each class and a brief discussion of implementation issues such as member variable and other special notes if any. While it is almost certain that the final design and implementation of Cronos will not follow this design specification exactly, this paper should serve as a sound basis on which to implement the Cronos project.
  
  

• 8 Glossary

  • AI -- Artifically Intellegence.
  • Dice -- All dice in TITAN are six sided.
  • Hex -- A 'space' on the board, each hex represents a terrain where a stack can visit.
  • Monster -- A creature such as an Ogre, who combine with other creatures to make a stack. A monster has Power and Skill values.
  • Muster -- The process by which new creatures are added to a stack.
  • Power -- How many dice you roll for a creature in battle against an enemy in battle. Also the number of htis a monster can suffer before dying.
  • Range strike -- Being able to attack another creature when you are not in an adjacent hex to them.
  • Skill -- Determines how difficult a monster is to hit and how easily it hits other monsters.
  • Stack -- A hidden collection of monsters, identified by a stack cover. Stacks move from hex to hex on the board.
  • Stack split -- Dividing a stack into two stacks: taking some creatures from one stack and creating another with a new stack cover.
  • NAT -- Network Address Translation, a method of mapping several machines to a single public IP address
  
  
  

• 9 Related Documents

  • Law of Titan
  • Initial Requirements
  • System Architecture
  • Final Requirements