Generic Collectible Card Game

Contents

1. Introduction
1.1. What is it?
1.2. Architecture
2. Client
2.1. Keyboard and mouse
2.2. Extensions for Mtg
2.3. Extensions for Pokemon
2.4. Extensions for Metw
2.5. Client command reference
3. Server
3.1. Rules definition file
3.2. Setting up a game server(s)
3.2.1. Setting up an additional table(s)
3.2.2. Creating a table with own rules
3.3. Setting up the whole system manually
3.3.1. Fine tuning
3.4. Tools for server adminstration
3.5. Adminstrator’s tasks
3.5.1. Roles
4. Internals
4.1. Dependent and independent parts
4.2. Boot sequence
4.2.1. Client boot sequence
4.2.2. Server boot sequence
4.3. Text formatting
4.3.1. General tags
4.3.2. Mtg specific tags
4.3.3. Metw specific tags
4.3.4. Pokemon specific tags
5. Scripting language
5.1. Syntax
5.1.1. Atomic data types
5.1.2. Expressions
5.1.3. Control flow
5.1.4. Defining own functions
5.1.5. Local variables
5.2. Function reference
5.2.1. Common client and server functions
5.2.2. Core functions (C++)
5.2.3. GUI library (C++)
5.2.4. Game data library (C++)
5.2.5. General client functions
5.2.6. General factory server functions
5.2.7. General game server functions
5.2.8. General meta server functions
5.2.9. General server functions (C++)
5.2.10. Lotr specific client functions
5.2.11. Lotr specific factory server functions
5.2.12. Lotr specific game server functions
5.2.13. Metw specific client functions
5.2.14. Metw specific common client and server functions
5.2.15. Metw specific factory server functions
5.2.16. Metw specific game server functions
5.2.17. Metw specific meta server functions
5.2.18. Mtg specific client functions
5.2.19. Mtg specific common client and server functions
5.2.20. Mtg specific factory server functions
5.2.21. Mtg specific game server functions
5.2.22. Mtg specific meta server functions
5.2.23. Net library (C++)
5.2.24. Pokemon specific client functions
5.2.25. Pokemon specific factory server functions
5.2.26. Pokemon specific game server functions
6. Implementing games using Gccg
6.1. Planning and preparations
6.2. Beginning of the hard work is easy
6.3. Basics of XML files
6.4. First Gccg-script
6.5. Creating set definition files
6.6. Setting up factory server
6.7. Setting up meta server
6.8. Details of game defining XML
6.9. Card placement algorithm

1. Introduction

1.1. What is it?

1.2. Architecture

The server system is a cluster of servers possibly distributed to several hosts. The center of the gaming system is the meta server, which is the place where clients connect to in first place. The meta server acts as a chat room and is also responsible for keeping track of players’ collections as well as all card and money transactions. The meta server is supported by one or more other servers.

Only obligatory additional server is the factory server, which serves as booster generator for meta server. The reasoning behind this server split is that the meta server does not have any knowledge of cards. It just uses simple integers to denote cards and product codes to denote different boosters and starters available. When the meta server sends amount of product and it’s product code, the factory server then generates list of (not necessarily) random integers presenting the product matching the product code. The generation process simulates actual rarity distribution of the product ordered.

When a single game server is launched, it connects to the meta server specified by it’s configuration. When a connection is established, the new server process appears as a table in the chat room. Players can see the operating parameters (such as bet and number of players required) of the game server on their screens. After initialization, the game server sleeps until the meta server awakes it by sending a message to initiate a game. After specified number of players are connected, the game begins and the game server process the whole game until the result of the game is declared. The declared game result is then sent to the meta server and the game server quits. Usually game servers are configured to start over again.

2. Client

2.1. Keyboard and mouse

2.2. Extensions for Mtg

2.3. Extensions for Pokemon

2.4. Extensions for Metw

2.5. Client command reference

/addproduct n id t prc
Mode: Chat mode
Restrictions: God and Salesman only
This command adds one product for sale. The ordering code of the product is 'id t', where id is the abbreviation of the card set and t is the type of the product ('booster', 'starter', etc.). The ordering code is a string which describes the product for the factory server. Number of the sale items available is n and the price of them is prc apiece.

/away text
Mode: Chat mode
Marks you as away from the keyboard with the given text as an explantion. Without any arguments, removes away status.

/ban player
Mode: Chat mode
Restrictions: God and Guard only
Without any arguments, this command lists all banned users. Adding one or more player nicks as arguments, this commands adds them to the ban list. When a player is banned, he cannot login in to the game anymore. Additionally, if the banned player is online when this command is issued, he is kicked automatically from the server. See also /help restrict and /help unban.

/bans
Mode: Chat mode
This command lists all banned users and restricted domains.

/bid bid
Mode: Play mode
Simple auction system works as follows: each player places their bids using this command. The bid can be any text. When each player has placed their bids, the auction results are displayed and book-keeping for bidding is reseted to be ready for next bidding.

