Overview

(documentation v.2)

The Sjambok API is designed to be a friendly, easy to use API for abstracting crossword puzzle games so that they may be used with a front end. Therefore, emphasis on data management, game specifics etc is emphasized in the engine. Data communication between front end and engine is accomplished through only two functions, whose parameters determine the kinds of data exchanged. The API as it currently is explained below. However, some information, such as number of players and their codes, is best accessed from sjmParameters.

The workhorse of the application will be the sjmEngine. It handles all move validation, data updates, and anything else the game needs to function. An application merely needs to process the user input a format palatable to the engine, and then send the information to it. Each instantiation of the engine represents a separate game; thus, multiple engines can be initialized to run multiple games at once. This could be useful as a sort of crossword games server. It currently can be initialized with sjmParameters, a class that carries initialization information. Once a saved game format is developed, the engine can create a new instance with a saved game. An engine will cleanly destruct; there are no shared variables between servers, and it relies on no global variables. Each function is explained below.

class sjmEngine
• sjmEngine(sjmParameters startup) - initializes an engine according to the sjmParameters, see sjmParameters for more detail
• sjmEngine(sjmParameters startup, char* filename) - initializes an engine according to a saved engine file and parameters; not yet implemented
• ~sjmEngine() - destructor of the engine
• SubmitMove(sjmMove* TheMove, char* result) - submit a player move to the engine
• RequestInfo(int request, void*& result) - submit a request for a piece of information, such as the board, game status, player score, etc. ptr returned must be cast to right data type

sjmMove is the communication medium by which player moves are sent. The player code is used so that players cannot impersonate each other; a hacked client could send a move with another player's id if it weren't randomized. The code is generated by sjmParameters. Before any kind of data should be set, the move type must first be set. The following move types are:

sjmMoveType
• NIL - the null move
• READY_TO_PLACE - locks a player into a move; this is so others have a chance to challenge
• PLAY_MOVE - If no one challenges, then the move can be played
• SCORE_MOVE - score a submitted move
• LOOKUP_WORD - allows a player to see if a word is in the dictionary (not implemented yet)
• SUGGEST_MOVE - lets a player see what the AI would do (not yet implemented)
• DISCARD_TILES - lets a player exchange his tiles, as long as there are enough in the bag
• RATE_MOVE - gives an AI rating of the move (not yet implemented)
• CHALLENGE_MOVE - after a player clears on READY_TO_PLACE, there can be a grace period where another can CHALLENGE
• PASS - player passes move; 6 passes results in game ending
• RESIGN - player can quit from game; if only one remains, he is the winner

class sjmMove
• sjmMove() - initializes a NIL move
• ~sjmMove() - destroys a move
• void setPlayerCode() - set the player code, so we know the origin of the move
• void setType(sjmMoveType set) - sets the type of move, as outlined above
• void setData(char* word) - put data pertinent to the move type into the move, such as a list of tiles to exchange, text of play, etc, specifics of data format for each type are discussed elsewhere
• void setXYZ(int* vector) - for a play involving a move on the board, set the coordinates
• void setDirection(int dir) - ditto, set the direction

sjmParameters is a class used to initialize a new sjmEngine. It provides a pointer to the dictionary, the board, the bag, and of course, play parameters and number of players. It also contains the code generation for the players.

class sjmParameters
• sjmParameters()
• sjmParameters(char* filename)
• ~sjmParameters()
• unsigned long int GenerateCode(int index)
• int getGeneratedCode(int index) - sjmParameters should store the randomly generated code; when the application needs to correlate a code to a player identity, it should use this function
• int getNumPlayers()
• scr_Bag* getBag()
• scr_Board* getBoard()
• scr_Dictionary* getDictionary()

The listing above does not list everything in the API so far; only what has been definitely frozen. Please give me feedback I know it is very vague, but within a few weeks, it will all be made crystal clear.