Quick Design Tour

Quick Design Tour


Moyoman was meant to make it easy for a new developer to understand how to contribute code. The goal of this document is to help the developer get up to speed quickly. The Moyoman software can be thought of as divided up into three components, the core framework, the modules, and the client program(s). The org.moyoman.framework package is the core of the Moyoman server. The org.moyoman.comm.client package is responsible for communicating with a client. The modules, which reside in the subpackages of org.moyoman.module, are where all of the move generation strategy code resides, and where the overwhelming amount of work by developers is expected to occur.

org.moyoman.framework package

Each Controller object which is created corresponds to one player of a game. The Moyoman server can have an arbitrary number of games being played at one time. Controller actually has two derived classes, GenerateController which is used for generating moves, and ValidateController, which is used for validating the moves of a player such as a person or an opponent playing remotely using a protocol such as GTP.

The Scheduler class is responsible for running the modules and generating a move. Modules are arranged in a DAG (directed acyclic graph). A module is run until it has completed its work. Then, any modules which were dependent on its output are run. Each time that a module completes its analysis, the Scheduler class determines whether there are any other modules which can be started because all of their prerequisite modules have completed. If so, that module is started, and passed an array of Module objects which which it had requested as input. These Module objects are clones of the originals so that the module is free to change their state. Scheduler has a generateMove() method and a makeMove() method. The generateMove() method gets the move from the server. The makeMove() method informs the module of the move that was actually made, so if the module saves state after each move, it can update itself.

The FSPersister class is responsible for loading and saving the state of the game using Java serialization.

org.moyoman.module package

All modules must extend the Module abstract class. Each module must perform certain tasks, such as generating a move, returning debug information, etc. In addition to extending the Module class, each module implementation must implement exactly one module interface. These interfaces are in the package one level below org.moyoman.module. For example, the shape interface is the org.moyoman.module.shape.Shape interface. Implementations of modules are down one level further. For example, the org.moyoman.module.shape.simpleshape.SimpleShape class implements the Shape interface. There can be more than one implementation of a given module type. Information about which specific module implementation of a given type is actually run is contained in the moyoman/config directory. The modulename.properties, moduletype.properties, module_order, and module.xml files contain the relevant information for this. The user can configure this through the client using the tools under the Admin menu.

For the developer who is not interested in digging through the Moyoman code but just wants to contribute a module, the process is straightforward. Using the MiddleGame module as an example, the developer would create the org.moyoman.module.middlegame.mg1 package. He would create an MG1 class in that package which extends Module and implements MiddleGame. He would then implement the abstract methods of Module and all of the methods of MiddleGame, but there can be no additional public methods other than those methods. After this is done, the Module dialog window under the Admin menu can be used to make MG1 the MiddleGame module which is run. If no other MiddleGame modules have yet been created, then the SimpleMoveGenerator class would have to be edited as well. Around line 57, the mt array is created, and all of the module types used by the move generator are entered there. An additional entry would have to be added for middle game.

org.moyoman.comm.client package

This package is meant to be the interface between the Moyoman server and the outside world. The package could be linked in with a client to allow the Moyoman server to be accessed remotely, or protocols such as GTP over sockets could be added. Some additional work will be needed to support some of this functionality. The PlayerManager class is used to start a game of Go. Two objects which are subclasses of the abstract Player class are passed to the PlayerManager constructor. Player has two derived classes ValidatedPlayer and NonvalidatedPlayer. The ValidatedPlayer class is used by players such as MoyomanPlayer which have checked their move for legality, while NonvalidatedPlayer would be used by classes such as MousePlayer which take a move from the user. The CommandExecutor class is used for communicating with the framework package, specifically with the Controller object. The DirectCommandExecutor class is derived from CommandExecutor and makes direct method calls. Other classes could be implemented which derive from CommandExecutor for making remote network calls.