/bind text
Mode: Any mode
Without any arguments, show a listing of all bindings. Otherwise, wait for a key press. After that, bind the given text to the key pressed. When the key with a binding is pressed, current input line is stored temporarily, the bound text is then put to the input line and return-key is pressed automatically. After that the content of the old input line is restored. See also /help bindk and /help unbind.

/bindk text
Mode: Any mode
Without any arguments, show a listing of all key stroke bindings. Otherwise, wait for a key press. After that, bind the given text to the key pressed. When the key with a binding is pressed, the bound text is appended to the input line as single key press. See also /help bind and /help unbind.

/buy n product
Mode: Chat mode
This command buys one or more products, which can be listed using /products command. An optional argument n determines the number of products to buy. Default is one. A product can be given as an abbreviation instead of the full set name. The set name may be followed by an optional product type specifier, which defaults to 'booster' if not given. The product names are also case insensitive.

/copydeck name
Mode: Chat mode
Make an exact copy of the current deck if selected and name it to name. Selects the copy as the current deck. If there are no deck selected, this command does nothing.

/default r p
Mode: Chat mode
When selling a card first time without any competing offer, the price of the card is set to the default value. Each rarity has it's own default price, which is set when you sell the first card having the rarity in question. At that time you set the initial default value using number pad and enter. After that you can set the price p as default for rarity r using this command. Without arguments, this command lists current default prices by rarity.

/delgame
Mode: Play mode
Remove a saved game for the current group of players. This command should be applied to save disk space on a server, when the saved game is not needed anymore.

/delproduct id t
Mode: Chat mode
Restrictions: God and Salesman only
This command removes one product. The ordering code id t is the same as in /addproduct.

/display name
Mode: Any mode
When you have filtered and sorted your own custom display, you can save it for later use with this command. The name of the custom display appears at the end of the display selection list. If you want to destroy this display later, you can choose \"Destroy this display\" from the collection menu while the display is selected. See also /help select and /help sort.

/draw options
Mode: Play mode
Declare the result of the game to be a draw. If someone has already declared the result, new declaration overrides it. Optional arguments options are game specific.

/eval exp
Mode: Any mode
This command takes an expression exp and evaluates it using gccg-script engine. The resulting value of the expression is stored to the variable E. Expression can contain more than one statements separated by semicolon. The last semicolon should be omitted.

/faq entry
Mode: Chat mode
This command displays an entry using {cyan}cyan text and adds a line to the FAQ proposals. All proposals are examined manually and added to the FAQ if they are useful. Please add questions starting with Q: and answers starting with A:. Without arguments, show current proposals for the FAQ.

/find card_name
Mode: Any mode
Find a card having a name card_name. If exact name was not found, then search for cards with the name containing a text card_name. If found either way, show the collection if not already visible. Then turn to page containing the card found. If already in such page, search for the next page containing the card qualifying the search criteria.

/give player amount
Mode: Chat mode
Give an amount of money to the other player. The other player must be online and the amount must be greater than zero.

/giveticket u n s p
Mode: Chat mode
Restrictions: God, Salesman and Judge only
Give n free product tickects, each allowing to buy one product p of the set s without charge, to the player u.

/go table
Mode: Chat mode
This command allows you to sit down to the table given as a table number. You can check available tables using /tables command.

/grant player1 player2
Mode: Chat mode
If the player2 is online, copy the password of player1 to the player2. Every player can grant his or her password to anybody, but only God can grant others' passwords. After the password is copied, the player2 who received the password, can log in as player1.

/have player
Mode: Chat mode
Asks the meta server for the have list of the given player. The have list contains all cards which you have marked as wanted and which are put for sale by the player.

/help topic
Mode: Any mode
Show information about the given topic. If there are no such topic, then all card names are checked against and if a match is found, then the card data of the mathed card is shown. Without arguments, show the list of available topics.

/inplay
Mode: Play mode
List all cards on table sorted by the owner of the card.

/join
Mode: Chat mode
Toggle your play/watch status. If you are sitting on table without the ongoing game, you will join to the game. If the number of players is sufficient, the game begins. If you join to the game that has already started, you will watch the game. This command also cancels 'ready to play' status, if already joined, but the game has not yet started.

/kick player
Mode: Chat mode
Restrictions: God and Guard only
This command forces disconnection for player.

/kicktable tblnum
Mode: Chat mode
Restrictions: God and Guard only
This command forces disconnection for table tblnum.

/legal
Mode: Play mode
This command asks the game server to report more detailed information on the legality of the current play deck. The deck is checked against all game formats defined and the report of violations against each format is generated.

/loadgame
Mode: Play mode
Searches if there is a saved game for current player(s) and restores it, if found. Note that you must be playing at the same server, where you saved your game - not necessarily at the same table. The game server announces at the beginning of the game, if there is a saved game available for your play group. Restoring the saved game does not remove it from the server; see also /help delgame.

/loadimages
Mode: Any mode
Normally all card images are loaded or generated on demand. This may cause unwanted delays when turning pages of the collection. This command loads all images at once.

/me text
Mode: Any mode
Send an emote string to the server, which replies it as an action made by you.

