Generic Collectible Card Game

[I’m writing this document in somewhat randomly selected order. If you have topics you eagerly wish learn, then ask me. I might write them next.]

Contents

Cannot read Table of Contents

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