/newdeck deckname
Mode: Chat mode
Create an empty deck with the given deckname and select it as the current deck. Opens up the deck editing list automatically. The deck is saved automatically after the editing list is closed

/ok
Mode: Play mode
Give your acceptance to the declared result. After all players have accepted the declared result, the game ends and meta server will update all game depended statistics accordingly.

/payall amount
Mode: Chat mode
Restrictions: God only
Add the given amount of money to every player.

/products
Mode: Chat mode
List the quantity and the price of each product for sale.

/quit
Mode: Any mode
If you are watching or playing, leave the game and return to the chat mode. Otherwise, save decks and other client-side data and close the server connection. After that, quit.

/rd
Mode: Chat mode
Send the content of the current deck to the meta server for registration. The meta server stores a copy of the deck. After you have registered your deck, game servers check your game decks against the registered deck. Then reports are generated wether the game deck is identical to the registered deck and/or wether the combined parts of the game deck contains the same cards as the registered one. NOTE: The game servers do not report anything if the deck is not registered. So, it is up to the player to observe that an opponent haven't change his deck during tournament event. See also /help ro.

/reboot
Mode: Chat mode
Restrictions: God only
Send Quit-message to all players and game servers. After that, reboot the meta server.

/refresh
Mode: Any mode
Ask full refresh of the collection status from server. Normally the collection state is stored on disk cache and may be not accurate if you have been offline.

/register set
Mode: Chat mode
If the player has collected all cards of the set, he or she is awarded by a bonus. The bonus is $0.1 per individual card in the set. If the player has not yet collected all cards, the number of missing cards is announced. The set must be given as an abbreviation of the card set (case insensitive). If the abbreviation is not valid, the list of valid abbreviations are shown.

/removeuser player
Mode: Chat mode
Restrictions: God only
This command deletes all data of player.

/renamedeck name
Mode: Chat mode
Give new name to the current deck if selected. If there are no deck selected, this command does nothing.

/reproduce
Mode: Chat mode
Restrictions: God and Salesman only
Check all products. If there is a sold out product, then add a shipment of product with halved availability (compared to the previous shipment) and price increased by 10%.

/restrict domain
Mode: Chat mode
Restrictions: God and Guard only
Without any arguments, this command lists all restrictions currently in effect. Domain name can be exact or it can contain * as a joker character, for example *.cheaters.com. When the restriction is added to the domain, all existing players can connect but new players are not accepted any more. They get a message explaining the situation and how to get an account by email from the server administrator. See also /help ban and /help unrestrict.

/ro
Mode: Chat mode
You can retrieve the original composiotion of the registered deck with this command. Be careful when using this command, since it overwrites your current deck with the content of the registered deck. See also /help rd.

/rtfm
Mode: Any mode
Show a link http://gccg.sf.net/faq.php for newbies. Optional arguments are added after the link in parenthesis, e.g. section number to check out.

/save
Mode: Chat mode
This command saves all client-side data to the directory ~/.gccg/Game/. It also sends an advise to the server to save all important data.

/savegame
Mode: Play mode
Saves your current game status to the disk in the game server. Each player, player pair, player triple, etc. have one personal save file, which is overwritten each time using this command. Saving the game does not end it, but you can declare undecided result and continue later using /loadgame. This command is automatically applied when one of the players' network connection dies. See also /help delgame.

/sealed args
Mode: Chat mode
The sealed deck game is based on alter egos of players. To initiate an sealed deck event, you must first transfer an amount of money to the sealed deck alter ego of your player character. This is accomplished by the command /sealed <n>, where <n> is the amount of money to start with. Tha cards and money already owned by the sealed deck alter ego, is not lost. The money is added to instead. The command also switches to the sealed deck character immediately. If you want to switch between your normal character and the sealed deck character, you can say /sealed without any arguments. To transfer all cards and money back to your main character, say /sealed end.

/select exp
Mode: Any mode
You can refine your collection view by applying subsequent selects. Each select expression checks every card from the current display and drops those cards not matching the filter expression exp. The filter expression is one of the following:
   <e1> rel <e2> - comparison where rel is =, >, <, !=, <= or >=
   <e1> op <e2> - mathematical expression where op is +, -, *, or /
   (e) - parenthesis alters precedence
   <e1> has <e2> - true if e2 is a substring of e1 (comparison case independent)
   not <e> - negate expression e
   <e1> and <e2> - true if both expressions are true
   <e1> or <e2> - true if either expressions is true
   <attr> - "

/set var value
Mode: Chat mode
Without arguments, this command lists all options currenlty set. Otherwise it can be used to fine tune operating parameters of the client or the server. All settings are offered to the server. If the server accepts the setting, i.e. the given variable var is meaningful to the server, then the server side option is set to value. In any case, client-side option is set to the value. The list of client-side options follows:
   nosound <s> - if set to 'yes', play no sound when game begins
   log <s> - if set to 'yes', print messages to stdout.
   trade_limit <n> - if you own more than n copies of the given card, consider these extra cards as tradeable (default 4)
   price 'higher'/'lower'/'same'/'default' - when selling first card or pressing enter, choose price according to this setting (default 'higher')
  The list of server-side options:
   avatar <image> - choose an image presenting you (see graphics/avatar)
   email <s> - set your email address shown by /whois command to s
   plan <s> - set additional information shown by /whois command to s
   realname <s> - set your real name shown by /whois command to s
  

/sort [n] k1 k2 ...
Mode: Any mode
Sort the current collection view according to one or more sort keys k1, k2, etc. Each key is one of the following: name of the card attribute, age as age of the set, name as name of the card, or set as name of the set card belongs. The valid card attributes are "+

/su user
Mode: Chat mode
This command closes current session and begins new one with a player account user. You must have already registered the account.

/tables
Mode: Chat mode
Show a list of game servers available. The list contains IP-addresses, ports and game parameters (number of players, bet) of each game server.

/time time message
Mode: Chat mode
Restrictions: Judge only
Adds a timer for calling time limits in a tournament. When this command is issued, the Judge yells 'time minutes until message'. Then it announces half time (if the limit is more than 19 minutes) and 5 minutes before the limit (if the limit is more than 5 minutes). Finally the end of the time limit is called.

/unban player
Mode: Chat mode
Restrictions: God and Guard only
Remove a player from the ban list. See also /help ban.

/unbind
Mode: Any mode
Waits for a key press. If the key pressed has a binding (see. /bind), remove the binding.

/undecided
Mode: Play mode
Declare that the game is not played to the final result. If someone has already declared the result, new declaration overrides it.

/unrestrict domain
Mode: Chat mode
Restrictions: God and Guard only
Remove a domain from the restriction list. See also /help restrict.

/unset var
Mode: Chat mode
This command removes the current setting of var.

/users pattern
Mode: Chat mode
Show list of all users matching wildcard pattern or all users if not given. The total number of users matching is shown instead if the list is too long.

/want player
Mode: Chat mode
Asks the meta server for the want list of the given player. The have list contains all cards which he or she have marked as wanted. The cards you have for sale or you have more than trade_limit, are shown in green.

/who
Mode: Chat mode
Show a list of all players and their ip-addresses, who are currently connected to the meta server.

/whois player
Mode: Chat mode
Ask the meta server to describe a player. The personal data (realname, email, plan) set by the player is shown as well as his/her wealth and game play history.

/win options
Mode: Play mode
Declare yourself as a winner of the game. If someone has already declared the result, new declaration overrides it. Optional arguments options are game specific.

/yell message
Mode: Chat mode
This command echoes a message to all players, even those who are currently playing.

3. Server

3.1. Rules definition file

Game name of the game
Info short description
Format name of the format
Rules for deck component
rules...
	

The deck checking works as follows. A set of rules is applied to each deck part (or to the combined set of all cards). Each limiting rule removes matching cards from the part under the examination. If there are any cards left after applying every limiting rule, the deck part is not legal. There are also check-rules that do not alter the deck part in any way, but checks some general principle. In short, the order of the rules is important.

The following rules are recognized:

Size min-max
	

Size n1,...,nk
	

Limit n
card name 1
card name 2 ...
	

Limit any
card name 1
card name 2 ...
	

General limit n
	

Otherwise ok
	

Set s limit n
	

Limit n for each card having e
	

Limit n cards having e
	

Check ’text’ using e
	

Game Pokemon
Format Tournament
Rules for deck

Size 60-60

Limit any

Fighting Energy
Grass Energy
Fire Energy
Lightning Energy
Water Energy
Psychic Energy

General limit 4

Otherwise ok

3.2. Setting up a game server(s)

3.2.1. Setting up an additional table(s)

1. Install binary package (or source and compile it) for your platform to have program called ccg_server.
2. Then install the game module, the server module and the game specific server module
   ./gccg_package i game server game-server
3. Launch your server for p players and connect it to the meta server meta
   ./Server --server meta --bet bet --players p game
   Without --server argument, the game server registers itself to the default meta server. Default bet is $1 and default number of players is one.
4. Don’t forget to open appropriate incoming TCP/IP ports at your firewall if blocked by default.

3.2.2. Creating a table with own rules

The package contains subdirectory data/, where you can find examples of format definitions, each having .rules extension. Pick one of the examples which resembles your upcoming game format mostly and copy it to new name. Then edit it to implement your game format and convert it to Gccg-script by issuing command
make rules
The command reads all rules defintions having extension .rules found at data/ directory and converts them putting results to the directory script/.

Now rules are ready for testing (assume that our rule set is called Mtg-block.rules which comes with the dev-tools). Try one player table issuing
./Server --rules Mtg-block.rules mtg
Don’t forget to add --server argument if using other meta server than default one.

3.3. Setting up the whole system manually

1. Lauch the factory server for your game
   ./Server factory-game
2. Lauch the meta server for your game
   ./Server meta-game
3. You should be now able to log in to your own meta server. Try your client
   ./Game --server your.server
4. Launch game servers you need as described in earlier subsection. Remember to add --server argument or otherwise the game server(s) connects to the default meta server.

3.3.1. Fine tuning

TIME_ZONE

This variable is announced to clients in certain situations where the local server-side time zone is needed.

INITIAL_MONEY

This is the minimum of the starting money given to the each new player.

AMOUNT_TO_PAY_WEEKLY

This is weekly payment. Together with the previous variable this defines the total number of money to be given to the new player. The exact formula is

INITIAL_MONEY + AMOUNT_TO_PAY_WEEKLY x p,

where p is the number of products available at the time of registration.

PRIZE_PER_PLAYER

This defines additional bonus to be given to the player winning a match. The formula for earnigs for the winning player is

(p - 1) x (b + PRIZE_PER_PLAYER) + (p x b),

where p is the number of players, b is the bet at the table used. In short, PRIZE_PER_PLAYER tells how much one player receives when playing against one opponent with $0 bet.

3.4. Tools for server adminstration

[Descripe other scripts.]

3.5. Adminstrator’s tasks

3.5.1. Roles

God

This account have full access to everything. With this account you can give any amount of money (even negative) to anybody and the amount is not subtracted from this account. You can give cards without owning them. Any password can be granted to anybody, whereas usually players can grant only their own passwords.

Guard

This account can kick people out of the chat room.

Judge

Reserved for future.

Salesman

This account is now obsolete, but it still can do product management with /addproduct and /reproduce.

root

This has no special meaning in Gccg, but reserving the root account prevents stupid people to log in directly from root account.

4. Internals

4.1. Dependent and independent parts

[Table: script files]

4.2. Boot sequence

4.2.1. Client boot sequence

4.2.2. Server boot sequence

4.3. Text formatting

4.3.1. General tags

4.3.2. Mtg specific tags

4.3.3. Metw specific tags

4.3.4. Pokemon specific tags

5. Scripting language

5.1. Syntax

5.1.1. Atomic data types

null

Empty value which can be expressed explicitly using NULL or ().

integer

Any integer value supported by C++ compiler.

real

Any real value supported by C++ compiler.

string

A sequence of characters beginning and ending with " or ’. If the sequence is enclosed in ", the special sequence \n is converted to the new line and the sequence \c to the character c.

list

An ordered sequence of any other objects. The sequence begins with ( and ends with ) and elements are separated by commas. An empty list is denoted by (,) and a list with one member is denoted by (e,), where e is the member of the list.

5.1.2. Expressions

atomic

Any atomic value evaluates to itself.

variable

A legal variable name can have one or more following characters: a...z, A...Z, 0...9, _ and .. A digit cannot be the first character of the variable name and NULL is forbidden as a variable name. Variable evaluates to it’s current value if set. If not set, then it evaluates to NULL.

array

The language does not have separate array type. However, list variables can be used as arrays. If a=(a₀,a₁,...,a_n-1) is a list, we can use notation a[i] as a reference to a_i. This notation can be nested like a[i][j], i.e lists of lists represents 2–dimensional array. Access time is constant. List indexing can be also used after any expression in parenthesis, e.g. (seq(1,5))[i].

dictionary

Dictionary type is also a special kind of list, which contains key–value pairs. Each member of the dictionary is a list with two members: (key,value). Dictionary must be initialized as an empty list, i.e. d=(,). After that each reference of form var{key} creates new pair (key,NULL) if necessary. If there is already correct key, then value corresponding to the key is returned. Dictionary indexing can also be used after expression in parenthesis like array indexing.

negation

Value of an expression -e is a negation of e if e is a number. Otherwise Parser::LangErr is thrown.

addition

Value of an expression e₁+e₂ is a concatenation of lists if both e₁ and e₂ are lists. If both are numbers, then value is the sum of those numbers. If one is an integer and other is a real, then answer is given as a real number. If one of the arguments is a string, then result is concatenation of the string and the other expression converted to string.

subtraction

An expression e₁-e₂ is a short hand notation for e₁+(-e₂) except for lists. If both arguments are list, the result is a list containing all members of e₁ which do not belong to e₂.

multiplication

An expression e₁*e₂ evaluates to e₁ x e₂ if both are numbers. If one is a number n and other is a string or a list, then the string or list is catenated with itself n times. If both operands are lists with the same size, then return value is a list containing pairwise multiplied elements of e₁ and e₂. Otherwise Parser::LangErr is thrown.

division

An expression e₁ / e₂ evaluates to the integer part of e₁/e₂ if both are integers. If either or both are real, the result of operation is e₁/e₂. Otherwise Parser::LangErr is thrown.

modulo

An expression e₁ % e₂ evaluates to remainder of division e₁/e₂ if both are integers. If either one is NULL, return NULL. Otherwise Parser::LangErr is thrown.

function call

Function call f(e) calls an user defined function if available. Otherwise an internal function is called. Function call evaluates to the value returned by the function.

substitution

Values can be assigned to variables with expression v=e, where v is a valid variable name. The substitution evaluates to e.

relation

Two expression can be compared with traditional operators ==, !=, <, >, <= and >=. Each of these operators returns 1, if relation is true and 0 otherwise. Relation is valid ordering and can be used with any type. When both operands are NULL, equality operator returns 1. If one of the operands is NULL and the other is not, equality operator returns 0. List operands are considered equal if they have same length and they have same members in same order. Operator != is a short hand notation for not e₁ == e₂.

logical

Operators &&, ! and || can be used. The !–operator returns 1 except when argument is non–zero integer or non–zero real. Other operators returns NULL if any argument is NULL. If both arguments are integers, then logical value 1 or 0 is returned. In any other case Parser::LangErr is thrown.

5.1.3. Control flow

for(i)(10)
{
  if(i % 2==0)
  {
    j=i;
    while(j)
      print(j=j-1);
    println("");
  }
}
	  

10
3210
543210
76543210
	  

5.1.4. Defining own functions

def increment
{
  return(ARG+1);
}
	  

NOTE 1: The return-statement do not terminate the execution of the function. You can set the return value more than once and the last call to return takes precedence.

NOTE 2: The function can be defined more than once. New definition overwrites older definition.

NOTE 3: Function definitions can be introduced anywhere in the code, even inside loops or if-else constructions.

5.1.5. Local variables

#
# foo(n,e) - evaluates n times expression e
#
def foo
{
  push(a);
  a=seq(1,ARG[0]);
  forall(ARG[1],a);
  a=pop();
}
	  

5.2. Function reference

5.2.1. Common client and server functions

5.2.2. Core functions (C++)

5.2.3. GUI library (C++)

5.2.4. Game data library (C++)

5.2.5. General client functions

5.2.6. General factory server functions

5.2.7. General game server functions

5.2.8. General meta server functions

5.2.9. General server functions (C++)

5.2.10. Lotr specific client functions

5.2.11. Lotr specific factory server functions

5.2.12. Lotr specific game server functions

5.2.13. Metw specific client functions

5.2.14. Metw specific common client and server functions

5.2.15. Metw specific factory server functions

5.2.16. Metw specific game server functions

5.2.17. Metw specific meta server functions

5.2.18. Mtg specific client functions

5.2.19. Mtg specific common client and server functions

5.2.20. Mtg specific factory server functions

5.2.21. Mtg specific game server functions

5.2.22. Mtg specific meta server functions

5.2.23. Net library (C++)

5.2.24. Pokemon specific client functions

5.2.25. Pokemon specific factory server functions

5.2.26. Pokemon specific game server functions

6. Implementing games using Gccg

6.1. Planning and preparations

Before starting a concrete work on a game project, you must collect some knowledge and material. You should be very familiar with the traditional conventions and rules of the game under implementation. Also, it would be very fruitful for the speed of the development, if you have at least basic knowledge for several other games already implemented under Gccg. When accomplishing each task a developer with large knowledge base can select the existing game with the most resemblance with respect to the task under work. If lucky, you can use lot of existing material as source.

Following information must be collected as a preparation for the project:

• Choose a short name for the game. It should be different to all existing games and usable as a part of a filename. You should also try to choose a short name, which is not trademarked.
• List of all cards that exist in the game. This list must contain at least the card name and it’s rarity distribution. You must also find out all rarities and assign one letter to denote each rarity. You also need packing information of each product for sale.
• Decide additional card data needed. At least you need all information which is relevant to the location algorithm. Usually some kind of the card type is used to decide where to put a card when played on table. However, the best possible solution is to provide all card data, because unused data can be used as reference during play.
• Choose a source(s) for data and acquire documents needed. Usually some kind of a spoiler list is enough. Ensure that the spoiler list contain all data you need and the information given is correct. Sometimes it is useful to use two different spoilers and make some kind of cross validation between the two, since there are almost always errors. In the worst case, you may use original cards and do a lot of hand work.
• Reserve port numbers for your game (see Table 7.) from the author. In principle any ports can be used, but organizing default port numbers makes life easier when someone wants to establish several servers.

This documentation is written to Unix-environment. Fortunately there is an excellent collection of Unix tools for Windows called Cygwin. You should install Cygwin if using Windows. [What packages are needed for Cygwin?] Then the most of this document applies also to the Cygwin environment. In addition to the decent working environment, you need to install at least binary packages (or compile from source) for your platform and the following packages: client, fonts, server and dev-tools. It is also highly recommended that you install all games you know including server packages. These can help you a lot, when you can peek how things are done in the game you are familiar with.

6.2. Beginning of the hard work is easy

6.3. Basics of XML files

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE ccg SYSTEM "gccg-game.dtd">

<ccg name="Collectible Poker" dir="Poker">
  <option name="hand card size" value="50"/>
  <option name="table card size" value="50"/>
  <option name="deck card size" value="50"/>
  <option name="book card size" value="50"/>
  <cardset source="poker_basecards.xml"/>
</ccg>

The structure of the game definition file is simple. Everything is stored inside tag ccg, which have two attributes, the full name of the game and the short name of the game. Everything else is given in any order using couple of predefined tags. In above example, we introduced option tag which have two attributes: name of the option and it’s value. The options above determines the size of cards used in several places in the client. The values are percentage of the size with respect to our card background image. So, in the example, we decided that cards in the hand, in the deck, in the collection or on the table have their sizes halved. After the options, there is a tag pointing to a set definition file. The cardset tag determines which set definition files to load on startup.

The set definition file specifies a list of cards in some order. The order determines one-to-one mapping between card numbers and card names. The first card of the first set definition file given in the game definition file is a card number zero. After that, each card gets next integer in sequence and this numbering continues through every set definition file specified in the game definition file. The card number zero has a special meaning. It represents the back side image of cards. Additionally, the first set definition file does not specify any real cards. It is reserved for card backs and other special objects needed.

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE ccg-setinfo SYSTEM "../gccg-set.dtd">
<ccg-setinfo name="" game="Collectible Poker">

  <cards>
    <card name="A Card" text="" graphics="back.jpg">
    </card>
    <card name="_unknown_" text="" graphics="">
    </card>
    <card name="_unknown_" text="" graphics="">
    </card>
  </cards>

</ccg-setinfo>

In the example above, we didn’t gave a name to our set (name attribute of ccg-setinfo tag). In that case, all cards from the nameless set definition file is considered special and they do not appear in players’ collection. Cards are listed in order inside cards tag. Each individual card is defined by card tag, which have attributes name, text and graphics. In the example, name attributes have a special value A Card denoting that the card does not have any meaningful name and _unknown for unused card slots. Attribute text contains the text of the card if any. The last attribute graphics points to the image representing the card. The images are searched from graphics/Game/ directory, unless the set definition file specifies different directory (see Section 6.5.). The example above sets image for the card number zero, i.e. the backside of cards. After the zero-card, there are cards 1 and 2 reserved for future. The number of reserved cards should be decided now to be big enough, since it ruins everything if card numbers changes later. If adding one card here, it shifts all the rest card numbers by one and every old server and client are incompatible thereafter.

6.4. First Gccg-script

# VARIABLES
# =========

HANDSIZE=5;
DECKBOX_SIZE=(20,220,110);
if(!port)
  port=29102;
product.image=(,);

# FUNCTIONS
# =========

def NewDeck
{
  return((("deck",(,)),));
}

def InitializeLocationTables
{
  rules.category=(,);
  rules.coordinate=(,);
}

def StartGame 
{
}

In the example above, we defined couple of variables and functions. Here is a description of variables:

HANDSIZE

This is the natural hand size for the game if any. Usually there are menu entries that allow directly transfer HANDSIZE number of cards from one target to another where appropriate.

DECKBOX_SIZE

This variable contains a triplet (w1, w2, w3), where each number is a width of the deck edit field in pixels. The first component w1 sets the width of the number of the cards field, w2 sets width for card names and w3 sets width of the card type field.

port

This is the default port number where to connect. We should check first that we don’t override port number given as an argument to the client.

product.image

This is a dictionary mapping product names to the corresponding product images under graphics/Game/. In the example we just defined an empty dictionary (which is the same as an empty list). If the image of a product is not found from this dictionary, the client uses graphics/unknown_booster.jpg instead.

NewDeck()

This functions takes no arguments and returns an empty deck structure. The decks are described as dictionary which maps deck name strings to the lists of integers representing card numbers in the deck part. In this case, we are satisfied with one part called deck and it’s content defaults to the empty list.

InitializeLocationTables()

The card placement algorithm is described in section 6.9. This is an initialization function, which fills rules for the location algorithm. We leave tables rules.category and rules.coordinate empty for now and discuss them later.

StartGame()

This function is called at the beginning of the each game and can contain initialization tasks and automated start up procedures at the beginning of the match.

Now we are ready for our first test launch. Just say
ccg_client game.xml
and client should start using our minimal set of definitions. Connection to the meta server will fail and there is not much to do. You can browse empty collection without any cards and quit.

6.5. Creating set definition files

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE ccg-setinfo SYSTEM "../gccg-set.dtd">
<ccg-setinfo name="Basic Deck" dir="BasicDeck"
  abbrev="BD" game="Collectible Poker">

  <cards>
    <card name="Red Joker" text="" graphics="rj.jpg">
       <attr key="rarity" value="V"/>
       <attr key="suit" value="any"/>
       <attr key="rank" value="any"/>
    </card>
    <card name="Black Joker" text="" graphics="bj.jpg">
       <attr key="rarity" value="V"/>
       <attr key="suit" value="any"/>
       <attr key="rank" value="any"/>
    </card>
    <card name="Ace of Spades" text="" graphics="as.jpg">
       <attr key="rarity" value="R"/>
       <attr key="suit" value="spades"/>
       <attr key="rank" value="ace"/>
    </card>
    <card name="King of Spades" text="" graphics="ks.jpg">
       <attr key="rarity" value="R"/>
       <attr key="suit" value="spades"/>
       <attr key="rank" value="king"/>
    </card>

    ...

    <card name="Three of Clubs" text="" graphics="3c.jpg">
       <attr key="rarity" value="C"/>
       <attr key="suit" value="clubs"/>
       <attr key="rank" value="3"/>
    </card>
    <card name="Two of Clubs" text="" graphics="2c.jpg">
       <attr key="rarity" value="C"/>
       <attr key="suit" value="clubs"/>
       <attr key="rank" value="2"/>
    </card>
  </cards>

</ccg-setinfo>

  ...
  <cardset source="poker_basecards.xml"/>
  <cardset source="basic_deck.xml"/>
  ...

The header tag ccg-setinfo introduced two new attributes. The attribute dir defines subdirectory for the set, which is used as source when looking for card images. In the example above, the full path of the image of King of Spades is thus graphics/Poker/BasicDeck/ks.jpg. The attribute abbrev is two letter abbreviation for the set, which is used in several places instead of the full set name. Each card now contains card property definitions. Each property is given by attr tag, which has two attributes: key and value. When a script needs to know an attribute of a card, it can call a function card_attr(a,n), where n is the number of the card and a is the attribute. If there is an attr mapping having key="a" defined in the set definition file, the value attribute is then returned; NULL otherwise. Only compulsory property for actual cards is rarity. It is one of the letters chosen to present rarities followed by optional probability weight, e.g. R2. For the sake of completeness, we mention that card tag can contain an attribute back, which defines the card number of the card. Default card back is zero card.

When your Perl converter works perfectly, you can update Makefile in data/ directory to help rebuilding of XML files. You should add your game to usage line and create an entry for your game, which builds all XML files needed. In principle, you need one line for each set
./game_spoil_to_xml.pl Game/set_spoiler.txt > ../xml/Game/set.xml
You can find examples from the existing data/Makefile.

Now it is time for second test launch. This time we can browse the collection having empty slots for cards. We can use Ctrl+H to view statistics of a card or zoom a computer generated default card image using Shift key. However, cards are in alphabetical order, which probably is not acceptable for the most of the games. See chapter 6.8. for more information.

6.6. Setting up factory server

if(!port)
  port=29103;

def InitDistributions
{
  distribution=(,);
  distribution{"BD"}=(,);
  distribution{"BD"}{"booster"}=((4,"C"),(2,"U"),(1,"R"));
}

We need to define following variables:

[wigy] gandalf:~ >telnet localhost 29103
Trying 127.0.0.1...
Connected to localhost.
Escape character is ’^]’.
(("BD",("Basic Deck",3,56)),)
(2,"BD","booster")
((42,14,37,13,48,7,44),(12,42,53,30,21,8,31))

Sometimes products cannot be constructed directly from the distribution information. When the product does not have clear "slots" for each rarity, we may need to code our own function. We can overwrite default behavior by defining function ProduceName, which is called when the server wants to construct any product called Name. We can refine even further, by defining function ProduceSet_Name, which is called when the server generates the specified product Name from the given Set.

  ...
  distribution{"BD"}{"booster"}=((4,"C"),(2,"U"),(1,"R"));
  distribution{"BD-V"}=(,);
  distribution{"BD-V"}{"booster"}=((4,"C"),(2,"U"),(1,"V"));
}

def ProduceBD_Booster
{
  if(random(100) < 20)
    return(RandomCardSet("BD",distribution{"BD-V"}{"booster"}));
  else
    return(RandomCardSet("BD",distribution{"BD"}{"booster"}));
}

6.7. Setting up meta server

if(!port)
  port=29102;
factory.port=29103;

PRIZE_PER_PLAYER=1.0;
INITIAL_MONEY=50.0;
AMOUNT_TO_PAY_WEEKLY=10.0;

if(!load("products"))
{
  products=(,);
  products{"Basic deck booster"}=(65536,3.9,("BD","booster"),65536);
  save("products");
}

Now it is time to test, if our server system is ready to sell products and manage collections. First we need to launch the factory server as described in the previous section and then launch the metaserver
./ccg_server --load meta-server.triggers game.xml
Now we can try our client to connect the meta server (don’t forget to add --server argument if necessary) and if succeeded, we are able to buy boosters, buy and sell cards, create decks and manage our want-lists. However, there are no card graphics yet but just simple blank skeletons having the name of the card and nothing else.

After testing you can shut down servers by simply pressing Ctrl+C. When receiving Ctrl+c or some other signal suggesting the end of excecution, the server saves it’s data and quits. You can look to the directory save/Game and there are all the non-static data of both servers.

6.8. Details of game defining XML

6.9. Card placement algorithm

• Write rest of xml/game.xml file.
• Copy and update client scripts.
• Update Server script.
  • add game name to usage line.
  • add handlers for cases meta-game, factory-game and game.
• Write rest of scripts/game.include file.
• Now client should be able to join chat, to buy boosters and to create decks.
• Define drawing hints in xml/game.xml
• Write scripts/game-server.triggers
  • add necessary deck parts to SetUpPlayer
• Launch game server.
• Write necessary functions for client scripts/game.include
  • add deck locations: DeckpartLocation
• Update server scripts/server.functions
  • add visibility info to new deck parts visible.me, visible.opp
• Acquire card images.
• Create packages (packages.xml, revisions, build)
• Make sample decks