Board Game Arena - User contributions [en]

Create a game in BGA Studio: Complete Walkthrough

2022-01-20T07:56:21Z

Grandepezzin:

{{Studio_Framework_Navigation}}

== Introduction ==

This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using BGA Studio framework.

Before you read this material, you must:
* Read the overall presentations of the BGA [[Studio]].
* Some-what know the languages used by BGA Studio: PHP, SQL, HTML, CSS, Javascript
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]
* Create a game using one of the available tutorials. Don't bother with a new game if you have not completed at least one of the tutorials.

If you are stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].
If you're uncomfortable posting on the public forum you can send messages directly to developers who post answers on that forum but NOT the BGA admins.
If you find typos in this wiki - fix it.

== Select a First Game ==

For your first '''real''' game you must either
* Select a game from [https://en.studio.boardgamearena.com/licensing Available Licenses]
* Or from the Public Domain

But what if the game you want is not there? If you are able to successfully publish your first game, you would gain the trust of the BGA admins and they will be happy to assist you in obtaining a license for a game you really want to do or you can request a license yourself. You can read more about game licenses on [[BGA Game licenses]] page.

Once you selected the game but before creating a new project, please take a few seconds to check that someone is not already developing this game. If it is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

Even if you see a few projects with name of the game they may not be active. There are a lot of abandoned game projects. If it's not clear by the status, post to Developers forum asking if anybody is actively working on the project or send a message to the developers listed for the abandoned projects, and at the same time ask admins on the same forum post to send you graphics for that game if they have them (there a button on [https://en.studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but it will just send an email).

If your goal was to fix bugs in an existing project, first try to locate it on Studio, projects developed by BGA admins are not in the Studio. Then get read only access to the project and you can create your own as a copy of the existing one. Contact existing project admin about getting write access to the original project or if they are willing to take your patches - apply them.

If you want to take over an existing project first ask on the forum to see if project is abandoned, then get read only access (via project list) and see if this worth using it, if it has no code or graphics just start from the scratch, don't worry about project name it can be renamed later.

== Create a project ==

If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken use gamenameYOURINITIALS
template, i.e."heartsla". Don't worry too much about the name, if game would be good enough to be publish it will be renamed to original name.

Find and start the game in turn based mode, make sure it works.

Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a no-starter.

Update your project status in [http://en.studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for license" or "waiting for graphics" or combination of those.

== Development Tools ==

At some point you need to setup your development environment which consist of multiple tools, such as
* Editor or IDE
* Browser with dev tools
* File sync tools
* BGA Web tools
* Image manipulation tools
* Version control tools

Please scan though articles from [[Studio#BGA_Studio_user_guide]] especially related to debugging and tools, there is a lot of useful info there.

== Hook version control system ==

If it's a real game, I would commit the code to version control right at start. You are going to find yourself in the situation when the game does not even start anymore and there is no way of debugging it unless you have a way to revert. That is where version control becomes very handy.
If you don't know what I am talking about then at least back-up your files after each of major steps. Starting now.
You can also create a project on github, but make sure '''you don't commit original publisher graphics files''' and '''you don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).
You can (and should) also commit your modification periodically via Studio Control Panel.

== Obtain game graphics ==

If you developing a game from Available Licenses games, ask the admins to send you graphics by contacting studio@boardgamearena.com. While that request is being processed (it can take time, as it often requires some back and forth between the admins and the publishers) you can proceed to next step - project creation.

If you don't get original graphics you go to '''Scavenger Hunt'''

* If you developing a public domain card game you can borrow standard cards from BGA generic assets, see [[Common_board_game_elements_image_resources]]
* Standard game pieces - meeples, cubes, dice can be found here as well [[Common_board_game_elements_image_resources]]
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you lucky they also sometime have boards and token scans in "Game Pieces" section of Images
* If that fail google "boardgame <name>" and check Images section
* Get the rules PDF as well, there tools that allows you to extract graphics from PDF, which usually good for meeples, cubes and such (can use pdfimages command line tool)

Once you get the graphics one way or another you have to massage it to fit in the BGA criteria, which usually involves
* If publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down
* For non square tiles and game pieces you need transparency
* Usually you chop off scoring "ring" around the board of the game since scoring track not needed for online adaptation

More details about graphics requirements can be found here [[Game art: img directory]].

[[File:Rrr_search.png]]

== Obtain game documentation ==

Also at this time obtain a electronic copy of rules, such as PDF (English version).

Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such
as cheat-sheets (may be easier to get a data from these then trying to scrub pdf). You create and place them in the doc/ folder of the project then
exclude them from version control. There is also a misc/ folder now but it will hold up to 1 Mb of data files which would be checked in, so rules pdf's may not fit there.

== Update game infos and box graphics ==

Even it does not nothing yet start with making sure game looks descent in the game selector, meaning it has nice box graphics and information is correct.

For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].
What you would do for real game you would go to http://boardgamegeek.com find the game and use the information from web-site to fill the gameinfos.

The next step is to replace game_box.png with proper images, usually you can find all images including publisher logo on boardgamegeek website.

Details about images can be found here: [[Game art: img directory]].

Now important step. You have to LOAD these files in studio website through control panel. So go to Control Panel -> Manager Games -> YOURPROJECT
and press Reload for 'Reload game informations' and 'Reload game box image'

[[File:Gamepanel_sharedcode.png]]

Now try to start the game again. If you some-how introduced a syntax error in gameinfos file it may not actually work (game won't start).
Always use "Express Start" button to start the game. You should see a standard state prompt from template. You should see X players on the right, testdude0 .. testdudeX-1.
To switch between them press the red arrow button near their names, it will open another tab. This way you don't need to login and logout from multiple accounts!

== Fix source copyright ==

Now since you have your own project, you want put your name in the copyright header, so replace

© <Your name here> <Your email address here>
with
© John Snow <jsnow@gameofthrones.com>

Well not exactly this but whatever your real name is. For all files in project directory, its about 10 files. Make sure project still starts after that :)

== Reduce the Rules ==

Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of lack of patience or skill.
To keep sane, start the game with *reduced* rules and try to complete that first.

* If it has any expansions - do not even attempt to deal with them, not even - "I will just add graphics for them now and not use" - waste of time if you don't complete basic
* If it has advanced rules - start with basic rules only, i.e. "beginner game"
* If it has special rules for 2 player vs 4, start with most basic form (i.e. 4), restrict to 4 players
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)
* Any sort of rules that you think can be removed and not included in base - set aside for now
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later

== Design Game Elements ==
Technically game elements are already designed by board game designer but your job is to map it to program space.
Each physical piece (card, token, cube) will leave footprints all over the code (unfortunatly in multiple disconnected places).
To prepare the game you need to sort out these elements, i.e. categorize. I usually have to the following categorization (in object oriented view):
* Instance - all individual pieces are instances, i.e. two red cubes are two instances of 'red cube' type (class)
* Type - element type which distinctly represents that element in appearence (i.e. red cube is different type than blue cube)
* Super Type - one of more common types that similar properties (i.e. red OR cube)
* Player color - supertype specific for player color (sometimes there is no colors but like player 1 - but is conceptually the same, I use color because its easier to track)

Personally I like to encode my elements in string using reverse dns notation listing all the properties above, i.e.
meeple_ff0000_7 - this is instance #7 of type meeple_ff0000 (red meeple)
Or
card_yellow_magic_2 - this is instance #2 of yellow card (in this case yellow is color of deck not related to player color) that can do magic

So every game element would be in the

1. Database - instances. The db record would be something like
key|location|state
meeple_ff0000_7|slot_action_2|1
meeple_ff0000_2|tableau_ff0000|0
2. Material file - types and supertypes, we never need repeating info here, so never list individual instances but only types or supertypes, in this case we don't really need to define red meeple vs blue meeple
'meeple'=>{'name'=>totranslate('Meeple')}
3. Client (js, css, tpl, etc) - instances and types. For example my meeple will be like
<pre>
<div id="meeple_ff0000_7" class="meeple meeple_ff0000"></div>
</pre>
with .css something like
.meeple { background-image: url(img/tokens.png); width: 2em; height: 2em;}
.meeple_ff0000 {background-position: 20% 0%;}
4. Game php - setup and logic. During setup you have to generate all the pieces and place them in right positions. Also sometimes you need to reference elements to code the logic (I usually try to encode all rules in material file as much as possible)

For complex card games I think it is the best to keep all these info and rules in spreadsheet and generate other files such as material.inc.php.
See more info below about design of the individual layers.

== Create Initial Layout and Game Graphics ==

Mentally it is easier to start with game layout and graphics pieces. Even when nothing is working its give you moral satisfaction!

There are a few ways how the html could have been generated. You could have started with nothing and generate
it all by javascript, or you could have started with complete game markup in html and make javascript just hide and move pieces around. BGA framework also provides a third way, which is mix of both, plus a template engine to generate HTML using PHP. The only thing that is really annoying about the template engine is that you cannot put any translatable strings in the template (which means any visible text at all). If you are using the template approach all strings have to extracted as variables and injected through PHP (.view.php). This page explains the template engine in great detail:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].

The other disadvantage of the template engine is you cannot run and debug it locally, in the beginning of development it's a lot faster run off local pages,
you can do it with some trickery described here [[Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout|Tools and Tips for BGA Studio]]

During this step you have to decide what technical solutions you will be using, such as
* Use inline positioning of all moving pieces, controlled by JS. There are a few classes that already exist in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contain 200-300 pieces, it seems wrong but actually its faster to type all of this up in html/css when trying write than debug code for page generator.
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.

Start by creating and mapping all games assets, best way is probably to open rule book on "boardgame contents" page and go through every piece. Every pieces of boardgame would have its "print" in multiple files in your game:
* Some sort if "div" in html, where id of element match id of element in database (easiest way)
* Css for the element (either unique or for class), usually with background propery refering to part of sprite image
* Entry in material.inc.php referring to static properties of the element, i.e. name, tooltip, rules, etc
* Entry in .tpl file to represent static or initial location on the table OR creation template

Here are some specific examples:

'''Game Board'''

Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically
<pre>
<div id="board" class="board shadow board4p"> ... </div>
</pre>
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board whcih is diffrent than 2 ppl board)
<pre>
.board {
position: relative;
width: 980px;
height: 433px;
margin-bottom: 5px;
}

.board4p {
background-image: url(img/board4p.jpg);
}
</pre>
That would be pretty much it for the board itself, as it does not really need a tooltip so we don't need entry in material.inc.php

'''Game Board Slots'''

These are interactive areas on the board, usually illustrated as such. In most cases you can get away with rectangular shapes, but sometimes you have to create circle or oval shapes (and in really advanced case would be some svg paths). For slots you can do the following:

Entry in material.inc.php
<pre>
$this->token_types = array(
...
'slot_action_2' => array(
'type' => 'slot_action',
'name' => clienttranslate("2 Gray Track Advancements"),
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),
'o'=>"1,0,0,gg", // automatic rules
),
...
</pre>

Entry in template inside the "board" div
<pre>
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div>
</pre>

Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)
<pre>
.slot_action_2 {
top: 83px;
left: 37px;
}
.slot_action {
position: absolute;
width: 46px;
height: 26px;
padding: 9px 7px 6px 4px;
}
</pre>

'''Meeples''' - also cards, tokens, other mobile stuff

In CSS these guys will use "sprite" images with transparency, so it will look like this this:
<pre>
.meeple {
background-image: url(img/tokens.png);
width: 25px;
height: 25px;
}
.meeple_ff0000 { /* red */
background-position: 14% 0%;
}
</pre>
As for creation you can either generate them using template (where whole thing wrapped in template block and {COLOR} replace with all possible colors in .view.php
<pre>
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div>
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div>
...
</pre>

Or you can declare a template js var in .tpl file
<pre>
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom
</pre>
and create in js, like this
<pre>
var tokenDiv = this.format_block('jstpl_mepple', {
"color" : color,
"num" : i
}); // this in js code somewhere before placing it
</pre>
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.

When do you create dom element matching game element?
* If you have static layout you create it in .tpl file and its always there, but during initial setup or during notification it moved in proper spot (including "removed from the game" spot)
* If you dynamically generated pieces you create the element during notification, and sometimes during animation. Also don't forgot to hook event listener to it if its interactive.

One of the greatest parts about the web is all client side code can be viewed in your browser, so if you wondering how something is done in another BGA game just load the page and spy on it! In Chrome that would be right click and "Inspect Element". That would immediately show html of the given element alongside with css used for it (on the right). Another great way to learn is you can add yourself to any BGA project as read only from the project page!

So at the end of this stage you should complete the following (keeping in mind reduced rules/material for first iteration):
* Create a layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc
* Create css and html snippets for all game pieces: boards, tokens, meeples, etc. Place them all in initial template (even if they're not supposed to be visible at start). I.e. create fake player's hand with cards, put meeples on the board
* Hook layout to number of players and colors picked by the game and test with multiple players
* Figure out what you want to display in mini-player boards and hook it up
* Create material.inc.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements

If at this time you don't have graphics yet create pieces with just CSS, you can use shape, background color and object text using css ::after construct to fake the pieces.

[[File:Injected_text.png]]

== Hook Input and Animation ==

This step can be done before or after some of the server steps, or you go in iterations switching back and forward until you get it done, up to you.

At this time you want to hook clicking on pieces and buttons and provide some reaction, such of moving a piece. The handler code will be replaced later by the server hook, but at the beginning you want your game to be alive as early as possible.

Usually all pieces will be hooked to onclick during JS "setup" method, in addition if you create elements during server notification they have to be hooked up at that time.

You can play with animation effects you want put in place, in general all the pieces that move in real game should be moving, such as meeples, resources tokens/cubes, cards, vp tokens.
Regular piece animation is provided by BGA framework, but if you use html layout positioning not inline positioning you have to remove absolute positions (inline position styling) after each move. The set of functions for relative position token animation can found in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js

Also its a good idea to give player a visual cues on what game elements are clickable now, usually it will be a style, such as "active_slot", with visual effect of white dashed outline (outline is better then border, because border changes will make piece slightly move since it changes the size) or box-shadow (i.e. neon glow)

If you read [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] you know that you should not get carried away with animation, you are creating a board game not a video game... That also applies to sound effects (in general, you should not use any sounds effects beside already provided by framework).

See [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]] and [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.

== Create Database Schema ==

At some point you have to design your game database. Do it sooner then later since it would be harder to change it later, since some
code decisions would be based on that.

If you have grid-based abstract game use template from reversi, if you have a card game use template from hearts (the cards one also commented out in generated template for your project). The cards database goes with php class called [[Deck]].

In general make it as simple as possible.
Think about it, your game has 300 pieces (likely less). Using database to store this amount of data is like shooting a mosquito with a tank.
Anything more complex then one table with 5 columns or two tables will only going to make it harder to develop and not improve performance.
You can forget about normalising and any fancy stuff you learn about databases in school. String field for a primary key would be as fast as integer when we talking about this size of data. So don't over-optimize with trying to have integers field that have state based on bitmask!

Also remember that static (non dynamic) information about the game does not need to be stored in the database, that all include everything that does not change, i.e
all token/card properties such as name, tooltips, "strength", color, etc. This is stored in material.inc.php and server has access to it from anywhere, as well as client
if you send it with getAllDatas(). The only reason store some of it in database if it can affect your queries (i.e. type of token).

Usually design process will contain the following steps:
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model
* Mapping - now map real game to that model
* Encoding - now represent this model in database and material file with reasonable amount of fields

Example: '''The card game'''

* In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it
* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but as part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in your database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.
* The card state is very simple, it's usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position itself usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html
* For dynamic stuff we should try to reduce amount of fields we need, i.e. we need a field for card, so its one, we need to know what zone cards belong to, its 2, and we have possible few other fields, but if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Another Example: '''The euro game'''

See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]

So the piece mapping for non-grid based
games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here:
[https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php tokens.php].

<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

See [[Game database model: dbmodel.sql]] for details about editing the file.

Note: the simpler the database is the less debugging of db issues you have to deal with including database migration. The tokens database above - if you use it you never have to worry about migration because you don't need extra tables in 95% of the games.
Here are some example of how real games are mapped to such database:

'''Chess'''

- chess is grid base game and normally you would use positional columns, but just for the sake of argument, the chess game will look like this
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_white
|f3
|0
|-
|P_black_2
|c6
|0
|-
|K_black
|e8
|1
|}
And the state in this case indicated that kind was moved for example (which means castling cannot be performed)

'''Classic card game'''

Lets pretend we need 2 decks for that game
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_spades_1
|hand_ff0000
|0 /* state not used for hand */
|-
|10_hearts_2
|tableau_ff0000
|2 /* position */
|-
|10_hearts_1
|tableau_common
|1 /* face down */
|}

'''Eminent Domain (card game)'''

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|card_tech_23
|hand_ff0000
|0 /* state not used for hand */
|-
|card_planet_19
|tableau_ff0000
|1 /* face up */
|-
|reource_s_22 /* silicon */
|card_planet_19
|2 /* production state */
|-
|fighter_F_1
|tableau_ff0000
|0
|}

You can also look at other games that use Tokens database and access layer: Nippon, Dungeon Petz, Lewis & Clark, Battleship, Russian Railroads, Khronos

== Implement Game Setup ==

Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page
and implement these step by step populating the database (using db access API).
Game initialization is performed in php method setupNewGame, this method is called once when game table is created.
Game notifications cannot be sent during this time.

== Implement One time game model synchronisation ==

Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix getAllDatas function
to return all possible data we need to reconstruct the game. The template for getAllDatas already taking care of player info, but you
have to alter it to return all other data from database visible to the "current" player.

After that on the client side we should display this data, so in your .js file in setup function (which is the receiver of getAllDatas) you add calls that handle data send by server, usually by calling animation function such as "placeToken" or "placeCard".

== Create State Machine ==

Now you need to create a game state machine.

The state handling spread across 4 files, so you have to make sure all the pieces are connected together.
The state machine states.inc.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

Please first watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine]
and then please read [[Your game state machine: states.inc.php]].

Now the state machine should be relatively simple. If you find yourself with machine with more than 20 states its probably not the way to go.
Not all the player interactions need separate states, a lot of things can be implemented directly on client, i.e. if your player need to select
a reward token, which offers choice of resource, instead of two states on server just have one state on server and possible few states on client (client side states)
to collect this info.

== Handle Turn Order ==

If your game goes in clockwise order in natural sitting position nothing really needed you just use standard API and you are good. However if position is complecated
it may require some trickery.

Usually turn order is done by "game state" (see state machine above). Basically it would be two choices:
* Turn order depends on game situation (such as we take player with highest number of red cubes)
* Turn order is custom and assign on previos step - i.e. we not playing in clockwise order anymore. In this case you either need to extend player table with new order info (CANNOT use player_no column) or use order markers that come with game (i.e. marker_ff0000 on position_1). In this we can build player array in right order and pick next player based on previous player using existing helper function such as $this->createNextPlayerTable($player_ids)

== Implement Notification handling ==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications send by server.
So previously we hooked onclick js handler right to client animation, in real game its a two
step operation. When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].

Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want
to avoid sending data to server until step is complete (which may involve direct client side animation). See [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Selection|Multi-Step Interactions]]

Part of the sending notifications would be to update player's scoring, BGA uses standard control for score (on JS side), see [[Game_interface_logic:_yourgamename.js#Update_players_score|Update Player's Score]].

In BGA there is only two ways interact with the server (officially)
* Initial data dump - when JS client starts it gets all current data via setup() method
* Game actions - ajaxcall from client, it returns error or ok (not data), then server send butch of notifications to client

Note current ajaxcall is super vebosy and prone to errors, I suggest to use helper function. It does a lot of stuff you must do anyways.
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = []; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server

if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, its is optional param - you rarely need it
}
},
</pre>

When you insert a single action you have to update multiples files:
* in ggg.js add ajaxcall, i.e. something like
this.addActionButton('pass',_('Pass'),()=>this.ajaxcallwrapper('pass'));
* in states.php - add action 'pass' to list of possible actions
'possibleactions' => ['pass','playCard']
* in action.php - add action hander, see https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php
* in game.php - add action hander, there you must do the following
** call checkAction to validate the action
** possible do more game specific check to validate what player doing is legal (even its not possible from your js side - player can cheat - not allow that)
** do some database maniplations, using access api
** send notifications - this is the "reply" for action
** transition to new state (it very rare that user will remain in the same state, except for multi-active states)
* back to ggg.js add notification subsciption and notification handler (two separate things)

== Wrap Up ==

* Implement game progression (getGameProgression() in php)
* Implement Zombie turn (zombieTurn() in php)
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
* The games logs should explain what happened if player was not looking
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Make sure all UI strings are marked for translation
* UI elements which are images (i.e. tokens, cards) should have tooltips

== Alpha ==
When you think you game is completely working there is still bunch of stuff you have to do/check before telling admin that game is ready, please go though this [[Pre-release checklist]].

If you think its completely ready, let admin know (studio@boardgamearena.com) and it they will push it to alpha.

Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:
* Links to the rules (in multiple languages if available).
* Links to teaching videos.
* In the "On the web" section, links to:
** The official website for the game (if there is one).
** The BoardGameGeek page for the game.
* Consider writing a summary of the rules.

== Level Up ==

When you successfully created a basic game and you want more, it's time to make it fancy!

* Add game externtions and variants using gameoptions file
* Add user preferences for customizations
* Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs
* You can use fancy scoring board at the end of game instead of default nothing
* And finally super cool dice rolling, card flipping and victory points evaporating effects

Tutorial reversi

2022-01-20T05:27:16Z

Grandepezzin: /* The database */

{{Studio_Framework_Navigation}}

== Introduction ==

Using this tutorial, you can build a complete working game on the BGA environment: Reversi.

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]

== Create your first game ==

With the initial skeleton of code provided initially, you can already start a game from the BGA Studio. For now, we are going to work with one player only. Most of the time it is simpler to proceed with only one player during the early phase of development of your game, as it's easy and fast to start/stop games.

(If you choose to start with 2 players, you should see two names on the right: testdude0 and testdude1. To switch between them, press the red arrow button near their names; it will open another tab. This way you don't need to login and logout from multiple accounts.)

Reminder: Always use the "Express Start" button to start the game.

Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.

== Let it look like Reversi ==

It's always a good idea to start with a little bit of graphic work. Why? Because this helps to figure out how the final game will be, and issues that may appear later.

Be careful designing the layout of your game: you must always keep in mind that players with a 1024px screen width must be able to play. Usually, it means that the width of the play area can be 750px (in the worst case).

For Reversi, it's useless to have a 750x750px board - much too big, so we choose this one which fit perfectly (536x528):

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg are lighter than png, so faster to load. Later we are going to use PNGs for discs for transparency purpose.

Now, let's make it appear in our game:
* upload board.jpg in your "img/" directory.
* edit "reversi_reversi.tpl" to add a 'div' for your board.

Note: If you are building this game by following the tutorial, you will have a different project name than 'reversi'. The file names in your project will be different than shown in this tutorial, replacing 'reversi' with your project name. It should be trivial to find the right file in your project, but be sure that any code (other than comments) that references 'reversi' is changed to your actual project name.

<pre>
<div id="board">
</div>
</pre>

* edit your reversi.css file to transform it into a visible board:

#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
}

Refresh your page. Here's your board:

[[File:reversi1.jpg]]

If the board does not appear, check the image filename. Remember file names are case sensitive!

== Make the squares appear ==

Now, we need to create some invisible HTML elements where squares are. These elements will be used as position references for white and black discs.
We need 64 squares. To avoid writing 64 'div' elements on our template, we are going to use the "block" feature.

Let's modify our template like this:

<pre>
<div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>

</div>
</pre>

As you can see, we created a "square" block, with 4 variable elements: X, Y, LEFT and TOP. We are going to use this block 64 times during page load.

Let's do it in our "reversi.view.php" file, inside the build_page function:

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

Note: as you can see, squares in our "board.jpg" files do not have an exact width/height in pixels, and that's the reason we are using floating point numbers here.

Now, to finish our work and check if everything works fine, we are going to style our square a little bit in our CSS stylesheet:

<pre>
#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
position: relative;
}

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
}
</pre>

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* For the test, we use a red background color for the square. This is a useful tip to figure out if everything is fine with invisible elements.

Let's refresh and check our our (beautiful) squares:

[[File:reversi2.jpg]]

If the red squares do not appear, check your css file (Chrome DevTools: Application > Frames > top > Stylesheets > reversi.css). If your changes are not there try clearing your cache!

Hint: Now that we know our squares are set up correctly, we can hide the red background. You can remove the "background-color: red;" line from your .square class in the CSS stylesheet.

== The discs ==

Now, our board is ready to receive some disc tokens!

[Note: Throughout this tutorial, sometimes "tokens" is used, and sometimes "discs" is used. They are often swapped if you're looking at code in the reversi example project.]

At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):

<pre>


<div id="tokens">
</div>
</div>
</pre>

Then, let's introduce a new piece of art with the discs. We need some transparency here so we are using a png file:

[[File:tokens.png]]

Upload this image file "tokens.png" in your "img/" directory.

Important: we are using ONE file for both discs. It's really important that you use a minimum number of graphic files for your game with this "CSS sprite" technique, because it makes the game loading faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].

Now, let's separate the disc with some CSS stuff:

<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('img/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we apply the classes "token" and "tokencolor_ffffff" to a div element and we've got a white token. Yeah.

Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.

Now, let's make a first token appear on our board. Disc tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (reversi_reversi.tpl), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named "jstpl_token" with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (braces <code>{}</code>) and JS template variables (dollar and braces <code>${}</code>).

Now, let's create a method in our Javascript code (in the "reversi.js" file) that will make a token appear on the board, using this template. Add under the section //// Utility methods:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();
},
</pre>

At first, with "dojo.place" and "this.format_block" methods, we create a HTML piece of code and insert it as a new child of "tokens" div element.

Then, with BGA "this.placeOnObject" method, we place this element over the panel of some player. Immediately after, using BGA "this.slideToObject" method, we make the disc slide to the "square" element, its final destination.

"'overall_player_board_'+player" refers to the div element that contains each player's information and avatar. By initially placing the token here, it gives the effect that the player's avatar is throwing the token onto the board.

Note: don't forget to call the "play()", otherwise the token remains at its original location.

Note: note that during all the process, the parent of the new disc HTML element will remain "tokens". placeOnObject and slideToObject methods are only moving the position of elements on screen, and they are not modifying the HTML tree.

Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Note: Probably you'll have to remove the line "self::reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );".

Now, to test if everything works fine, just add "this.addTokenOnBoard( 2, 2, [player_id] )" in the "setup" Javascript method in reversi.js, and restart the game.

A token should appear and slide immediately to its position, like this:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now.

To design the database model of our game, the best thing to do is to follow the "Go to game database" link at the bottom of our game, to access the database directly with a [http://www.phpmyadmin.net/ PhpMyAdmin] instance. Your PhpMyAdmin username/password is in your welcome email (and currently the same as the SFTP username/password).

Then, you can create the tables you need for your game (do not remove existing tables!), and report every SQL command used in your "dbmodel.sql" file. How do you generate SQL to create table after creating the table in the UI? See [https://www.itsupportguides.com/knowledge-base/tech-tips-tricks/how-to-generate-sql-create-table-script-using-phpmyadmin/ here]. Add 'IF NOT EXISTS' to the CREATE TABLE sql (see example below).

[[File:reversi4.jpg]]

The database model of Reversi is very simple: just one table with the squares of the board.

<pre>
CREATE TABLE IF NOT EXISTS `board` (
`board_x` smallint(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB;
</pre>

Add the above SQL to dbmodel.sql. Now, a new database with a "board" table will be created each time we start a Reversi game. This is why after modifying our dbmodel.sql it's a good time to stop & start again our game.

== Setup the initial game position ==

The "setupNewGame" method of our reversi.game.php is called during initial setup: this is the place to initialize our data and to place the initial tokens on the board (initially, there are 4 tokens on the board).

Let's do this:

<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
self::DbQuery( $sql );

// Active first player
self::activeNextPlayer();
</pre>

We create one table entry for each square, with a "NULL" value which means "empty square". For 4 specific squares, we place an initial token.

At the end, we call activeNextPlayer to make the first player active at the beginning of the game.

You need to remove the call to self::reattributeColorsBasedOnPreferences() in SetupNewGame() so that any player color preferences do not override the two colors supported here.

Now, we need to make these tokens appear on the client side. The first step is to return the token positions with our "getAllDatas" PHP method (called during each page reload):

<pre>
// Get reversi board token
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player
FROM board
WHERE board_player IS NOT NULL" );
</pre>

We are using the BGA framework "getObjectListFromDB" method that formats the result of this SQL query in a PHP array with x, y and player attributes.

Last, we process this array client side, and place a disc token on the board for each array item. We do this using our Javascript "setup" method:

<pre>
for( var i in gamedatas.board )
{
var square = gamedatas.board[i];

if( square.player !== null )
{
this.addTokenOnBoard( square.x, square.y, square.player );
}
}
</pre>

Our "board" entry created in "getAllDatas" can be used here as "gamedatas.board" in our Javascript. We are using our previously developed "addTokenOnBoard" method.

Reload... and here we are:

[[File:reversi5.jpg]]

It starts to smell Reversi here...

== The game state machine ==

Now, let's stop our game again, because we are going to start the core game logic.

You already read [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine], so you know that this is the heart of your game logic. For reversi, it's very simple. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

And here's our "states.inc.php", according to this diagram:

<pre>
$machinestates = array(

1 => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => 10 )
),

10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn",
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

99 => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</pre>

Now, let's create in reversi.game.php the methods that are declared in this game states description file:
* argPlayerTurn
* stNextPlayer

... and start a new Reversi game.

As you can see on the screen capture below, the BGA framework makes the game jump to our first game state "playerTurn" right after the initial setup. That's why the status bar contains the description of playerTurn state ("XXXX must play a disc"):

[[File:reversi7.jpg]]

== The rules ==

We will use the "getPossibleMoves" PHP method to:
* Indicate to the current player where she is allowed to play by returning a list of coordinates
* Check if the player has the right to play in the spot they choose

This is pure PHP programming here, and there are no special things from the BGA framework that can be used. This is why we won't go into details here. The overall idea is:
* Create a "getTurnedOverDiscs(x,y)" method that returns coordinates of discs that would be turned over if a token would be played at x,y.
* Loop through all free squares of the board and call the "getTurnedOverDiscs" method on each of them. If at least 1 token is turned over, this is a valid move.

IMPORTANT: Keep in mind that making a database query is slow, so please don't load the entire game board with a SQL query multiple times. In our implementation, we load the entire board once at the beginning of "getPossibleMoves", and then pass the board as an argument to all methods.

If you want to look into details, please look at the "utility method" sections of reversi.game.php. If building the tutorial yourself, copy the functions under "Utility functions" comment from the Reversi tutorial.

== Display allowed moves ==

Now we want to highlight the squares where the player can place a disc.

To do this, we add a "argPlayerTurn" method in reversi.game.php. This method is called on the server each time we enter into "playerTurn" game state, and its result is transferred automatically to the client-side:

<pre>
function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We use the "getPossibleMoves" method we just developed.

Each time we enter into a new game state, we use the "onEnteringState" Javascript method (in the reversi.js file, under "Game & client states"). This lets us use the data returned by the method above on the client side.

<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
{
case 'playerTurn':
this.updatePossibleMoves( args.args.possibleMoves );
break;
}
},
</pre>

So, when we enter into "playerTurn" game state, we call our "updatePossibleMoves" method (under the "Utility functions" section). This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>
Here's what this does. At first, it removes all "possibleMove" classes currently applied with the very useful combination of "dojo.query" and "removeClass" method.

Then it loops through all possible moves our PHP "updatePossibleMoves" function created for us, and adds the "possibleMove" class to each corresponding square.

Finally, it uses the BGA framework "addTooltipToClass" method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

To see the possible moves we need to create a CSS class ("possibleMove") that can be applied to a "square" element to highlight it:
<pre>
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}
</pre>

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
* When we click on a "possibleMove" square, send the move to the server.
* Server side, check the move is correct, apply Reversi rules and jump to next player.
* Client side, change the disc position to reflect the move.

First we associate each click on a square to one of our methods using our Javascript "setup" method:

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

Note the use of the "dojo.query" method to get all HTML elements with "square" class in just one function call. Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

<pre>
onPlayDisc: function( evt )
{
// Stop this event propagation
dojo.stopEvent( evt );

// Get the clicked square x and y
// Note: square id format is "square_X_Y"
var coords = evt.currentTarget.id.split('_');
var x = coords[1];
var y = coords[2];

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

What we do here is:
* We stop the propagation of the Javascript "onclick" event. Otherwise, it can lead to random behavior so it's always a good idea.
* We get the x/y coordinates of the square by using "evt.currentTarget.id".
* We check that clicked square has the "possibleMove" class, otherwise we know for sure that we can't play there.
* We check that "playDisc" action is possible, according to current game state (see "possibleactions" entry in our "playerTurn" game state defined above). This check is important to avoid issues if a player double clicks on a square.
* Finally, we make a call to the server using BGA "ajaxcall" method with argument x and y. Be sure to update the first parameter to match your game if building the tutorial yourself. E.g. "/yourgamename/yourgamename/playDisc.html"

Now, we have to manage this "playDisc" action on the server side. At first, we introduce a "playDisc" entry point in our "reversi.action.php":

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding "playDisc" method in our game logic (reversi.game.php).

Now, let's have a look of this playDisc method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

<pre>
// Now, check if this is a possible move
$board = self::getBoard();
$player_id = self::getActivePlayerId();
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );

if( count( $turnedOverDiscs ) > 0 )
{
// This move is possible!
</pre>

...now, we are using the "getTurnedOverDiscs" method again to check that this move is possible.

<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$sql = "UPDATE board SET board_player='$player_id'
WHERE ( board_x, board_y) IN ( ";

foreach( $turnedOverDiscs as $turnedOver )
{
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";
}
$sql .= "('$x','$y') ) ";

self::DbQuery( $sql );

</pre>

... we update the database to change the color of all turned over disc + the disc we just placed.

<pre>
// Update scores according to the number of disc on board
$sql = "UPDATE player
SET player_score = (
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
)";
self::DbQuery( $sql );

// Statistics
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
self::incStat( 1, 'discPlayedOnCorner', $player_id );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
self::incStat( 1, 'discPlayedOnBorder', $player_id );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
self::incStat( 1, 'discPlayedOnCenter', $player_id );

</pre>

... now, we update both player score by counting all disc, and we manage game statistics.

<pre>
// Notify
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );

self::notifyAllPlayers( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
self::notifyAllPlayers( "newScores", "", array(
"scores" => $newScores
) );
</pre>

... then we notify about all these changes. We are using for that 3 notifications ('playDisc', 'turnOverDiscs' and 'newScores' that we are going to implement on client side later). Note that the description of the 'playDisc' notification will be logged in the game log.

<pre>
// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}
else
throw new feException( "Impossible move" );
}
</pre>

... finally, we jump to the next game state if everything goes fine ('playDisc' is the name of a transition in the 'playerTurn' game state description above which leads to state 11 which is 'nextPlayer').

To make the statistics work, we have to initialize them in stats.inc.php:

<pre>
// Statistics existing for each player
"player" => array(

"discPlayedOnCorner" => array( "id"=> 10,
"name" => totranslate("Discs played on a corner"),
"type" => "int" ),

"discPlayedOnBorder" => array( "id"=> 11,
"name" => totranslate("Discs played on a border"),
"type" => "int" ),

"discPlayedOnCenter" => array( "id"=> 12,
"name" => totranslate("Discs played on board center part"),
"type" => "int" ),

"turnedOver" => array( "id"=> 13,
"name" => totranslate("Number of discs turned over"),
"type" => "int" )
)
</pre>

A last thing to do on the server side is to activate the next player when we enter the "nextPlayer" game state (in the "reversi.game.php" file, under "Game state reactions"):

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

// Check if both player has at least 1 discs, and if there are free squares to play
$player_to_discs = self::getCollectionFromDb( "SELECT board_player, COUNT( board_x )
FROM board
GROUP BY board_player", true );

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
$this->gamestate->nextState( 'endGame' );
return ;
}
else if( ! isset( $player_to_discs[ $player_id ] ) )
{
// Active player has no more disc on the board => he looses immediately
$this->gamestate->nextState( 'endGame' );
return ;
}

// Can this player play?

$possibleMoves = self::getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{

// This player can't play
// Can his opponent play ?
$opponent_id = self::getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( self::getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
$this->gamestate->nextState( 'endGame' );
}
else
{
// => pass his turn
$this->gamestate->nextState( 'cantPlay' );
}
}
else
{
// This player can play. Give him some extra time
self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );
}

}
</pre>

Now, when we play a disc, the rules are checked and the disc appears in the database.

[[File:reversi9.jpg]]

Of course, as we don't manage notifications on client side, we need to press F5 after each move to see the changes on the board.

== Make the move appear automatically ==

Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.

In our "setupNotifications" method, we register 2 methods for the 2 notifications we created at the previous step ('playDisc' and 'turnOverDiscs'):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
dojo.subscribe( 'newScores', this, "notif_newScores" );
this.notifqueue.setSynchronous( 'newScores', 500 );
</pre>

As you can see, we associate each of our 3 notifications with a method prefixed with "notif_". We also define these notifications as "synchronous", with a duration in millisecond. It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Update the player scores
* (wait 500ms)

The 2nd parameter in dojo.subscribe call (this) is the 'context', and will be passed in as a parameter to the specified method.

Let's have a look now on the "playDisc" notification handler method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

No surprise here, we re-used some existing stuff to:
* Remove the highlighted squares.
* Add a new disc on board, coming from player panel.

Now, here's the method that handles the turnOverDiscs notification:

<pre>
notif_turnOverDiscs: function( notif )
{
// Get the color of the player who is returning the discs
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;

// Make these discs blink and set them to the specified color
for( var i in notif.args.turnedOver )
{
var token = notif.args.turnedOver[ i ];

// Make the token blink 2 times
var anim = dojo.fx.chain( [
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),
dojo.fadeOut( {
node: 'token_'+token.x+'_'+token.y,
onEnd: function( node ) {

// Remove any color class
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'tokencolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )

] ); // end of dojo.fx.chain

// ... and launch the animation
anim.play();
}
},
</pre>

The list of the discs to be turned over has been made available by our server side code in "notif.args.turnedOver" (see previous paragraph). We loop through all these discs, and create a complex animation using dojo.Animation for each of them. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

In few words: we create a chain of 4 animations to make the disc fade out, fade in, fade out again, and fade in again. At the end of the second fade out, we change the color of the disc. Finally, we launch the animation with "play()".

And Also the notification to update the scores:

<pre>
notif_newScores: function( notif )
{
for( var player_id in notif.args.scores )
{
var newScore = notif.args.scores[ player_id ];
this.scoreCtrl[ player_id ].toValue( newScore );
}
},
</pre>

Create a game in BGA Studio: Complete Walkthrough

2022-01-19T14:27:17Z

Grandepezzin: /* Hook version control system */

{{Studio_Framework_Navigation}}

== Introduction ==

This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using BGA Studio framework.

Before you read this material, you must:
* Read the overall presentations of the BGA [[Studio]].
* Some-what know the languages used by BGA Studio: PHP, SQL, HTML, CSS, Javascript
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]
* Create a game using one of the available tutorials. Don't bother with a new game if you have not completed at least one of the tutorials.

If you are stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].
If you're uncomfortable posting on the public forum you can send messages directly to developers who post answers on that forum but NOT the BGA admins.
If you find typos in this wiki - fix it.

== Select a First Game ==

For your first '''real''' game you must either
* Select a game from [https://en.studio.boardgamearena.com/licensing Available Licenses]
* Or from the Public Domain

But what if the game you want is not there? If you are able to successfully publish your first game, you would gain the trust of the BGA admins and they will be happy to assist you in obtaining a license for a game you really want to do or you can request a license yourself. You can read more about game licenses on [[BGA Game licenses]] page.

Once you selected the game but before creating a new project, please take a few seconds to check that someone is not already developing this game. If it is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

Even if you see a few projects with name of the game they may not be active. There are a lot of abandoned game projects. If it's not clear by the status, post to Developers forum asking if anybody is actively working on the project or send a message to the developers listed for the abandoned projects, and at the same time ask admins on the same forum post to send you graphics for that game if they have them (there a button on [https://en.studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but it will just send an email).

If your goal was to fix bugs in an existing project, first try to locate it on Studio, projects developed by BGA admins are not in the Studio. Then get read only access to the project and you can create your own as a copy of the existing one. Contact existing project admin about getting write access to the original project or if they are willing to take your patches - apply them.

If you want to take over an existing project first ask on the forum to see if project is abandoned, then get read only access (via project list) and see if this worth using it, if it has no code or graphics just start from the scratch, don't worry about project name it can be renamed later.

== Create a project ==

If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken use gamenameYOURINITIALS
template, i.e."heartsla". Don't worry too much about the name, if game would be good enough to be publish it will be renamed to original name.

Find and start the game in turn based mode, make sure it works.

Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a no-starter.

Update your project status in [http://en.studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for license" or "waiting for graphics" or combination of those.

== Development Tools ==

At some point you need to setup your development environment which consist of multiple tools, such as
* Editor or IDE
* Browser with dev tools
* File sync tools
* BGA Web tools
* Image manipulation tools
* Version control tools

Please scan though articles from [[Studio#BGA_Studio_user_guide]] especially related to debugging and tools, there is a lot of useful info there.

== Hook version control system ==

If it's a real game, I would commit the code to version control right at start. You are going to find yourself in the situation when the game does not even start anymore and there is no way of debugging it unless you have a way to revert. That is where version control becomes very handy.
If you don't know what I am talking about then at least back-up your files after each of major steps. Starting now.
You can also create a project on github, but make sure '''you don't commit original publisher graphics files''' and '''you don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).
You can (and should) also commit your modification periodically via Studio Control Panel.

== Obtain game graphics ==

If you developing a game from Available Licenses games, ask the admins to send you graphics by contacting studio@boardgamearena.com. While that request is being processed (it can take time, as it often requires some back and forth between the admins and the publishers) you can proceed to next step - project creation.

If you don't get original graphics you go to '''Scavenger Hunt'''

* If you developing a public domain card game you can borrow standard cards from BGA generic assets, see [[Common_board_game_elements_image_resources]]
* Standard game pieces - meeples, cubes, dice can be found here as well [[Common_board_game_elements_image_resources]]
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you lucky they also sometime have boards and token scans in "Game Pieces" section of Images
* If that fail google "boardgame <name>" and check Images section
* Get the rules PDF as well, there tools that allows you to extract graphics from PDF, which usually good for meeples, cubes and such (can use pdfimages command line tool)

Once you get the graphics one way or another you have to massage it to fit in the BGA criteria, which usually involves
* If publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down
* For non square tiles and game pieces you need transparency
* Usually you chop off scoring "ring" around the board of the game since scoring track not needed for online adaptation

More details about graphics requirements can be found here [[Game art: img directory]].

[[File:Rrr_search.png]]

== Obtain game documentation ==

Also at this time obtain a electronic copy of rules, such as PDF (English version).

Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such
as cheat-sheets (may be easier to get a data from these then trying to scrub pdf). You create and place them in the doc/ folder of the project then
exclude them from version control. There is also a misc/ folder now but it will hold up to 1 Mb of data files which would be checked in, so rules pdf's may not fit there.

== Update game infos and box graphics ==

Even it does not nothing yet start with making sure game looks descent in the game selector, meaning it has nice box graphics and information is correct.

For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].
What you would do for real game you would go to http://boardgamegeek.com find the game and use the information from web-site to fill the gameinfos.

The next step is to replace game_box.png with proper images, usually you can find all images including publisher logo on boardgamegeek website.

Details about images can be found here: [[Game art: img directory]].

Now important step. You have to LOAD these files in studio website through control panel. So go to Control Panel -> Manager Games -> YOURPROJECT
and press Reload for 'Reload game informations' and 'Reload game box image'

[[File:Gamepanel_sharedcode.png]]

Now try to start the game again. If you some-how introduced a syntax error in gameinfos file it may not actually work (game won't start).
Always use "Express Start" button to start the game. You should see a standard state prompt from template. You should see X players on the right, testdude0 .. testdudeX-1.
To switch between them press the red arrow button near their names, it will open another tab. This way you don't need to login and logout from multiple accounts!

== Fix source copyright ==

Now since you have your own project, you want put your name in the copyright header, so replace

© <Your name here> <Your email address here>
with
© John Snow <jsnow@gameofthrones.com>

Well not exactly this but whatever your real name is. For all files in project directory, its about 10 files. Make sure project still starts after that :)

== Reduce the Rules ==

Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of lack of patience or skill.
To keep sane, start the game with *reduced* rules and try to complete that first.

* If it has any expansions - do not even attempt to deal with them, not even - "I will just add graphics for them now and not use" - waste of time if you don't complete basic
* If it has advanced rules - start with basic rules only, i.e. "beginner game"
* If it has special rules for 2 player vs 4, start with most basic form (i.e. 4), restrict to 4 players
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)
* Any sort of rules that you think can be removed and not included in base - set aside for now
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later

== Design Game Elements ==
Technically game elements are already designed by board game designer but your job is to map it to program space.
Each physical piece (card, token, cube) will leave footprints all over the code (unfortunatly in multiple disconnected places).
To prepare the game you need to sort out these elements, i.e. categorize. I usually have to the following categorization (in object oriented view):
* Instance - all individual pieces are instances, i.e. two red cubes are two instances of 'red cube' type (class)
* Type - element type which distinctly represents that element in appearence (i.e. red cube is different type than blue cube)
* Super Type - one of more common types that similar properties (i.e. red OR cube)
* Player color - supertype specific for player color (sometimes there is no colors but like player 1 - but is conceptually the same, I use color because its easier to track)

Personally I like to encode my elements in string using reverse dns notation listing all the properties above, i.e.
meeple_ff0000_7 - this is instance #7 of type meeple_ff0000 (red meeple)
Or
card_yellow_magic_2 - this is instance #2 of yellow card (in this case yellow is color of deck not related to player color) that can do magic

So every game element would be in the

1. Database - instances. The db record would be something like
key|location|state
meeple_ff0000_7|slot_action_2|1
meeple_ff0000_2|tableau_ff0000|0
2. Material file - types and supertypes, we never need repeating info here, so never list individual instances but only types or supertypes, in this case we don't really need to define red meeple vs blue meeple
'meeple'=>{'name'=>totranslate('Meeple')}
3. Client (js, css, tpl, etc) - instances and types. For example my meeple will be like
<pre>
<div id="meeple_ff0000_7" class="meeple meeple_ff0000"></div>
</pre>
with .css something like
.meeple { background-image: url(img/tokens.png); width: 2em; height: 2em;}
.meeple_ff0000 {background-position: 20% 0%;}
4. Game php - setup and logic. During setup you have to generate all the pieces and place them in right positions. Also sometimes you need to reference elements to code the logic (I usually try to encode all rules in material file as much as possible)

For complex card games I think it is the best to keep all these info and rules in spreadsheet and generate other files such as material.inc.php.
See more info below about design of the individual layers.

== Create Initial Layout and Game Graphics ==

Mentally it is easier to start with game layout and graphics pieces. Even when nothing is working its give you moral satisfaction!

There are a few ways how the html could have been generated. You could have started with nothing and generate
it all by javascript, or you could have started with complete game markup in html and make javascript just hide and move pieces around. BGA framework also provides a third way, which is mix of both, plus a template engine to generate HTML using PHP. The only thing that is really annoying about the template engine is that you cannot put any translatable strings in the template (which means any visible text at all). If you are using the template approach all strings have to extracted as variables and injected through PHP (.view.php). This page explains the template engine in great detail:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].

The other disadvantage of the template engine is you cannot run and debug it locally, in the beginning of development it's a lot faster run off local pages,
you can do it with some trickery described here [[Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout|Tools and Tips for BGA Studio]]

During this step you have to decide what technical solutions you will be using, such as
* Use inline positioning of all moving pieces, controlled by JS. There are a few classes that already exist in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contain 200-300 pieces, it seems wrong but actually its faster to type all of this up in html/css when trying write than debug code for page generator.
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.

Start by creating and mapping all games assets, best way is probably to open rule book on "boardgame contents" page and go through every piece. Every pieces of boardgame would have its "print" in multiple files in your game:
* Some sort if "div" in html, where id of element match id of element in database (easiest way)
* Css for the element (either unique or for class), usually with background propery refering to part of sprite image
* Entry in material.inc.php referring to static properties of the element, i.e. name, tooltip, rules, etc
* Entry in .tpl file to represent static or initial location on the table OR creation template

Here are some specific examples:

'''Game Board'''

Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically
<pre>
<div id="board" class="board shadow board4p"> ... </div>
</pre>
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board whcih is diffrent than 2 ppl board)
<pre>
.board {
position: relative;
width: 980px;
height: 433px;
margin-bottom: 5px;
}

.board4p {
background-image: url(img/board4p.jpg);
}
</pre>
That would be pretty much it for the board itself, as it does not really need a tooltip so we don't need entry in material.inc.php

'''Game Board Slots'''

These are interactive areas on the board, usually illustrated as such. In most cases you can get away with rectangular shapes, but sometimes you have to create circle or oval shapes (and in really advanced case would be some svg paths). For slots you can do the following:

Entry in material.inc.php
<pre>
$this->token_types = array(
...
'slot_action_2' => array(
'type' => 'slot_action',
'name' => clienttranslate("2 Gray Track Advancements"),
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),
'o'=>"1,0,0,gg", // automatic rules
),
...
</pre>

Entry in template inside the "board" div
<pre>
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div>
</pre>

Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)
<pre>
.slot_action_2 {
top: 83px;
left: 37px;
}
.slot_action {
position: absolute;
width: 46px;
height: 26px;
padding: 9px 7px 6px 4px;
}
</pre>

'''Meeples''' - also cards, tokens, other mobile stuff

In CSS these guys will use "sprite" images with transparency, so it will look like this this:
<pre>
.meeple {
background-image: url(img/tokens.png);
width: 25px;
height: 25px;
}
.meeple_ff0000 { /* red */
background-position: 14% 0%;
}
</pre>
As for creation you can either generate them using template (where whole thing wrapped in template block and {COLOR} replace with all possible colors in .view.php
<pre>
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div>
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div>
...
</pre>

Or you can declare a template js var in .tpl file
<pre>
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom
</pre>
and create in js, like this
<pre>
var tokenDiv = this.format_block('jstpl_mepple', {
"color" : color,
"num" : i
}); // this in js code somewhere before placing it
</pre>
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.

When do you create dom element matching game element?
* If you have static layout you create it in .tpl file and its always there, but during initial setup or during notification it moved in proper spot (including "removed from the game" spot)
* If you dynamically generated pieces you create the element during notification, and sometimes during animation. Also don't forgot to hook event listener to it if its interactive.

One of the greatest parts about the web is all client side code can be viewed in your browser, so if you wondering how something is done in another BGA game just load the page and spy on it! In Chrome that would be right click and "Inspect Element". That would immediately show html of the given element alongside with css used for it (on the right). Another great way to learn is you can add yourself to any BGA project as read only from the project page!

So at the end of this stage you should complete the following (keeping in mind reduced rules/material for first iteration):
* Create a layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc
* Create css and html snippets for all game pieces: boards, tokens, meeples, etc. Place them all in initial template (even if they're not supposed to be visible at start). I.e. create fake player's hand with cards, put meeples on the board
* Hook layout to number of players and colors picked by the game and test with multiple players
* Figure out what you want to display in mini-player boards and hook it up
* Create material.inc.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements

If at this time you don't have graphics yet create pieces with just CSS, you can use shape, background color and object text using css ::after construct to fake the pieces.

[[File:Injected_text.png]]

== Hook Input and Animation ==

This step can be done before or after some of the server steps, or you go in iterations switching back and forward until you get it done, up to you.

At this time you want to hook clicking on pieces and buttons and provide some reaction, such of moving a piece. The handler code will be replaced later by the server hook, but at the beginning you want your game to be alive as early as possible.

Usually all pieces will be hooked to onclick during JS "setup" method, in addition if you create elements during server notification they have to be hooked up at that time.

You can play with animation effects you want put in place, in general all the pieces that move in real game should be moving, such as meeples, resources tokens/cubes, cards, vp tokens.
Regular piece animation is provided by BGA framework, but if you use html layout positioning not inline positioning you have to remove absolute positions (inline position styling) after each move. The set of functions for relative position token animation can found in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js

Also its a good idea to give player a visual cues on what game elements are clickable now, usually it will be a style, such as "active_slot", with visual effect of white dashed outline (outline is better then border, because border changes will make piece slightly move since it changes the size) or box-shadow (i.e. neon glow)

If you read [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] you know that you should not get carried away with animation, you are creating a board game not a video game... That also applies to sound effects (in general, you should not use any sounds effects beside already provided by framework).

See [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]] and [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.

== Create Database Schema ==

At some point you have to design your game database. Do it sooner then later since it would be harder to change it later, since some
code decisions would be based on that.

If you have grid-based abstract game use template from reversi, if you have a card game use template from hearts (the cards one also commented out in generated template for your project). The cards database goes with php class called [[Deck]].

In general make it as simple as possible.
Think about it, your game has 300 pieces (likely less). Using database to store this amount of data is like shooting a mosquito with a tank.
Anything more complex then one table with 5 columns or two tables will only going to make it harder to develop and not improve performance.
You can forget about normalising and any fancy stuff you learn about databases in school. String field for a primary key would be as fast as integer when we talking about this size of data. So don't over-optimize with trying to have integers field that have state based on bitmask!

Also remember that static (non dynamic) information about the game does not need to be stored in the database, that all include everything that does not change, i.e
all token/card properties such as name, tooltips, "strength", color, etc. This is stored in material.inc.php and server has access to it from anywhere, as well as client
if you send it with getAllDatas(). The only reason store some of it in database if it can affect your queries (i.e. type of token).

Usually design process will contain the following steps:
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model
* Mapping - now map real game to that model
* Encoding - now represent this model in database and material file with reasonable amount of fields

Example: '''The card game'''

* In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it
* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but as part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in your database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position itself usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html
* For dynamic stuff we should try to reduce amount of fields we need, i.e. we need a field for card, so its one, we need to know what zone cards belong to, its 2, and we have possible few other fields, but if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Another Example: '''The euro game'''

See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]

So the piece mapping for non-grid based
games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here:
[https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php tokens.php].

<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

See [[Game database model: dbmodel.sql]] for details about editing the file.

Note: the simpler the database is the less debugging of db issues you have to deal with including database migration. The tokens database above - if you use it you never have to worry about migration because you don't need extra tables in 95% of the games.
Here are some example of how real games are mapped to such database:

'''Chess'''

- chess is grid base game and normally you would use positional columns, but just for the sake of argument, the chess game will look like this
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_white
|f3
|0
|-
|P_black_2
|c6
|0
|-
|K_black
|e8
|1
|}
And the state in this case indicated that kind was moved for example (which means castling cannot be performed)

'''Classic card game'''

Lets pretend we need 2 decks for that game
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_spades_1
|hand_ff0000
|0 /* state not used for hand */
|-
|10_hearts_2
|tableau_ff0000
|2 /* position */
|-
|10_hearts_1
|tableau_common
|1 /* face down */
|}

'''Eminent Domain (card game)'''

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|card_tech_23
|hand_ff0000
|0 /* state not used for hand */
|-
|card_planet_19
|tableau_ff0000
|1 /* face up */
|-
|reource_s_22 /* silicon */
|card_planet_19
|2 /* production state */
|-
|fighter_F_1
|tableau_ff0000
|0
|}

You can also look at other games that use Tokens database and access layer: Nippon, Dungeon Petz, Lewis & Clark, Battleship, Russian Railroads, Khronos

== Implement Game Setup ==

Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page
and implement these step by step populating the database (using db access API).
Game initialization is performed in php method setupNewGame, this method is called once when game table is created.
Game notifications cannot be sent during this time.

== Implement One time game model synchronisation ==

Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix getAllDatas function
to return all possible data we need to reconstruct the game. The template for getAllDatas already taking care of player info, but you
have to alter it to return all other data from database visible to the "current" player.

After that on the client side we should display this data, so in your .js file in setup function (which is the receiver of getAllDatas) you add calls that handle data send by server, usually by calling animation function such as "placeToken" or "placeCard".

== Create State Machine ==

Now you need to create a game state machine.

The state handling spread across 4 files, so you have to make sure all the pieces are connected together.
The state machine states.inc.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

Please first watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine]
and then please read [[Your game state machine: states.inc.php]].

Now the state machine should be relatively simple. If you find yourself with machine with more than 20 states its probably not the way to go.
Not all the player interactions need separate states, a lot of things can be implemented directly on client, i.e. if your player need to select
a reward token, which offers choice of resource, instead of two states on server just have one state on server and possible few states on client (client side states)
to collect this info.

== Handle Turn Order ==

If your game goes in clockwise order in natural sitting position nothing really needed you just use standard API and you are good. However if position is complecated
it may require some trickery.

Usually turn order is done by "game state" (see state machine above). Basically it would be two choices:
* Turn order depends on game situation (such as we take player with highest number of red cubes)
* Turn order is custom and assign on previos step - i.e. we not playing in clockwise order anymore. In this case you either need to extend player table with new order info (CANNOT use player_no column) or use order markers that come with game (i.e. marker_ff0000 on position_1). In this we can build player array in right order and pick next player based on previous player using existing helper function such as $this->createNextPlayerTable($player_ids)

== Implement Notification handling ==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications send by server.
So previously we hooked onclick js handler right to client animation, in real game its a two
step operation. When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].

Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want
to avoid sending data to server until step is complete (which may involve direct client side animation). See [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Selection|Multi-Step Interactions]]

Part of the sending notifications would be to update player's scoring, BGA uses standard control for score (on JS side), see [[Game_interface_logic:_yourgamename.js#Update_players_score|Update Player's Score]].

In BGA there is only two ways interact with the server (officially)
* Initial data dump - when JS client starts it gets all current data via setup() method
* Game actions - ajaxcall from client, it returns error or ok (not data), then server send butch of notifications to client

Note current ajaxcall is super vebosy and prone to errors, I suggest to use helper function. It does a lot of stuff you must do anyways.
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = []; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server

if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, its is optional param - you rarely need it
}
},
</pre>

When you insert a single action you have to update multiples files:
* in ggg.js add ajaxcall, i.e. something like
this.addActionButton('pass',_('Pass'),()=>this.ajaxcallwrapper('pass'));
* in states.php - add action 'pass' to list of possible actions
'possibleactions' => ['pass','playCard']
* in action.php - add action hander, see https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php
* in game.php - add action hander, there you must do the following
** call checkAction to validate the action
** possible do more game specific check to validate what player doing is legal (even its not possible from your js side - player can cheat - not allow that)
** do some database maniplations, using access api
** send notifications - this is the "reply" for action
** transition to new state (it very rare that user will remain in the same state, except for multi-active states)
* back to ggg.js add notification subsciption and notification handler (two separate things)

== Wrap Up ==

* Implement game progression (getGameProgression() in php)
* Implement Zombie turn (zombieTurn() in php)
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
* The games logs should explain what happened if player was not looking
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Make sure all UI strings are marked for translation
* UI elements which are images (i.e. tokens, cards) should have tooltips

== Alpha ==
When you think you game is completely working there is still bunch of stuff you have to do/check before telling admin that game is ready, please go though this [[Pre-release checklist]].

If you think its completely ready, let admin know (studio@boardgamearena.com) and it they will push it to alpha.

Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:
* Links to the rules (in multiple languages if available).
* Links to teaching videos.
* In the "On the web" section, links to:
** The official website for the game (if there is one).
** The BoardGameGeek page for the game.
* Consider writing a summary of the rules.

== Level Up ==

When you successfully created a basic game and you want more, it's time to make it fancy!

* Add game externtions and variants using gameoptions file
* Add user preferences for customizations
* Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs
* You can use fancy scoring board at the end of game instead of default nothing
* And finally super cool dice rolling, card flipping and victory points evaporating effects

Create a game in BGA Studio: Complete Walkthrough

2022-01-19T14:25:24Z

Grandepezzin: /* Select a First Game */

{{Studio_Framework_Navigation}}

== Introduction ==

This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using BGA Studio framework.

Before you read this material, you must:
* Read the overall presentations of the BGA [[Studio]].
* Some-what know the languages used by BGA Studio: PHP, SQL, HTML, CSS, Javascript
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]
* Create a game using one of the available tutorials. Don't bother with a new game if you have not completed at least one of the tutorials.

If you are stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].
If you're uncomfortable posting on the public forum you can send messages directly to developers who post answers on that forum but NOT the BGA admins.
If you find typos in this wiki - fix it.

== Select a First Game ==

For your first '''real''' game you must either
* Select a game from [https://en.studio.boardgamearena.com/licensing Available Licenses]
* Or from the Public Domain

But what if the game you want is not there? If you are able to successfully publish your first game, you would gain the trust of the BGA admins and they will be happy to assist you in obtaining a license for a game you really want to do or you can request a license yourself. You can read more about game licenses on [[BGA Game licenses]] page.

Once you selected the game but before creating a new project, please take a few seconds to check that someone is not already developing this game. If it is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

Even if you see a few projects with name of the game they may not be active. There are a lot of abandoned game projects. If it's not clear by the status, post to Developers forum asking if anybody is actively working on the project or send a message to the developers listed for the abandoned projects, and at the same time ask admins on the same forum post to send you graphics for that game if they have them (there a button on [https://en.studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but it will just send an email).

If your goal was to fix bugs in an existing project, first try to locate it on Studio, projects developed by BGA admins are not in the Studio. Then get read only access to the project and you can create your own as a copy of the existing one. Contact existing project admin about getting write access to the original project or if they are willing to take your patches - apply them.

If you want to take over an existing project first ask on the forum to see if project is abandoned, then get read only access (via project list) and see if this worth using it, if it has no code or graphics just start from the scratch, don't worry about project name it can be renamed later.

== Create a project ==

If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken use gamenameYOURINITIALS
template, i.e."heartsla". Don't worry too much about the name, if game would be good enough to be publish it will be renamed to original name.

Find and start the game in turn based mode, make sure it works.

Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a no-starter.

Update your project status in [http://en.studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for license" or "waiting for graphics" or combination of those.

== Development Tools ==

At some point you need to setup your development environment which consist of multiple tools, such as
* Editor or IDE
* Browser with dev tools
* File sync tools
* BGA Web tools
* Image manipulation tools
* Version control tools

Please scan though articles from [[Studio#BGA_Studio_user_guide]] especially related to debugging and tools, there is a lot of useful info there.

== Hook version control system ==

If its a real game I would commit the code to version control right at start. You going to find yourself in the situation
when game does not even start anymore and no way of debugging it unless you have a way to revert. That is where version control becomes very handy.
If you don't know what I am talking about then at least back-up your files after each of major steps. Starting now.
You can also create a project on github, but make sure '''you don't commit original publisher graphics files''' and '''you don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).
You can (and should) also commit your modification periodically via studio's control panel.

== Obtain game graphics ==

If you developing a game from Available Licenses games, ask the admins to send you graphics by contacting studio@boardgamearena.com. While that request is being processed (it can take time, as it often requires some back and forth between the admins and the publishers) you can proceed to next step - project creation.

If you don't get original graphics you go to '''Scavenger Hunt'''

* If you developing a public domain card game you can borrow standard cards from BGA generic assets, see [[Common_board_game_elements_image_resources]]
* Standard game pieces - meeples, cubes, dice can be found here as well [[Common_board_game_elements_image_resources]]
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you lucky they also sometime have boards and token scans in "Game Pieces" section of Images
* If that fail google "boardgame <name>" and check Images section
* Get the rules PDF as well, there tools that allows you to extract graphics from PDF, which usually good for meeples, cubes and such (can use pdfimages command line tool)

Once you get the graphics one way or another you have to massage it to fit in the BGA criteria, which usually involves
* If publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down
* For non square tiles and game pieces you need transparency
* Usually you chop off scoring "ring" around the board of the game since scoring track not needed for online adaptation

More details about graphics requirements can be found here [[Game art: img directory]].

[[File:Rrr_search.png]]

== Obtain game documentation ==

Also at this time obtain a electronic copy of rules, such as PDF (English version).

Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such
as cheat-sheets (may be easier to get a data from these then trying to scrub pdf). You create and place them in the doc/ folder of the project then
exclude them from version control. There is also a misc/ folder now but it will hold up to 1 Mb of data files which would be checked in, so rules pdf's may not fit there.

== Update game infos and box graphics ==

Even it does not nothing yet start with making sure game looks descent in the game selector, meaning it has nice box graphics and information is correct.

For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].
What you would do for real game you would go to http://boardgamegeek.com find the game and use the information from web-site to fill the gameinfos.

The next step is to replace game_box.png with proper images, usually you can find all images including publisher logo on boardgamegeek website.

Details about images can be found here: [[Game art: img directory]].

Now important step. You have to LOAD these files in studio website through control panel. So go to Control Panel -> Manager Games -> YOURPROJECT
and press Reload for 'Reload game informations' and 'Reload game box image'

[[File:Gamepanel_sharedcode.png]]

Now try to start the game again. If you some-how introduced a syntax error in gameinfos file it may not actually work (game won't start).
Always use "Express Start" button to start the game. You should see a standard state prompt from template. You should see X players on the right, testdude0 .. testdudeX-1.
To switch between them press the red arrow button near their names, it will open another tab. This way you don't need to login and logout from multiple accounts!

== Fix source copyright ==

Now since you have your own project, you want put your name in the copyright header, so replace

© <Your name here> <Your email address here>
with
© John Snow <jsnow@gameofthrones.com>

Well not exactly this but whatever your real name is. For all files in project directory, its about 10 files. Make sure project still starts after that :)

== Reduce the Rules ==

Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of lack of patience or skill.
To keep sane, start the game with *reduced* rules and try to complete that first.

* If it has any expansions - do not even attempt to deal with them, not even - "I will just add graphics for them now and not use" - waste of time if you don't complete basic
* If it has advanced rules - start with basic rules only, i.e. "beginner game"
* If it has special rules for 2 player vs 4, start with most basic form (i.e. 4), restrict to 4 players
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)
* Any sort of rules that you think can be removed and not included in base - set aside for now
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later

== Design Game Elements ==
Technically game elements are already designed by board game designer but your job is to map it to program space.
Each physical piece (card, token, cube) will leave footprints all over the code (unfortunatly in multiple disconnected places).
To prepare the game you need to sort out these elements, i.e. categorize. I usually have to the following categorization (in object oriented view):
* Instance - all individual pieces are instances, i.e. two red cubes are two instances of 'red cube' type (class)
* Type - element type which distinctly represents that element in appearence (i.e. red cube is different type than blue cube)
* Super Type - one of more common types that similar properties (i.e. red OR cube)
* Player color - supertype specific for player color (sometimes there is no colors but like player 1 - but is conceptually the same, I use color because its easier to track)

Personally I like to encode my elements in string using reverse dns notation listing all the properties above, i.e.
meeple_ff0000_7 - this is instance #7 of type meeple_ff0000 (red meeple)
Or
card_yellow_magic_2 - this is instance #2 of yellow card (in this case yellow is color of deck not related to player color) that can do magic

So every game element would be in the

1. Database - instances. The db record would be something like
key|location|state
meeple_ff0000_7|slot_action_2|1
meeple_ff0000_2|tableau_ff0000|0
2. Material file - types and supertypes, we never need repeating info here, so never list individual instances but only types or supertypes, in this case we don't really need to define red meeple vs blue meeple
'meeple'=>{'name'=>totranslate('Meeple')}
3. Client (js, css, tpl, etc) - instances and types. For example my meeple will be like
<pre>
<div id="meeple_ff0000_7" class="meeple meeple_ff0000"></div>
</pre>
with .css something like
.meeple { background-image: url(img/tokens.png); width: 2em; height: 2em;}
.meeple_ff0000 {background-position: 20% 0%;}
4. Game php - setup and logic. During setup you have to generate all the pieces and place them in right positions. Also sometimes you need to reference elements to code the logic (I usually try to encode all rules in material file as much as possible)

For complex card games I think it is the best to keep all these info and rules in spreadsheet and generate other files such as material.inc.php.
See more info below about design of the individual layers.

== Create Initial Layout and Game Graphics ==

Mentally it is easier to start with game layout and graphics pieces. Even when nothing is working its give you moral satisfaction!

There are a few ways how the html could have been generated. You could have started with nothing and generate
it all by javascript, or you could have started with complete game markup in html and make javascript just hide and move pieces around. BGA framework also provides a third way, which is mix of both, plus a template engine to generate HTML using PHP. The only thing that is really annoying about the template engine is that you cannot put any translatable strings in the template (which means any visible text at all). If you are using the template approach all strings have to extracted as variables and injected through PHP (.view.php). This page explains the template engine in great detail:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].

The other disadvantage of the template engine is you cannot run and debug it locally, in the beginning of development it's a lot faster run off local pages,
you can do it with some trickery described here [[Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout|Tools and Tips for BGA Studio]]

During this step you have to decide what technical solutions you will be using, such as
* Use inline positioning of all moving pieces, controlled by JS. There are a few classes that already exist in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contain 200-300 pieces, it seems wrong but actually its faster to type all of this up in html/css when trying write than debug code for page generator.
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.

Start by creating and mapping all games assets, best way is probably to open rule book on "boardgame contents" page and go through every piece. Every pieces of boardgame would have its "print" in multiple files in your game:
* Some sort if "div" in html, where id of element match id of element in database (easiest way)
* Css for the element (either unique or for class), usually with background propery refering to part of sprite image
* Entry in material.inc.php referring to static properties of the element, i.e. name, tooltip, rules, etc
* Entry in .tpl file to represent static or initial location on the table OR creation template

Here are some specific examples:

'''Game Board'''

Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically
<pre>
<div id="board" class="board shadow board4p"> ... </div>
</pre>
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board whcih is diffrent than 2 ppl board)
<pre>
.board {
position: relative;
width: 980px;
height: 433px;
margin-bottom: 5px;
}

.board4p {
background-image: url(img/board4p.jpg);
}
</pre>
That would be pretty much it for the board itself, as it does not really need a tooltip so we don't need entry in material.inc.php

'''Game Board Slots'''

These are interactive areas on the board, usually illustrated as such. In most cases you can get away with rectangular shapes, but sometimes you have to create circle or oval shapes (and in really advanced case would be some svg paths). For slots you can do the following:

Entry in material.inc.php
<pre>
$this->token_types = array(
...
'slot_action_2' => array(
'type' => 'slot_action',
'name' => clienttranslate("2 Gray Track Advancements"),
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),
'o'=>"1,0,0,gg", // automatic rules
),
...
</pre>

Entry in template inside the "board" div
<pre>
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div>
</pre>

Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)
<pre>
.slot_action_2 {
top: 83px;
left: 37px;
}
.slot_action {
position: absolute;
width: 46px;
height: 26px;
padding: 9px 7px 6px 4px;
}
</pre>

'''Meeples''' - also cards, tokens, other mobile stuff

In CSS these guys will use "sprite" images with transparency, so it will look like this this:
<pre>
.meeple {
background-image: url(img/tokens.png);
width: 25px;
height: 25px;
}
.meeple_ff0000 { /* red */
background-position: 14% 0%;
}
</pre>
As for creation you can either generate them using template (where whole thing wrapped in template block and {COLOR} replace with all possible colors in .view.php
<pre>
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div>
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div>
...
</pre>

Or you can declare a template js var in .tpl file
<pre>
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom
</pre>
and create in js, like this
<pre>
var tokenDiv = this.format_block('jstpl_mepple', {
"color" : color,
"num" : i
}); // this in js code somewhere before placing it
</pre>
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.

When do you create dom element matching game element?
* If you have static layout you create it in .tpl file and its always there, but during initial setup or during notification it moved in proper spot (including "removed from the game" spot)
* If you dynamically generated pieces you create the element during notification, and sometimes during animation. Also don't forgot to hook event listener to it if its interactive.

One of the greatest parts about the web is all client side code can be viewed in your browser, so if you wondering how something is done in another BGA game just load the page and spy on it! In Chrome that would be right click and "Inspect Element". That would immediately show html of the given element alongside with css used for it (on the right). Another great way to learn is you can add yourself to any BGA project as read only from the project page!

So at the end of this stage you should complete the following (keeping in mind reduced rules/material for first iteration):
* Create a layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc
* Create css and html snippets for all game pieces: boards, tokens, meeples, etc. Place them all in initial template (even if they're not supposed to be visible at start). I.e. create fake player's hand with cards, put meeples on the board
* Hook layout to number of players and colors picked by the game and test with multiple players
* Figure out what you want to display in mini-player boards and hook it up
* Create material.inc.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements

If at this time you don't have graphics yet create pieces with just CSS, you can use shape, background color and object text using css ::after construct to fake the pieces.

[[File:Injected_text.png]]

== Hook Input and Animation ==

This step can be done before or after some of the server steps, or you go in iterations switching back and forward until you get it done, up to you.

At this time you want to hook clicking on pieces and buttons and provide some reaction, such of moving a piece. The handler code will be replaced later by the server hook, but at the beginning you want your game to be alive as early as possible.

Usually all pieces will be hooked to onclick during JS "setup" method, in addition if you create elements during server notification they have to be hooked up at that time.

You can play with animation effects you want put in place, in general all the pieces that move in real game should be moving, such as meeples, resources tokens/cubes, cards, vp tokens.
Regular piece animation is provided by BGA framework, but if you use html layout positioning not inline positioning you have to remove absolute positions (inline position styling) after each move. The set of functions for relative position token animation can found in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js

Also its a good idea to give player a visual cues on what game elements are clickable now, usually it will be a style, such as "active_slot", with visual effect of white dashed outline (outline is better then border, because border changes will make piece slightly move since it changes the size) or box-shadow (i.e. neon glow)

If you read [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] you know that you should not get carried away with animation, you are creating a board game not a video game... That also applies to sound effects (in general, you should not use any sounds effects beside already provided by framework).

See [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]] and [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.

== Create Database Schema ==

At some point you have to design your game database. Do it sooner then later since it would be harder to change it later, since some
code decisions would be based on that.

If you have grid-based abstract game use template from reversi, if you have a card game use template from hearts (the cards one also commented out in generated template for your project). The cards database goes with php class called [[Deck]].

In general make it as simple as possible.
Think about it, your game has 300 pieces (likely less). Using database to store this amount of data is like shooting a mosquito with a tank.
Anything more complex then one table with 5 columns or two tables will only going to make it harder to develop and not improve performance.
You can forget about normalising and any fancy stuff you learn about databases in school. String field for a primary key would be as fast as integer when we talking about this size of data. So don't over-optimize with trying to have integers field that have state based on bitmask!

Also remember that static (non dynamic) information about the game does not need to be stored in the database, that all include everything that does not change, i.e
all token/card properties such as name, tooltips, "strength", color, etc. This is stored in material.inc.php and server has access to it from anywhere, as well as client
if you send it with getAllDatas(). The only reason store some of it in database if it can affect your queries (i.e. type of token).

Usually design process will contain the following steps:
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model
* Mapping - now map real game to that model
* Encoding - now represent this model in database and material file with reasonable amount of fields

Example: '''The card game'''

* In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it
* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but as part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in your database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position itself usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html
* For dynamic stuff we should try to reduce amount of fields we need, i.e. we need a field for card, so its one, we need to know what zone cards belong to, its 2, and we have possible few other fields, but if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Another Example: '''The euro game'''

See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]

So the piece mapping for non-grid based
games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here:
[https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php tokens.php].

<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

See [[Game database model: dbmodel.sql]] for details about editing the file.

Note: the simpler the database is the less debugging of db issues you have to deal with including database migration. The tokens database above - if you use it you never have to worry about migration because you don't need extra tables in 95% of the games.
Here are some example of how real games are mapped to such database:

'''Chess'''

- chess is grid base game and normally you would use positional columns, but just for the sake of argument, the chess game will look like this
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_white
|f3
|0
|-
|P_black_2
|c6
|0
|-
|K_black
|e8
|1
|}
And the state in this case indicated that kind was moved for example (which means castling cannot be performed)

'''Classic card game'''

Lets pretend we need 2 decks for that game
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_spades_1
|hand_ff0000
|0 /* state not used for hand */
|-
|10_hearts_2
|tableau_ff0000
|2 /* position */
|-
|10_hearts_1
|tableau_common
|1 /* face down */
|}

'''Eminent Domain (card game)'''

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|card_tech_23
|hand_ff0000
|0 /* state not used for hand */
|-
|card_planet_19
|tableau_ff0000
|1 /* face up */
|-
|reource_s_22 /* silicon */
|card_planet_19
|2 /* production state */
|-
|fighter_F_1
|tableau_ff0000
|0
|}

You can also look at other games that use Tokens database and access layer: Nippon, Dungeon Petz, Lewis & Clark, Battleship, Russian Railroads, Khronos

== Implement Game Setup ==

Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page
and implement these step by step populating the database (using db access API).
Game initialization is performed in php method setupNewGame, this method is called once when game table is created.
Game notifications cannot be sent during this time.

== Implement One time game model synchronisation ==

Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix getAllDatas function
to return all possible data we need to reconstruct the game. The template for getAllDatas already taking care of player info, but you
have to alter it to return all other data from database visible to the "current" player.

After that on the client side we should display this data, so in your .js file in setup function (which is the receiver of getAllDatas) you add calls that handle data send by server, usually by calling animation function such as "placeToken" or "placeCard".

== Create State Machine ==

Now you need to create a game state machine.

The state handling spread across 4 files, so you have to make sure all the pieces are connected together.
The state machine states.inc.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

Please first watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine]
and then please read [[Your game state machine: states.inc.php]].

Now the state machine should be relatively simple. If you find yourself with machine with more than 20 states its probably not the way to go.
Not all the player interactions need separate states, a lot of things can be implemented directly on client, i.e. if your player need to select
a reward token, which offers choice of resource, instead of two states on server just have one state on server and possible few states on client (client side states)
to collect this info.

== Handle Turn Order ==

If your game goes in clockwise order in natural sitting position nothing really needed you just use standard API and you are good. However if position is complecated
it may require some trickery.

Usually turn order is done by "game state" (see state machine above). Basically it would be two choices:
* Turn order depends on game situation (such as we take player with highest number of red cubes)
* Turn order is custom and assign on previos step - i.e. we not playing in clockwise order anymore. In this case you either need to extend player table with new order info (CANNOT use player_no column) or use order markers that come with game (i.e. marker_ff0000 on position_1). In this we can build player array in right order and pick next player based on previous player using existing helper function such as $this->createNextPlayerTable($player_ids)

== Implement Notification handling ==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications send by server.
So previously we hooked onclick js handler right to client animation, in real game its a two
step operation. When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].

Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want
to avoid sending data to server until step is complete (which may involve direct client side animation). See [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Selection|Multi-Step Interactions]]

Part of the sending notifications would be to update player's scoring, BGA uses standard control for score (on JS side), see [[Game_interface_logic:_yourgamename.js#Update_players_score|Update Player's Score]].

In BGA there is only two ways interact with the server (officially)
* Initial data dump - when JS client starts it gets all current data via setup() method
* Game actions - ajaxcall from client, it returns error or ok (not data), then server send butch of notifications to client

Note current ajaxcall is super vebosy and prone to errors, I suggest to use helper function. It does a lot of stuff you must do anyways.
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = []; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server

if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, its is optional param - you rarely need it
}
},
</pre>

When you insert a single action you have to update multiples files:
* in ggg.js add ajaxcall, i.e. something like
this.addActionButton('pass',_('Pass'),()=>this.ajaxcallwrapper('pass'));
* in states.php - add action 'pass' to list of possible actions
'possibleactions' => ['pass','playCard']
* in action.php - add action hander, see https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php
* in game.php - add action hander, there you must do the following
** call checkAction to validate the action
** possible do more game specific check to validate what player doing is legal (even its not possible from your js side - player can cheat - not allow that)
** do some database maniplations, using access api
** send notifications - this is the "reply" for action
** transition to new state (it very rare that user will remain in the same state, except for multi-active states)
* back to ggg.js add notification subsciption and notification handler (two separate things)

== Wrap Up ==

* Implement game progression (getGameProgression() in php)
* Implement Zombie turn (zombieTurn() in php)
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
* The games logs should explain what happened if player was not looking
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Make sure all UI strings are marked for translation
* UI elements which are images (i.e. tokens, cards) should have tooltips

== Alpha ==
When you think you game is completely working there is still bunch of stuff you have to do/check before telling admin that game is ready, please go though this [[Pre-release checklist]].

If you think its completely ready, let admin know (studio@boardgamearena.com) and it they will push it to alpha.

Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:
* Links to the rules (in multiple languages if available).
* Links to teaching videos.
* In the "On the web" section, links to:
** The official website for the game (if there is one).
** The BoardGameGeek page for the game.
* Consider writing a summary of the rules.

== Level Up ==

When you successfully created a basic game and you want more, it's time to make it fancy!

* Add game externtions and variants using gameoptions file
* Add user preferences for customizations
* Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs
* You can use fancy scoring board at the end of game instead of default nothing
* And finally super cool dice rolling, card flipping and victory points evaporating effects

First steps with BGA Studio

2022-01-19T09:30:11Z

Grandepezzin: /* Let's code! */

{{Studio_Framework_Navigation}}

== Connect to the BGA Studio website ==

Go to BGA Studio website:
http://studio.boardgamearena.com

Choose one of your 10 accounts (ex: myusername0, password was sent in welcome email), and login into the website - as you would do for Board Game Arena.

If you don't have account see [[How to join BGA developer team?]]

== Create a new game project ==

You can do most of the projects-related operations from "Control Panel / Manage games". In particular, you can create a new project automatically from there.

Your first "game" should be one of the tutorials, so your project name should be something like "tutorialbob".

At this stage it is too early to create a real game but if you really don't want to start until you have a game in mind, check [[Create a game in BGA Studio: Complete Walkthrough]]
section "Select a First Game"

For reference top bar studio links
* AVAILABLE LICENSES - list of all available licenses (not public domain) - http://en.studio.boardgamearena.com/#!licensing
* STUDIO PROJECTS - list of all registered studio projects - http://en.studio.boardgamearena.com/#!projects
* CONTROL PANEL - manage projects - http://en.studio.boardgamearena.com/#!controlpanel

== Connect to your SFTP folder ==

From the initial email from the Studio you get:
* the name of the SFTP server to connect to
* your SFTP login and password

Using this information:
# Connect to the SFTP server using your SFTP login and password, through your favourite SFTP client software (such as [http://winscp.net/ WinSCP], see [[Tools_and_tips_of_BGA_Studio#File_Sync_on_Windows|File Sync]])
# Check that your remote home folder contains one folder for each of the three example games (reversi, hearts, gomoku). If you have already created a new game project, one additional folder should be in your "home" folder.
# Note: You have to setup AUTOMATED sync between your folder and remote folder, manually ftp'ing files would be no-starter. For WinSCP you can do this from the file menu (Commands->Keep remote directories up to Date...)

== Let's code! ==

Now, you can try to launch a new game on BGA Studio from the "Play now" menu entry, as you would do on Board Game Arena website.

# To launch your game from Studio go to Studio -> Control Panel -> Manage games -> <your_game> -> <your_game_page> -> Play now
# Use the 'I want between X and X' players to tick down the maximum players number to the minimum
# Click 'Express start': your game launches with the maximum number of players specified. It shows an empty canvas: in the game zone you just have a sentence 'This is your game interface. You can edit this HTML in your ".tpl" file.'. If you don't see Express start button make sure you are in Manual mode for game creation.
# Switch to your SFTP home folder, go into your game folder. Edit the game_game.tpl file, and change this sentence to 'Hey, this is my first game!', then save.
# Go back to your browser and refresh, check that the game zone has updated.
# Click the red arrow next to a test account's name in the player panel to view the game from that player's account <br/>[[File:Change_active_player.jpg]]
# From the Player page or Table page click on the link "You are playing <name of game> (realtime)" (or click on the 'Gear' icon on the top right) and choose 'Express STOP'. The game ends automatically and you are brought back to the table screen for this ended game.
# Switch to your game folder, go into the img folder and overwrite your game_box.png file with another image.
# Go back to your browser, '''empty your browser cache''', then refresh the page, and check that the game box image has been updated.

Then you can modify the provided skeleton and begin to develop your game :)

== Commit your changes ==

Committing uploads your changes on BGA's [http://en.wikipedia.org/wiki/Revision_control revision control] system. This is an extra assurance not to lose your code, and to have the possibility to get a previous version of your code if you need to backtrack. It also helps us to follow your progress (we get an email when you commit). So you should commit from time to time, when you hit some landmark in your development.

You can automatically commit your sources in the repository from "Control Panel / Manage Games / Your game / Commit my modifications now". Then:

# Enter your commit comment (such as 'My first commit') then hit the 'Submit' button;
# Check the log for errors, it should end with the following lines:

Transmitting file data .
Committed revision #revision number#.
HAL says: done.

NOTE: committing the code is currently not working until admin commits it manually the first time. Even if it does you cannot automatically deal with this version control system except for committing. Therefore its recommended to use another means of storing the code in version control system, such as local git repo or github, see [[Tools_and_tips_of_BGA_Studio#Version_Control|Version Control]]

== That's all! ==

Now you know about the basics of updating your game on BGA Studio and testing your changes.

Now you can select one of the tutorials to play with and start coding.

For links to tutorials and ALL studio documentation see [[Studio]].

First steps with BGA Studio

2022-01-19T09:02:07Z

Grandepezzin: /* Let's code! */

{{Studio_Framework_Navigation}}

== Connect to the BGA Studio website ==

Go to BGA Studio website:
http://studio.boardgamearena.com

Choose one of your 10 accounts (ex: myusername0, password was sent in welcome email), and login into the website - as you would do for Board Game Arena.

If you don't have account see [[How to join BGA developer team?]]

== Create a new game project ==

You can do most of the projects-related operations from "Control Panel / Manage games". In particular, you can create a new project automatically from there.

Your first "game" should be one of the tutorials, so your project name should be something like "tutorialbob".

At this stage it is too early to create a real game but if you really don't want to start until you have a game in mind, check [[Create a game in BGA Studio: Complete Walkthrough]]
section "Select a First Game"

For reference top bar studio links
* AVAILABLE LICENSES - list of all available licenses (not public domain) - http://en.studio.boardgamearena.com/#!licensing
* STUDIO PROJECTS - list of all registered studio projects - http://en.studio.boardgamearena.com/#!projects
* CONTROL PANEL - manage projects - http://en.studio.boardgamearena.com/#!controlpanel

== Connect to your SFTP folder ==

From the initial email from the Studio you get:
* the name of the SFTP server to connect to
* your SFTP login and password

Using this information:
# Connect to the SFTP server using your SFTP login and password, through your favourite SFTP client software (such as [http://winscp.net/ WinSCP], see [[Tools_and_tips_of_BGA_Studio#File_Sync_on_Windows|File Sync]])
# Check that your remote home folder contains one folder for each of the three example games (reversi, hearts, gomoku). If you have already created a new game project, one additional folder should be in your "home" folder.
# Note: You have to setup AUTOMATED sync between your folder and remote folder, manually ftp'ing files would be no-starter. For WinSCP you can do this from the file menu (Commands->Keep remote directories up to Date...)

== Let's code! ==

Now, you can try to launch a new game on BGA Studio from the "Play now" menu entry, as you would do on Board Game Arena website.

# To launch your game from studio go to studio control panel -> manage games -> <your_game> -> <your_game_page> -> Play now
# Use the 'I want between X and X' players to tick down the maximum players number to the minimum
# Click 'Express start': your game launches with the maximum number of players specified. It shows an empty canvas: in the game zone you just have a sentence 'This is your game interface. You can edit this HTML in your ".tpl" file.'. If you don't see Express start button make sure you are in Manual mode for game creation.
# Switch to your SFTP home folder, go into your game folder. Edit the game_game.tpl file, and change this sentence to 'Hey, this is my first game!', then save.
# Go back to your browser and refresh, check that the game zone has updated.
# Click the red arrow next to a test account's name in the player panel to view the game from that player's account <br/>[[File:Change_active_player.jpg]]
# From the Player page or Table page click on the link "You are playing <name of game> (realtime)" (or click on the 'Gear' icon on the top right) and choose 'Express STOP'. The game ends automatically and you are brought back to the table screen for this ended game.
# Switch to your game folder, go into the img folder and overwrite your game_box.png file with another image.
# Go back to your browser, '''empty your browser cache''', then refresh the page, and check that the game box image has been updated.

Then you can modify the provided skeleton and begin to develop your game :)

== Commit your changes ==

Committing uploads your changes on BGA's [http://en.wikipedia.org/wiki/Revision_control revision control] system. This is an extra assurance not to lose your code, and to have the possibility to get a previous version of your code if you need to backtrack. It also helps us to follow your progress (we get an email when you commit). So you should commit from time to time, when you hit some landmark in your development.

You can automatically commit your sources in the repository from "Control Panel / Manage Games / Your game / Commit my modifications now". Then:

# Enter your commit comment (such as 'My first commit') then hit the 'Submit' button;
# Check the log for errors, it should end with the following lines:

Transmitting file data .
Committed revision #revision number#.
HAL says: done.

NOTE: committing the code is currently not working until admin commits it manually the first time. Even if it does you cannot automatically deal with this version control system except for committing. Therefore its recommended to use another means of storing the code in version control system, such as local git repo or github, see [[Tools_and_tips_of_BGA_Studio#Version_Control|Version Control]]

== That's all! ==

Now you know about the basics of updating your game on BGA Studio and testing your changes.

Now you can select one of the tutorials to play with and start coding.

For links to tutorials and ALL studio documentation see [[Studio]].

Gamehelptutorialpezzin

2022-01-19T08:56:45Z

Grandepezzin: Created page with "Ciao, this is my tutorial page."

Ciao, this is my tutorial page.

Game database model: dbmodel.sql

2022-01-18T22:36:54Z

Grandepezzin: /* PHP */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you are dealing with games with 50-500 pieces!
** If you have 5 tables for a card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: if you have cards that have power, color and special abilities. In the database you only need to store the card type, all the other properties should not be there. Only exception being if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in the database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

By default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You '''MUST NOT MODIFY''' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

=== The '''player''' table ===

You may add columns to the '''player''' table. This is very practical to add simple values associated with players. '''NB:''' you must not alter existing columns created by the framework.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this data with getActivePlayerName() or loadPlayersBasicInfos() methods)
* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.

<strong><u>CAUTION:</u></strong> '''player_table_order''' is not guaranteed to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== PHP ==
Database initialization should be in function setupNewGame() in 'gamename.game.php'.

Database schema migration should be in function upgradeTableDb(), see below.

Warning: all CREATE/ALTER tables and view should be in dbmodel.sql. Do not call these queries from php to avoid implicit commits https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html
which will cause issues. The only time you can do such queries from php is in the upgradeTableDb method.

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should implement upgradeTableDb method, see [[Post-release phase#Updating the database schema|Updating the database schema after release]]

Create a game in BGA Studio: Complete Walkthrough

2022-01-18T22:35:40Z

Grandepezzin: /* Level Up */

{{Studio_Framework_Navigation}}

== Introduction ==

This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using BGA Studio framework.

Before you read this material, you must:
* Read the overall presentations of the BGA [[Studio]].
* Some-what know the languages used by BGA Studio: PHP, SQL, HTML, CSS, Javascript
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]
* Create a game using one of the available tutorials. Don't bother with a new game if you have not completed at least one of the tutorials.

If you are stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].
If you're uncomfortable posting on the public forum you can send messages directly to developers who post answers on that forum but NOT the BGA admins.
If you find typos in this wiki - fix it.

== Select a First Game ==

For your first '''real''' game you must either
* Select a game from [https://en.studio.boardgamearena.com/licensing Available Licenses]
* Or from the Public Domain

But what if the game you want is not there? If you are able to successfully publish your first game, you would gain the trust of the BGA admins and they will be happy to assist you in obtaining a license for a game you really want to do or you can request a license yourself. You can read more about game licenses on [[BGA Game licenses]] page.

Once you selected the game but before creating a new project, please take a few seconds to check that someone is not already developing this game. If it is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

Even if you see a few projects with name of the game they may not be active. There are a lot of abandoned game projects. If it's not clear by the status, post to Developers forum asking if anybody actively working on the project or send a message to developers listed for the abandoned projects, and at the same time ask admins on the same forum post to send you graphics for that game if they have them (there a button on [https://en.studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but it will just send email).

If your goal was to fix bugs in an existing project, first try to locate on studio, projects developed by bga admins are not in the studio. Then get read only access to the project and you can create your own as a copy of the existing one. Contact existing project admin about getting write access to the original project or if they willing to take your patches - apply them.

If you want to take over an existing project first ask on forum to see if project is abandoned, then get read only access (via project list) and see if this worth using it, if it has no code or graphics just start from the scratch, don't worry about project name it can be renamed later.

== Create a project ==

If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken use gamenameYOURINITIALS
template, i.e."heartsla". Don't worry too much about the name, if game would be good enough to be publish it will be renamed to original name.

Find and start the game in turn based mode, make sure it works.

Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a no-starter.

Update your project status in [http://en.studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for license" or "waiting for graphics" or combination of those.

== Development Tools ==

At some point you need to setup your development environment which consist of multiple tools, such as
* Editor or IDE
* Browser with dev tools
* File sync tools
* BGA Web tools
* Image manipulation tools
* Version control tools

Please scan though articles from [[Studio#BGA_Studio_user_guide]] especially related to debugging and tools, there is a lot of useful info there.

== Hook version control system ==

If its a real game I would commit the code to version control right at start. You going to find yourself in the situation
when game does not even start anymore and no way of debugging it unless you have a way to revert. That is where version control becomes very handy.
If you don't know what I am talking about then at least back-up your files after each of major steps. Starting now.
You can also create a project on github, but make sure '''you don't commit original publisher graphics files''' and '''you don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).
You can (and should) also commit your modification periodically via studio's control panel.

== Obtain game graphics ==

If you developing a game from Available Licenses games, ask the admins to send you graphics by contacting studio@boardgamearena.com. While that request is being processed (it can take time, as it often requires some back and forth between the admins and the publishers) you can proceed to next step - project creation.

If you don't get original graphics you go to '''Scavenger Hunt'''

* If you developing a public domain card game you can borrow standard cards from BGA generic assets, see [[Common_board_game_elements_image_resources]]
* Standard game pieces - meeples, cubes, dice can be found here as well [[Common_board_game_elements_image_resources]]
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you lucky they also sometime have boards and token scans in "Game Pieces" section of Images
* If that fail google "boardgame <name>" and check Images section
* Get the rules PDF as well, there tools that allows you to extract graphics from PDF, which usually good for meeples, cubes and such (can use pdfimages command line tool)

Once you get the graphics one way or another you have to massage it to fit in the BGA criteria, which usually involves
* If publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down
* For non square tiles and game pieces you need transparency
* Usually you chop off scoring "ring" around the board of the game since scoring track not needed for online adaptation

More details about graphics requirements can be found here [[Game art: img directory]].

[[File:Rrr_search.png]]

== Obtain game documentation ==

Also at this time obtain a electronic copy of rules, such as PDF (English version).

Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such
as cheat-sheets (may be easier to get a data from these then trying to scrub pdf). You create and place them in the doc/ folder of the project then
exclude them from version control. There is also a misc/ folder now but it will hold up to 1 Mb of data files which would be checked in, so rules pdf's may not fit there.

== Update game infos and box graphics ==

Even it does not nothing yet start with making sure game looks descent in the game selector, meaning it has nice box graphics and information is correct.

For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].
What you would do for real game you would go to http://boardgamegeek.com find the game and use the information from web-site to fill the gameinfos.

The next step is to replace game_box.png with proper images, usually you can find all images including publisher logo on boardgamegeek website.

Details about images can be found here: [[Game art: img directory]].

Now important step. You have to LOAD these files in studio website through control panel. So go to Control Panel -> Manager Games -> YOURPROJECT
and press Reload for 'Reload game informations' and 'Reload game box image'

[[File:Gamepanel_sharedcode.png]]

Now try to start the game again. If you some-how introduced a syntax error in gameinfos file it may not actually work (game won't start).
Always use "Express Start" button to start the game. You should see a standard state prompt from template. You should see X players on the right, testdude0 .. testdudeX-1.
To switch between them press the red arrow button near their names, it will open another tab. This way you don't need to login and logout from multiple accounts!

== Fix source copyright ==

Now since you have your own project, you want put your name in the copyright header, so replace

© <Your name here> <Your email address here>
with
© John Snow <jsnow@gameofthrones.com>

Well not exactly this but whatever your real name is. For all files in project directory, its about 10 files. Make sure project still starts after that :)

== Reduce the Rules ==

Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of lack of patience or skill.
To keep sane, start the game with *reduced* rules and try to complete that first.

* If it has any expansions - do not even attempt to deal with them, not even - "I will just add graphics for them now and not use" - waste of time if you don't complete basic
* If it has advanced rules - start with basic rules only, i.e. "beginner game"
* If it has special rules for 2 player vs 4, start with most basic form (i.e. 4), restrict to 4 players
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)
* Any sort of rules that you think can be removed and not included in base - set aside for now
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later

== Design Game Elements ==
Technically game elements are already designed by board game designer but your job is to map it to program space.
Each physical piece (card, token, cube) will leave footprints all over the code (unfortunatly in multiple disconnected places).
To prepare the game you need to sort out these elements, i.e. categorize. I usually have to the following categorization (in object oriented view):
* Instance - all individual pieces are instances, i.e. two red cubes are two instances of 'red cube' type (class)
* Type - element type which distinctly represents that element in appearence (i.e. red cube is different type than blue cube)
* Super Type - one of more common types that similar properties (i.e. red OR cube)
* Player color - supertype specific for player color (sometimes there is no colors but like player 1 - but is conceptually the same, I use color because its easier to track)

Personally I like to encode my elements in string using reverse dns notation listing all the properties above, i.e.
meeple_ff0000_7 - this is instance #7 of type meeple_ff0000 (red meeple)
Or
card_yellow_magic_2 - this is instance #2 of yellow card (in this case yellow is color of deck not related to player color) that can do magic

So every game element would be in the

1. Database - instances. The db record would be something like
key|location|state
meeple_ff0000_7|slot_action_2|1
meeple_ff0000_2|tableau_ff0000|0
2. Material file - types and supertypes, we never need repeating info here, so never list individual instances but only types or supertypes, in this case we don't really need to define red meeple vs blue meeple
'meeple'=>{'name'=>totranslate('Meeple')}
3. Client (js, css, tpl, etc) - instances and types. For example my meeple will be like
<pre>
<div id="meeple_ff0000_7" class="meeple meeple_ff0000"></div>
</pre>
with .css something like
.meeple { background-image: url(img/tokens.png); width: 2em; height: 2em;}
.meeple_ff0000 {background-position: 20% 0%;}
4. Game php - setup and logic. During setup you have to generate all the pieces and place them in right positions. Also sometimes you need to reference elements to code the logic (I usually try to encode all rules in material file as much as possible)

For complex card games I think it is the best to keep all these info and rules in spreadsheet and generate other files such as material.inc.php.
See more info below about design of the individual layers.

== Create Initial Layout and Game Graphics ==

Mentally it is easier to start with game layout and graphics pieces. Even when nothing is working its give you moral satisfaction!

There are a few ways how the html could have been generated. You could have started with nothing and generate
it all by javascript, or you could have started with complete game markup in html and make javascript just hide and move pieces around. BGA framework also provides a third way, which is mix of both, plus a template engine to generate HTML using PHP. The only thing that is really annoying about the template engine is that you cannot put any translatable strings in the template (which means any visible text at all). If you are using the template approach all strings have to extracted as variables and injected through PHP (.view.php). This page explains the template engine in great detail:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].

The other disadvantage of the template engine is you cannot run and debug it locally, in the beginning of development it's a lot faster run off local pages,
you can do it with some trickery described here [[Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout|Tools and Tips for BGA Studio]]

During this step you have to decide what technical solutions you will be using, such as
* Use inline positioning of all moving pieces, controlled by JS. There are a few classes that already exist in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contain 200-300 pieces, it seems wrong but actually its faster to type all of this up in html/css when trying write than debug code for page generator.
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.

Start by creating and mapping all games assets, best way is probably to open rule book on "boardgame contents" page and go through every piece. Every pieces of boardgame would have its "print" in multiple files in your game:
* Some sort if "div" in html, where id of element match id of element in database (easiest way)
* Css for the element (either unique or for class), usually with background propery refering to part of sprite image
* Entry in material.inc.php referring to static properties of the element, i.e. name, tooltip, rules, etc
* Entry in .tpl file to represent static or initial location on the table OR creation template

Here are some specific examples:

'''Game Board'''

Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically
<pre>
<div id="board" class="board shadow board4p"> ... </div>
</pre>
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board whcih is diffrent than 2 ppl board)
<pre>
.board {
position: relative;
width: 980px;
height: 433px;
margin-bottom: 5px;
}

.board4p {
background-image: url(img/board4p.jpg);
}
</pre>
That would be pretty much it for the board itself, as it does not really need a tooltip so we don't need entry in material.inc.php

'''Game Board Slots'''

These are interactive areas on the board, usually illustrated as such. In most cases you can get away with rectangular shapes, but sometimes you have to create circle or oval shapes (and in really advanced case would be some svg paths). For slots you can do the following:

Entry in material.inc.php
<pre>
$this->token_types = array(
...
'slot_action_2' => array(
'type' => 'slot_action',
'name' => clienttranslate("2 Gray Track Advancements"),
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),
'o'=>"1,0,0,gg", // automatic rules
),
...
</pre>

Entry in template inside the "board" div
<pre>
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div>
</pre>

Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)
<pre>
.slot_action_2 {
top: 83px;
left: 37px;
}
.slot_action {
position: absolute;
width: 46px;
height: 26px;
padding: 9px 7px 6px 4px;
}
</pre>

'''Meeples''' - also cards, tokens, other mobile stuff

In CSS these guys will use "sprite" images with transparency, so it will look like this this:
<pre>
.meeple {
background-image: url(img/tokens.png);
width: 25px;
height: 25px;
}
.meeple_ff0000 { /* red */
background-position: 14% 0%;
}
</pre>
As for creation you can either generate them using template (where whole thing wrapped in template block and {COLOR} replace with all possible colors in .view.php
<pre>
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div>
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div>
...
</pre>

Or you can declare a template js var in .tpl file
<pre>
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom
</pre>
and create in js, like this
<pre>
var tokenDiv = this.format_block('jstpl_mepple', {
"color" : color,
"num" : i
}); // this in js code somewhere before placing it
</pre>
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.

When do you create dom element matching game element?
* If you have static layout you create it in .tpl file and its always there, but during initial setup or during notification it moved in proper spot (including "removed from the game" spot)
* If you dynamically generated pieces you create the element during notification, and sometimes during animation. Also don't forgot to hook event listener to it if its interactive.

One of the greatest parts about the web is all client side code can be viewed in your browser, so if you wondering how something is done in another BGA game just load the page and spy on it! In Chrome that would be right click and "Inspect Element". That would immediately show html of the given element alongside with css used for it (on the right). Another great way to learn is you can add yourself to any BGA project as read only from the project page!

So at the end of this stage you should complete the following (keeping in mind reduced rules/material for first iteration):
* Create a layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc
* Create css and html snippets for all game pieces: boards, tokens, meeples, etc. Place them all in initial template (even if they're not supposed to be visible at start). I.e. create fake player's hand with cards, put meeples on the board
* Hook layout to number of players and colors picked by the game and test with multiple players
* Figure out what you want to display in mini-player boards and hook it up
* Create material.inc.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements

If at this time you don't have graphics yet create pieces with just CSS, you can use shape, background color and object text using css ::after construct to fake the pieces.

[[File:Injected_text.png]]

== Hook Input and Animation ==

This step can be done before or after some of the server steps, or you go in iterations switching back and forward until you get it done, up to you.

At this time you want to hook clicking on pieces and buttons and provide some reaction, such of moving a piece. The handler code will be replaced later by the server hook, but at the beginning you want your game to be alive as early as possible.

Usually all pieces will be hooked to onclick during JS "setup" method, in addition if you create elements during server notification they have to be hooked up at that time.

You can play with animation effects you want put in place, in general all the pieces that move in real game should be moving, such as meeples, resources tokens/cubes, cards, vp tokens.
Regular piece animation is provided by BGA framework, but if you use html layout positioning not inline positioning you have to remove absolute positions (inline position styling) after each move. The set of functions for relative position token animation can found in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js

Also its a good idea to give player a visual cues on what game elements are clickable now, usually it will be a style, such as "active_slot", with visual effect of white dashed outline (outline is better then border, because border changes will make piece slightly move since it changes the size) or box-shadow (i.e. neon glow)

If you read [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] you know that you should not get carried away with animation, you are creating a board game not a video game... That also applies to sound effects (in general, you should not use any sounds effects beside already provided by framework).

See [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]] and [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.

== Create Database Schema ==

At some point you have to design your game database. Do it sooner then later since it would be harder to change it later, since some
code decisions would be based on that.

If you have grid-based abstract game use template from reversi, if you have a card game use template from hearts (the cards one also commented out in generated template for your project). The cards database goes with php class called [[Deck]].

In general make it as simple as possible.
Think about it, your game has 300 pieces (likely less). Using database to store this amount of data is like shooting a mosquito with a tank.
Anything more complex then one table with 5 columns or two tables will only going to make it harder to develop and not improve performance.
You can forget about normalising and any fancy stuff you learn about databases in school. String field for a primary key would be as fast as integer when we talking about this size of data. So don't over-optimize with trying to have integers field that have state based on bitmask!

Also remember that static (non dynamic) information about the game does not need to be stored in the database, that all include everything that does not change, i.e
all token/card properties such as name, tooltips, "strength", color, etc. This is stored in material.inc.php and server has access to it from anywhere, as well as client
if you send it with getAllDatas(). The only reason store some of it in database if it can affect your queries (i.e. type of token).

Usually design process will contain the following steps:
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model
* Mapping - now map real game to that model
* Encoding - now represent this model in database and material file with reasonable amount of fields

Example: '''The card game'''

* In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it
* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but as part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in your database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position itself usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html
* For dynamic stuff we should try to reduce amount of fields we need, i.e. we need a field for card, so its one, we need to know what zone cards belong to, its 2, and we have possible few other fields, but if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Another Example: '''The euro game'''

See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]

So the piece mapping for non-grid based
games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here:
[https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php tokens.php].

<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

See [[Game database model: dbmodel.sql]] for details about editing the file.

Note: the simpler the database is the less debugging of db issues you have to deal with including database migration. The tokens database above - if you use it you never have to worry about migration because you don't need extra tables in 95% of the games.
Here are some example of how real games are mapped to such database:

'''Chess'''

- chess is grid base game and normally you would use positional columns, but just for the sake of argument, the chess game will look like this
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_white
|f3
|0
|-
|P_black_2
|c6
|0
|-
|K_black
|e8
|1
|}
And the state in this case indicated that kind was moved for example (which means castling cannot be performed)

'''Classic card game'''

Lets pretend we need 2 decks for that game
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_spades_1
|hand_ff0000
|0 /* state not used for hand */
|-
|10_hearts_2
|tableau_ff0000
|2 /* position */
|-
|10_hearts_1
|tableau_common
|1 /* face down */
|}

'''Eminent Domain (card game)'''

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|card_tech_23
|hand_ff0000
|0 /* state not used for hand */
|-
|card_planet_19
|tableau_ff0000
|1 /* face up */
|-
|reource_s_22 /* silicon */
|card_planet_19
|2 /* production state */
|-
|fighter_F_1
|tableau_ff0000
|0
|}

You can also look at other games that use Tokens database and access layer: Nippon, Dungeon Petz, Lewis & Clark, Battleship, Russian Railroads, Khronos

== Implement Game Setup ==

Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page
and implement these step by step populating the database (using db access API).
Game initialization is performed in php method setupNewGame, this method is called once when game table is created.
Game notifications cannot be sent during this time.

== Implement One time game model synchronisation ==

Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix getAllDatas function
to return all possible data we need to reconstruct the game. The template for getAllDatas already taking care of player info, but you
have to alter it to return all other data from database visible to the "current" player.

After that on the client side we should display this data, so in your .js file in setup function (which is the receiver of getAllDatas) you add calls that handle data send by server, usually by calling animation function such as "placeToken" or "placeCard".

== Create State Machine ==

Now you need to create a game state machine.

The state handling spread across 4 files, so you have to make sure all the pieces are connected together.
The state machine states.inc.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

Please first watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine]
and then please read [[Your game state machine: states.inc.php]].

Now the state machine should be relatively simple. If you find yourself with machine with more than 20 states its probably not the way to go.
Not all the player interactions need separate states, a lot of things can be implemented directly on client, i.e. if your player need to select
a reward token, which offers choice of resource, instead of two states on server just have one state on server and possible few states on client (client side states)
to collect this info.

== Handle Turn Order ==

If your game goes in clockwise order in natural sitting position nothing really needed you just use standard API and you are good. However if position is complecated
it may require some trickery.

Usually turn order is done by "game state" (see state machine above). Basically it would be two choices:
* Turn order depends on game situation (such as we take player with highest number of red cubes)
* Turn order is custom and assign on previos step - i.e. we not playing in clockwise order anymore. In this case you either need to extend player table with new order info (CANNOT use player_no column) or use order markers that come with game (i.e. marker_ff0000 on position_1). In this we can build player array in right order and pick next player based on previous player using existing helper function such as $this->createNextPlayerTable($player_ids)

== Implement Notification handling ==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications send by server.
So previously we hooked onclick js handler right to client animation, in real game its a two
step operation. When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].

Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want
to avoid sending data to server until step is complete (which may involve direct client side animation). See [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Selection|Multi-Step Interactions]]

Part of the sending notifications would be to update player's scoring, BGA uses standard control for score (on JS side), see [[Game_interface_logic:_yourgamename.js#Update_players_score|Update Player's Score]].

In BGA there is only two ways interact with the server (officially)
* Initial data dump - when JS client starts it gets all current data via setup() method
* Game actions - ajaxcall from client, it returns error or ok (not data), then server send butch of notifications to client

Note current ajaxcall is super vebosy and prone to errors, I suggest to use helper function. It does a lot of stuff you must do anyways.
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = []; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server

if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, its is optional param - you rarely need it
}
},
</pre>

When you insert a single action you have to update multiples files:
* in ggg.js add ajaxcall, i.e. something like
this.addActionButton('pass',_('Pass'),()=>this.ajaxcallwrapper('pass'));
* in states.php - add action 'pass' to list of possible actions
'possibleactions' => ['pass','playCard']
* in action.php - add action hander, see https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php
* in game.php - add action hander, there you must do the following
** call checkAction to validate the action
** possible do more game specific check to validate what player doing is legal (even its not possible from your js side - player can cheat - not allow that)
** do some database maniplations, using access api
** send notifications - this is the "reply" for action
** transition to new state (it very rare that user will remain in the same state, except for multi-active states)
* back to ggg.js add notification subsciption and notification handler (two separate things)

== Wrap Up ==

* Implement game progression (getGameProgression() in php)
* Implement Zombie turn (zombieTurn() in php)
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
* The games logs should explain what happened if player was not looking
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Make sure all UI strings are marked for translation
* UI elements which are images (i.e. tokens, cards) should have tooltips

== Alpha ==
When you think you game is completely working there is still bunch of stuff you have to do/check before telling admin that game is ready, please go though this [[Pre-release checklist]].

If you think its completely ready, let admin know (studio@boardgamearena.com) and it they will push it to alpha.

Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:
* Links to the rules (in multiple languages if available).
* Links to teaching videos.
* In the "On the web" section, links to:
** The official website for the game (if there is one).
** The BoardGameGeek page for the game.
* Consider writing a summary of the rules.

== Level Up ==

When you successfully created a basic game and you want more, it's time to make it fancy!

* Add game externtions and variants using gameoptions file
* Add user preferences for customizations
* Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs
* You can use fancy scoring board at the end of game instead of default nothing
* And finally super cool dice rolling, card flipping and victory points evaporating effects

Create a game in BGA Studio: Complete Walkthrough

2022-01-18T22:35:15Z

Grandepezzin: /* Wrap Up */

{{Studio_Framework_Navigation}}

== Introduction ==

This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using BGA Studio framework.

Before you read this material, you must:
* Read the overall presentations of the BGA [[Studio]].
* Some-what know the languages used by BGA Studio: PHP, SQL, HTML, CSS, Javascript
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]
* Create a game using one of the available tutorials. Don't bother with a new game if you have not completed at least one of the tutorials.

If you are stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].
If you're uncomfortable posting on the public forum you can send messages directly to developers who post answers on that forum but NOT the BGA admins.
If you find typos in this wiki - fix it.

== Select a First Game ==

For your first '''real''' game you must either
* Select a game from [https://en.studio.boardgamearena.com/licensing Available Licenses]
* Or from the Public Domain

But what if the game you want is not there? If you are able to successfully publish your first game, you would gain the trust of the BGA admins and they will be happy to assist you in obtaining a license for a game you really want to do or you can request a license yourself. You can read more about game licenses on [[BGA Game licenses]] page.

Once you selected the game but before creating a new project, please take a few seconds to check that someone is not already developing this game. If it is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

Even if you see a few projects with name of the game they may not be active. There are a lot of abandoned game projects. If it's not clear by the status, post to Developers forum asking if anybody actively working on the project or send a message to developers listed for the abandoned projects, and at the same time ask admins on the same forum post to send you graphics for that game if they have them (there a button on [https://en.studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but it will just send email).

If your goal was to fix bugs in an existing project, first try to locate on studio, projects developed by bga admins are not in the studio. Then get read only access to the project and you can create your own as a copy of the existing one. Contact existing project admin about getting write access to the original project or if they willing to take your patches - apply them.

If you want to take over an existing project first ask on forum to see if project is abandoned, then get read only access (via project list) and see if this worth using it, if it has no code or graphics just start from the scratch, don't worry about project name it can be renamed later.

== Create a project ==

If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken use gamenameYOURINITIALS
template, i.e."heartsla". Don't worry too much about the name, if game would be good enough to be publish it will be renamed to original name.

Find and start the game in turn based mode, make sure it works.

Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a no-starter.

Update your project status in [http://en.studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for license" or "waiting for graphics" or combination of those.

== Development Tools ==

At some point you need to setup your development environment which consist of multiple tools, such as
* Editor or IDE
* Browser with dev tools
* File sync tools
* BGA Web tools
* Image manipulation tools
* Version control tools

Please scan though articles from [[Studio#BGA_Studio_user_guide]] especially related to debugging and tools, there is a lot of useful info there.

== Hook version control system ==

If its a real game I would commit the code to version control right at start. You going to find yourself in the situation
when game does not even start anymore and no way of debugging it unless you have a way to revert. That is where version control becomes very handy.
If you don't know what I am talking about then at least back-up your files after each of major steps. Starting now.
You can also create a project on github, but make sure '''you don't commit original publisher graphics files''' and '''you don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).
You can (and should) also commit your modification periodically via studio's control panel.

== Obtain game graphics ==

If you developing a game from Available Licenses games, ask the admins to send you graphics by contacting studio@boardgamearena.com. While that request is being processed (it can take time, as it often requires some back and forth between the admins and the publishers) you can proceed to next step - project creation.

If you don't get original graphics you go to '''Scavenger Hunt'''

* If you developing a public domain card game you can borrow standard cards from BGA generic assets, see [[Common_board_game_elements_image_resources]]
* Standard game pieces - meeples, cubes, dice can be found here as well [[Common_board_game_elements_image_resources]]
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you lucky they also sometime have boards and token scans in "Game Pieces" section of Images
* If that fail google "boardgame <name>" and check Images section
* Get the rules PDF as well, there tools that allows you to extract graphics from PDF, which usually good for meeples, cubes and such (can use pdfimages command line tool)

Once you get the graphics one way or another you have to massage it to fit in the BGA criteria, which usually involves
* If publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down
* For non square tiles and game pieces you need transparency
* Usually you chop off scoring "ring" around the board of the game since scoring track not needed for online adaptation

More details about graphics requirements can be found here [[Game art: img directory]].

[[File:Rrr_search.png]]

== Obtain game documentation ==

Also at this time obtain a electronic copy of rules, such as PDF (English version).

Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such
as cheat-sheets (may be easier to get a data from these then trying to scrub pdf). You create and place them in the doc/ folder of the project then
exclude them from version control. There is also a misc/ folder now but it will hold up to 1 Mb of data files which would be checked in, so rules pdf's may not fit there.

== Update game infos and box graphics ==

Even it does not nothing yet start with making sure game looks descent in the game selector, meaning it has nice box graphics and information is correct.

For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].
What you would do for real game you would go to http://boardgamegeek.com find the game and use the information from web-site to fill the gameinfos.

The next step is to replace game_box.png with proper images, usually you can find all images including publisher logo on boardgamegeek website.

Details about images can be found here: [[Game art: img directory]].

Now important step. You have to LOAD these files in studio website through control panel. So go to Control Panel -> Manager Games -> YOURPROJECT
and press Reload for 'Reload game informations' and 'Reload game box image'

[[File:Gamepanel_sharedcode.png]]

Now try to start the game again. If you some-how introduced a syntax error in gameinfos file it may not actually work (game won't start).
Always use "Express Start" button to start the game. You should see a standard state prompt from template. You should see X players on the right, testdude0 .. testdudeX-1.
To switch between them press the red arrow button near their names, it will open another tab. This way you don't need to login and logout from multiple accounts!

== Fix source copyright ==

Now since you have your own project, you want put your name in the copyright header, so replace

© <Your name here> <Your email address here>
with
© John Snow <jsnow@gameofthrones.com>

Well not exactly this but whatever your real name is. For all files in project directory, its about 10 files. Make sure project still starts after that :)

== Reduce the Rules ==

Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of lack of patience or skill.
To keep sane, start the game with *reduced* rules and try to complete that first.

* If it has any expansions - do not even attempt to deal with them, not even - "I will just add graphics for them now and not use" - waste of time if you don't complete basic
* If it has advanced rules - start with basic rules only, i.e. "beginner game"
* If it has special rules for 2 player vs 4, start with most basic form (i.e. 4), restrict to 4 players
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)
* Any sort of rules that you think can be removed and not included in base - set aside for now
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later

== Design Game Elements ==
Technically game elements are already designed by board game designer but your job is to map it to program space.
Each physical piece (card, token, cube) will leave footprints all over the code (unfortunatly in multiple disconnected places).
To prepare the game you need to sort out these elements, i.e. categorize. I usually have to the following categorization (in object oriented view):
* Instance - all individual pieces are instances, i.e. two red cubes are two instances of 'red cube' type (class)
* Type - element type which distinctly represents that element in appearence (i.e. red cube is different type than blue cube)
* Super Type - one of more common types that similar properties (i.e. red OR cube)
* Player color - supertype specific for player color (sometimes there is no colors but like player 1 - but is conceptually the same, I use color because its easier to track)

Personally I like to encode my elements in string using reverse dns notation listing all the properties above, i.e.
meeple_ff0000_7 - this is instance #7 of type meeple_ff0000 (red meeple)
Or
card_yellow_magic_2 - this is instance #2 of yellow card (in this case yellow is color of deck not related to player color) that can do magic

So every game element would be in the

1. Database - instances. The db record would be something like
key|location|state
meeple_ff0000_7|slot_action_2|1
meeple_ff0000_2|tableau_ff0000|0
2. Material file - types and supertypes, we never need repeating info here, so never list individual instances but only types or supertypes, in this case we don't really need to define red meeple vs blue meeple
'meeple'=>{'name'=>totranslate('Meeple')}
3. Client (js, css, tpl, etc) - instances and types. For example my meeple will be like
<pre>
<div id="meeple_ff0000_7" class="meeple meeple_ff0000"></div>
</pre>
with .css something like
.meeple { background-image: url(img/tokens.png); width: 2em; height: 2em;}
.meeple_ff0000 {background-position: 20% 0%;}
4. Game php - setup and logic. During setup you have to generate all the pieces and place them in right positions. Also sometimes you need to reference elements to code the logic (I usually try to encode all rules in material file as much as possible)

For complex card games I think it is the best to keep all these info and rules in spreadsheet and generate other files such as material.inc.php.
See more info below about design of the individual layers.

== Create Initial Layout and Game Graphics ==

Mentally it is easier to start with game layout and graphics pieces. Even when nothing is working its give you moral satisfaction!

There are a few ways how the html could have been generated. You could have started with nothing and generate
it all by javascript, or you could have started with complete game markup in html and make javascript just hide and move pieces around. BGA framework also provides a third way, which is mix of both, plus a template engine to generate HTML using PHP. The only thing that is really annoying about the template engine is that you cannot put any translatable strings in the template (which means any visible text at all). If you are using the template approach all strings have to extracted as variables and injected through PHP (.view.php). This page explains the template engine in great detail:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].

The other disadvantage of the template engine is you cannot run and debug it locally, in the beginning of development it's a lot faster run off local pages,
you can do it with some trickery described here [[Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout|Tools and Tips for BGA Studio]]

During this step you have to decide what technical solutions you will be using, such as
* Use inline positioning of all moving pieces, controlled by JS. There are a few classes that already exist in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contain 200-300 pieces, it seems wrong but actually its faster to type all of this up in html/css when trying write than debug code for page generator.
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.

Start by creating and mapping all games assets, best way is probably to open rule book on "boardgame contents" page and go through every piece. Every pieces of boardgame would have its "print" in multiple files in your game:
* Some sort if "div" in html, where id of element match id of element in database (easiest way)
* Css for the element (either unique or for class), usually with background propery refering to part of sprite image
* Entry in material.inc.php referring to static properties of the element, i.e. name, tooltip, rules, etc
* Entry in .tpl file to represent static or initial location on the table OR creation template

Here are some specific examples:

'''Game Board'''

Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically
<pre>
<div id="board" class="board shadow board4p"> ... </div>
</pre>
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board whcih is diffrent than 2 ppl board)
<pre>
.board {
position: relative;
width: 980px;
height: 433px;
margin-bottom: 5px;
}

.board4p {
background-image: url(img/board4p.jpg);
}
</pre>
That would be pretty much it for the board itself, as it does not really need a tooltip so we don't need entry in material.inc.php

'''Game Board Slots'''

These are interactive areas on the board, usually illustrated as such. In most cases you can get away with rectangular shapes, but sometimes you have to create circle or oval shapes (and in really advanced case would be some svg paths). For slots you can do the following:

Entry in material.inc.php
<pre>
$this->token_types = array(
...
'slot_action_2' => array(
'type' => 'slot_action',
'name' => clienttranslate("2 Gray Track Advancements"),
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),
'o'=>"1,0,0,gg", // automatic rules
),
...
</pre>

Entry in template inside the "board" div
<pre>
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div>
</pre>

Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)
<pre>
.slot_action_2 {
top: 83px;
left: 37px;
}
.slot_action {
position: absolute;
width: 46px;
height: 26px;
padding: 9px 7px 6px 4px;
}
</pre>

'''Meeples''' - also cards, tokens, other mobile stuff

In CSS these guys will use "sprite" images with transparency, so it will look like this this:
<pre>
.meeple {
background-image: url(img/tokens.png);
width: 25px;
height: 25px;
}
.meeple_ff0000 { /* red */
background-position: 14% 0%;
}
</pre>
As for creation you can either generate them using template (where whole thing wrapped in template block and {COLOR} replace with all possible colors in .view.php
<pre>
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div>
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div>
...
</pre>

Or you can declare a template js var in .tpl file
<pre>
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom
</pre>
and create in js, like this
<pre>
var tokenDiv = this.format_block('jstpl_mepple', {
"color" : color,
"num" : i
}); // this in js code somewhere before placing it
</pre>
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.

When do you create dom element matching game element?
* If you have static layout you create it in .tpl file and its always there, but during initial setup or during notification it moved in proper spot (including "removed from the game" spot)
* If you dynamically generated pieces you create the element during notification, and sometimes during animation. Also don't forgot to hook event listener to it if its interactive.

One of the greatest parts about the web is all client side code can be viewed in your browser, so if you wondering how something is done in another BGA game just load the page and spy on it! In Chrome that would be right click and "Inspect Element". That would immediately show html of the given element alongside with css used for it (on the right). Another great way to learn is you can add yourself to any BGA project as read only from the project page!

So at the end of this stage you should complete the following (keeping in mind reduced rules/material for first iteration):
* Create a layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc
* Create css and html snippets for all game pieces: boards, tokens, meeples, etc. Place them all in initial template (even if they're not supposed to be visible at start). I.e. create fake player's hand with cards, put meeples on the board
* Hook layout to number of players and colors picked by the game and test with multiple players
* Figure out what you want to display in mini-player boards and hook it up
* Create material.inc.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements

If at this time you don't have graphics yet create pieces with just CSS, you can use shape, background color and object text using css ::after construct to fake the pieces.

[[File:Injected_text.png]]

== Hook Input and Animation ==

This step can be done before or after some of the server steps, or you go in iterations switching back and forward until you get it done, up to you.

At this time you want to hook clicking on pieces and buttons and provide some reaction, such of moving a piece. The handler code will be replaced later by the server hook, but at the beginning you want your game to be alive as early as possible.

Usually all pieces will be hooked to onclick during JS "setup" method, in addition if you create elements during server notification they have to be hooked up at that time.

You can play with animation effects you want put in place, in general all the pieces that move in real game should be moving, such as meeples, resources tokens/cubes, cards, vp tokens.
Regular piece animation is provided by BGA framework, but if you use html layout positioning not inline positioning you have to remove absolute positions (inline position styling) after each move. The set of functions for relative position token animation can found in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js

Also its a good idea to give player a visual cues on what game elements are clickable now, usually it will be a style, such as "active_slot", with visual effect of white dashed outline (outline is better then border, because border changes will make piece slightly move since it changes the size) or box-shadow (i.e. neon glow)

If you read [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] you know that you should not get carried away with animation, you are creating a board game not a video game... That also applies to sound effects (in general, you should not use any sounds effects beside already provided by framework).

See [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]] and [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.

== Create Database Schema ==

At some point you have to design your game database. Do it sooner then later since it would be harder to change it later, since some
code decisions would be based on that.

If you have grid-based abstract game use template from reversi, if you have a card game use template from hearts (the cards one also commented out in generated template for your project). The cards database goes with php class called [[Deck]].

In general make it as simple as possible.
Think about it, your game has 300 pieces (likely less). Using database to store this amount of data is like shooting a mosquito with a tank.
Anything more complex then one table with 5 columns or two tables will only going to make it harder to develop and not improve performance.
You can forget about normalising and any fancy stuff you learn about databases in school. String field for a primary key would be as fast as integer when we talking about this size of data. So don't over-optimize with trying to have integers field that have state based on bitmask!

Also remember that static (non dynamic) information about the game does not need to be stored in the database, that all include everything that does not change, i.e
all token/card properties such as name, tooltips, "strength", color, etc. This is stored in material.inc.php and server has access to it from anywhere, as well as client
if you send it with getAllDatas(). The only reason store some of it in database if it can affect your queries (i.e. type of token).

Usually design process will contain the following steps:
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model
* Mapping - now map real game to that model
* Encoding - now represent this model in database and material file with reasonable amount of fields

Example: '''The card game'''

* In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it
* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but as part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in your database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position itself usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html
* For dynamic stuff we should try to reduce amount of fields we need, i.e. we need a field for card, so its one, we need to know what zone cards belong to, its 2, and we have possible few other fields, but if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Another Example: '''The euro game'''

See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]

So the piece mapping for non-grid based
games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here:
[https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php tokens.php].

<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

See [[Game database model: dbmodel.sql]] for details about editing the file.

Note: the simpler the database is the less debugging of db issues you have to deal with including database migration. The tokens database above - if you use it you never have to worry about migration because you don't need extra tables in 95% of the games.
Here are some example of how real games are mapped to such database:

'''Chess'''

- chess is grid base game and normally you would use positional columns, but just for the sake of argument, the chess game will look like this
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_white
|f3
|0
|-
|P_black_2
|c6
|0
|-
|K_black
|e8
|1
|}
And the state in this case indicated that kind was moved for example (which means castling cannot be performed)

'''Classic card game'''

Lets pretend we need 2 decks for that game
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_spades_1
|hand_ff0000
|0 /* state not used for hand */
|-
|10_hearts_2
|tableau_ff0000
|2 /* position */
|-
|10_hearts_1
|tableau_common
|1 /* face down */
|}

'''Eminent Domain (card game)'''

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|card_tech_23
|hand_ff0000
|0 /* state not used for hand */
|-
|card_planet_19
|tableau_ff0000
|1 /* face up */
|-
|reource_s_22 /* silicon */
|card_planet_19
|2 /* production state */
|-
|fighter_F_1
|tableau_ff0000
|0
|}

You can also look at other games that use Tokens database and access layer: Nippon, Dungeon Petz, Lewis & Clark, Battleship, Russian Railroads, Khronos

== Implement Game Setup ==

Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page
and implement these step by step populating the database (using db access API).
Game initialization is performed in php method setupNewGame, this method is called once when game table is created.
Game notifications cannot be sent during this time.

== Implement One time game model synchronisation ==

Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix getAllDatas function
to return all possible data we need to reconstruct the game. The template for getAllDatas already taking care of player info, but you
have to alter it to return all other data from database visible to the "current" player.

After that on the client side we should display this data, so in your .js file in setup function (which is the receiver of getAllDatas) you add calls that handle data send by server, usually by calling animation function such as "placeToken" or "placeCard".

== Create State Machine ==

Now you need to create a game state machine.

The state handling spread across 4 files, so you have to make sure all the pieces are connected together.
The state machine states.inc.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

Please first watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine]
and then please read [[Your game state machine: states.inc.php]].

Now the state machine should be relatively simple. If you find yourself with machine with more than 20 states its probably not the way to go.
Not all the player interactions need separate states, a lot of things can be implemented directly on client, i.e. if your player need to select
a reward token, which offers choice of resource, instead of two states on server just have one state on server and possible few states on client (client side states)
to collect this info.

== Handle Turn Order ==

If your game goes in clockwise order in natural sitting position nothing really needed you just use standard API and you are good. However if position is complecated
it may require some trickery.

Usually turn order is done by "game state" (see state machine above). Basically it would be two choices:
* Turn order depends on game situation (such as we take player with highest number of red cubes)
* Turn order is custom and assign on previos step - i.e. we not playing in clockwise order anymore. In this case you either need to extend player table with new order info (CANNOT use player_no column) or use order markers that come with game (i.e. marker_ff0000 on position_1). In this we can build player array in right order and pick next player based on previous player using existing helper function such as $this->createNextPlayerTable($player_ids)

== Implement Notification handling ==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications send by server.
So previously we hooked onclick js handler right to client animation, in real game its a two
step operation. When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].

Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want
to avoid sending data to server until step is complete (which may involve direct client side animation). See [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Selection|Multi-Step Interactions]]

Part of the sending notifications would be to update player's scoring, BGA uses standard control for score (on JS side), see [[Game_interface_logic:_yourgamename.js#Update_players_score|Update Player's Score]].

In BGA there is only two ways interact with the server (officially)
* Initial data dump - when JS client starts it gets all current data via setup() method
* Game actions - ajaxcall from client, it returns error or ok (not data), then server send butch of notifications to client

Note current ajaxcall is super vebosy and prone to errors, I suggest to use helper function. It does a lot of stuff you must do anyways.
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = []; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server

if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, its is optional param - you rarely need it
}
},
</pre>

When you insert a single action you have to update multiples files:
* in ggg.js add ajaxcall, i.e. something like
this.addActionButton('pass',_('Pass'),()=>this.ajaxcallwrapper('pass'));
* in states.php - add action 'pass' to list of possible actions
'possibleactions' => ['pass','playCard']
* in action.php - add action hander, see https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php
* in game.php - add action hander, there you must do the following
** call checkAction to validate the action
** possible do more game specific check to validate what player doing is legal (even its not possible from your js side - player can cheat - not allow that)
** do some database maniplations, using access api
** send notifications - this is the "reply" for action
** transition to new state (it very rare that user will remain in the same state, except for multi-active states)
* back to ggg.js add notification subsciption and notification handler (two separate things)

== Wrap Up ==

* Implement game progression (getGameProgression() in php)
* Implement Zombie turn (zombieTurn() in php)
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
* The games logs should explain what happened if player was not looking
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Make sure all UI strings are marked for translation
* UI elements which are images (i.e. tokens, cards) should have tooltips

== Alpha ==
When you think you game is completely working there is still bunch of stuff you have to do/check before telling admin that game is ready, please go though this [[Pre-release checklist]].

If you think its completely ready, let admin know (studio@boardgamearena.com) and it they will push it to alpha.

Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:
* Links to the rules (in multiple languages if available).
* Links to teaching videos.
* In the "On the web" section, links to:
** The official website for the game (if there is one).
** The BoardGameGeek page for the game.
* Consider writing a summary of the rules.

== Level Up ==

When you successfully created a basic game and you want more, its time to make it fancy!

* Add game externtions and variants using gameoptions file
* Add user preferences for customizations
* Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs
* You can use fancy scoring board at the end of game instead of default nothing
* And finally super cool dice rolling, card flipping and victory points evaporating effects

Create a game in BGA Studio: Complete Walkthrough

2022-01-18T22:33:49Z

Grandepezzin: /* Create Initial Layout and Game Graphics */

{{Studio_Framework_Navigation}}

== Introduction ==

This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using BGA Studio framework.

Before you read this material, you must:
* Read the overall presentations of the BGA [[Studio]].
* Some-what know the languages used by BGA Studio: PHP, SQL, HTML, CSS, Javascript
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]
* Create a game using one of the available tutorials. Don't bother with a new game if you have not completed at least one of the tutorials.

If you are stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].
If you're uncomfortable posting on the public forum you can send messages directly to developers who post answers on that forum but NOT the BGA admins.
If you find typos in this wiki - fix it.

== Select a First Game ==

For your first '''real''' game you must either
* Select a game from [https://en.studio.boardgamearena.com/licensing Available Licenses]
* Or from the Public Domain

But what if the game you want is not there? If you are able to successfully publish your first game, you would gain the trust of the BGA admins and they will be happy to assist you in obtaining a license for a game you really want to do or you can request a license yourself. You can read more about game licenses on [[BGA Game licenses]] page.

Once you selected the game but before creating a new project, please take a few seconds to check that someone is not already developing this game. If it is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

Even if you see a few projects with name of the game they may not be active. There are a lot of abandoned game projects. If it's not clear by the status, post to Developers forum asking if anybody actively working on the project or send a message to developers listed for the abandoned projects, and at the same time ask admins on the same forum post to send you graphics for that game if they have them (there a button on [https://en.studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but it will just send email).

If your goal was to fix bugs in an existing project, first try to locate on studio, projects developed by bga admins are not in the studio. Then get read only access to the project and you can create your own as a copy of the existing one. Contact existing project admin about getting write access to the original project or if they willing to take your patches - apply them.

If you want to take over an existing project first ask on forum to see if project is abandoned, then get read only access (via project list) and see if this worth using it, if it has no code or graphics just start from the scratch, don't worry about project name it can be renamed later.

== Create a project ==

If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken use gamenameYOURINITIALS
template, i.e."heartsla". Don't worry too much about the name, if game would be good enough to be publish it will be renamed to original name.

Find and start the game in turn based mode, make sure it works.

Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a no-starter.

Update your project status in [http://en.studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for license" or "waiting for graphics" or combination of those.

== Development Tools ==

At some point you need to setup your development environment which consist of multiple tools, such as
* Editor or IDE
* Browser with dev tools
* File sync tools
* BGA Web tools
* Image manipulation tools
* Version control tools

Please scan though articles from [[Studio#BGA_Studio_user_guide]] especially related to debugging and tools, there is a lot of useful info there.

== Hook version control system ==

If its a real game I would commit the code to version control right at start. You going to find yourself in the situation
when game does not even start anymore and no way of debugging it unless you have a way to revert. That is where version control becomes very handy.
If you don't know what I am talking about then at least back-up your files after each of major steps. Starting now.
You can also create a project on github, but make sure '''you don't commit original publisher graphics files''' and '''you don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).
You can (and should) also commit your modification periodically via studio's control panel.

== Obtain game graphics ==

If you developing a game from Available Licenses games, ask the admins to send you graphics by contacting studio@boardgamearena.com. While that request is being processed (it can take time, as it often requires some back and forth between the admins and the publishers) you can proceed to next step - project creation.

If you don't get original graphics you go to '''Scavenger Hunt'''

* If you developing a public domain card game you can borrow standard cards from BGA generic assets, see [[Common_board_game_elements_image_resources]]
* Standard game pieces - meeples, cubes, dice can be found here as well [[Common_board_game_elements_image_resources]]
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you lucky they also sometime have boards and token scans in "Game Pieces" section of Images
* If that fail google "boardgame <name>" and check Images section
* Get the rules PDF as well, there tools that allows you to extract graphics from PDF, which usually good for meeples, cubes and such (can use pdfimages command line tool)

Once you get the graphics one way or another you have to massage it to fit in the BGA criteria, which usually involves
* If publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down
* For non square tiles and game pieces you need transparency
* Usually you chop off scoring "ring" around the board of the game since scoring track not needed for online adaptation

More details about graphics requirements can be found here [[Game art: img directory]].

[[File:Rrr_search.png]]

== Obtain game documentation ==

Also at this time obtain a electronic copy of rules, such as PDF (English version).

Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such
as cheat-sheets (may be easier to get a data from these then trying to scrub pdf). You create and place them in the doc/ folder of the project then
exclude them from version control. There is also a misc/ folder now but it will hold up to 1 Mb of data files which would be checked in, so rules pdf's may not fit there.

== Update game infos and box graphics ==

Even it does not nothing yet start with making sure game looks descent in the game selector, meaning it has nice box graphics and information is correct.

For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].
What you would do for real game you would go to http://boardgamegeek.com find the game and use the information from web-site to fill the gameinfos.

The next step is to replace game_box.png with proper images, usually you can find all images including publisher logo on boardgamegeek website.

Details about images can be found here: [[Game art: img directory]].

Now important step. You have to LOAD these files in studio website through control panel. So go to Control Panel -> Manager Games -> YOURPROJECT
and press Reload for 'Reload game informations' and 'Reload game box image'

[[File:Gamepanel_sharedcode.png]]

Now try to start the game again. If you some-how introduced a syntax error in gameinfos file it may not actually work (game won't start).
Always use "Express Start" button to start the game. You should see a standard state prompt from template. You should see X players on the right, testdude0 .. testdudeX-1.
To switch between them press the red arrow button near their names, it will open another tab. This way you don't need to login and logout from multiple accounts!

== Fix source copyright ==

Now since you have your own project, you want put your name in the copyright header, so replace

© <Your name here> <Your email address here>
with
© John Snow <jsnow@gameofthrones.com>

Well not exactly this but whatever your real name is. For all files in project directory, its about 10 files. Make sure project still starts after that :)

== Reduce the Rules ==

Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of lack of patience or skill.
To keep sane, start the game with *reduced* rules and try to complete that first.

* If it has any expansions - do not even attempt to deal with them, not even - "I will just add graphics for them now and not use" - waste of time if you don't complete basic
* If it has advanced rules - start with basic rules only, i.e. "beginner game"
* If it has special rules for 2 player vs 4, start with most basic form (i.e. 4), restrict to 4 players
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)
* Any sort of rules that you think can be removed and not included in base - set aside for now
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later

== Design Game Elements ==
Technically game elements are already designed by board game designer but your job is to map it to program space.
Each physical piece (card, token, cube) will leave footprints all over the code (unfortunatly in multiple disconnected places).
To prepare the game you need to sort out these elements, i.e. categorize. I usually have to the following categorization (in object oriented view):
* Instance - all individual pieces are instances, i.e. two red cubes are two instances of 'red cube' type (class)
* Type - element type which distinctly represents that element in appearence (i.e. red cube is different type than blue cube)
* Super Type - one of more common types that similar properties (i.e. red OR cube)
* Player color - supertype specific for player color (sometimes there is no colors but like player 1 - but is conceptually the same, I use color because its easier to track)

Personally I like to encode my elements in string using reverse dns notation listing all the properties above, i.e.
meeple_ff0000_7 - this is instance #7 of type meeple_ff0000 (red meeple)
Or
card_yellow_magic_2 - this is instance #2 of yellow card (in this case yellow is color of deck not related to player color) that can do magic

So every game element would be in the

1. Database - instances. The db record would be something like
key|location|state
meeple_ff0000_7|slot_action_2|1
meeple_ff0000_2|tableau_ff0000|0
2. Material file - types and supertypes, we never need repeating info here, so never list individual instances but only types or supertypes, in this case we don't really need to define red meeple vs blue meeple
'meeple'=>{'name'=>totranslate('Meeple')}
3. Client (js, css, tpl, etc) - instances and types. For example my meeple will be like
<pre>
<div id="meeple_ff0000_7" class="meeple meeple_ff0000"></div>
</pre>
with .css something like
.meeple { background-image: url(img/tokens.png); width: 2em; height: 2em;}
.meeple_ff0000 {background-position: 20% 0%;}
4. Game php - setup and logic. During setup you have to generate all the pieces and place them in right positions. Also sometimes you need to reference elements to code the logic (I usually try to encode all rules in material file as much as possible)

For complex card games I think it is the best to keep all these info and rules in spreadsheet and generate other files such as material.inc.php.
See more info below about design of the individual layers.

== Create Initial Layout and Game Graphics ==

Mentally it is easier to start with game layout and graphics pieces. Even when nothing is working its give you moral satisfaction!

There are a few ways how the html could have been generated. You could have started with nothing and generate
it all by javascript, or you could have started with complete game markup in html and make javascript just hide and move pieces around. BGA framework also provides a third way, which is mix of both, plus a template engine to generate HTML using PHP. The only thing that is really annoying about the template engine is that you cannot put any translatable strings in the template (which means any visible text at all). If you are using the template approach all strings have to extracted as variables and injected through PHP (.view.php). This page explains the template engine in great detail:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].

The other disadvantage of the template engine is you cannot run and debug it locally, in the beginning of development it's a lot faster run off local pages,
you can do it with some trickery described here [[Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout|Tools and Tips for BGA Studio]]

During this step you have to decide what technical solutions you will be using, such as
* Use inline positioning of all moving pieces, controlled by JS. There are a few classes that already exist in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contain 200-300 pieces, it seems wrong but actually its faster to type all of this up in html/css when trying write than debug code for page generator.
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.

Start by creating and mapping all games assets, best way is probably to open rule book on "boardgame contents" page and go through every piece. Every pieces of boardgame would have its "print" in multiple files in your game:
* Some sort if "div" in html, where id of element match id of element in database (easiest way)
* Css for the element (either unique or for class), usually with background propery refering to part of sprite image
* Entry in material.inc.php referring to static properties of the element, i.e. name, tooltip, rules, etc
* Entry in .tpl file to represent static or initial location on the table OR creation template

Here are some specific examples:

'''Game Board'''

Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically
<pre>
<div id="board" class="board shadow board4p"> ... </div>
</pre>
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board whcih is diffrent than 2 ppl board)
<pre>
.board {
position: relative;
width: 980px;
height: 433px;
margin-bottom: 5px;
}

.board4p {
background-image: url(img/board4p.jpg);
}
</pre>
That would be pretty much it for the board itself, as it does not really need a tooltip so we don't need entry in material.inc.php

'''Game Board Slots'''

These are interactive areas on the board, usually illustrated as such. In most cases you can get away with rectangular shapes, but sometimes you have to create circle or oval shapes (and in really advanced case would be some svg paths). For slots you can do the following:

Entry in material.inc.php
<pre>
$this->token_types = array(
...
'slot_action_2' => array(
'type' => 'slot_action',
'name' => clienttranslate("2 Gray Track Advancements"),
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),
'o'=>"1,0,0,gg", // automatic rules
),
...
</pre>

Entry in template inside the "board" div
<pre>
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div>
</pre>

Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)
<pre>
.slot_action_2 {
top: 83px;
left: 37px;
}
.slot_action {
position: absolute;
width: 46px;
height: 26px;
padding: 9px 7px 6px 4px;
}
</pre>

'''Meeples''' - also cards, tokens, other mobile stuff

In CSS these guys will use "sprite" images with transparency, so it will look like this this:
<pre>
.meeple {
background-image: url(img/tokens.png);
width: 25px;
height: 25px;
}
.meeple_ff0000 { /* red */
background-position: 14% 0%;
}
</pre>
As for creation you can either generate them using template (where whole thing wrapped in template block and {COLOR} replace with all possible colors in .view.php
<pre>
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div>
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div>
...
</pre>

Or you can declare a template js var in .tpl file
<pre>
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom
</pre>
and create in js, like this
<pre>
var tokenDiv = this.format_block('jstpl_mepple', {
"color" : color,
"num" : i
}); // this in js code somewhere before placing it
</pre>
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.

When do you create dom element matching game element?
* If you have static layout you create it in .tpl file and its always there, but during initial setup or during notification it moved in proper spot (including "removed from the game" spot)
* If you dynamically generated pieces you create the element during notification, and sometimes during animation. Also don't forgot to hook event listener to it if its interactive.

One of the greatest parts about the web is all client side code can be viewed in your browser, so if you wondering how something is done in another BGA game just load the page and spy on it! In Chrome that would be right click and "Inspect Element". That would immediately show html of the given element alongside with css used for it (on the right). Another great way to learn is you can add yourself to any BGA project as read only from the project page!

So at the end of this stage you should complete the following (keeping in mind reduced rules/material for first iteration):
* Create a layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc
* Create css and html snippets for all game pieces: boards, tokens, meeples, etc. Place them all in initial template (even if they're not supposed to be visible at start). I.e. create fake player's hand with cards, put meeples on the board
* Hook layout to number of players and colors picked by the game and test with multiple players
* Figure out what you want to display in mini-player boards and hook it up
* Create material.inc.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements

If at this time you don't have graphics yet create pieces with just CSS, you can use shape, background color and object text using css ::after construct to fake the pieces.

[[File:Injected_text.png]]

== Hook Input and Animation ==

This step can be done before or after some of the server steps, or you go in iterations switching back and forward until you get it done, up to you.

At this time you want to hook clicking on pieces and buttons and provide some reaction, such of moving a piece. The handler code will be replaced later by the server hook, but at the beginning you want your game to be alive as early as possible.

Usually all pieces will be hooked to onclick during JS "setup" method, in addition if you create elements during server notification they have to be hooked up at that time.

You can play with animation effects you want put in place, in general all the pieces that move in real game should be moving, such as meeples, resources tokens/cubes, cards, vp tokens.
Regular piece animation is provided by BGA framework, but if you use html layout positioning not inline positioning you have to remove absolute positions (inline position styling) after each move. The set of functions for relative position token animation can found in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js

Also its a good idea to give player a visual cues on what game elements are clickable now, usually it will be a style, such as "active_slot", with visual effect of white dashed outline (outline is better then border, because border changes will make piece slightly move since it changes the size) or box-shadow (i.e. neon glow)

If you read [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] you know that you should not get carried away with animation, you are creating a board game not a video game... That also applies to sound effects (in general, you should not use any sounds effects beside already provided by framework).

See [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]] and [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.

== Create Database Schema ==

At some point you have to design your game database. Do it sooner then later since it would be harder to change it later, since some
code decisions would be based on that.

If you have grid-based abstract game use template from reversi, if you have a card game use template from hearts (the cards one also commented out in generated template for your project). The cards database goes with php class called [[Deck]].

In general make it as simple as possible.
Think about it, your game has 300 pieces (likely less). Using database to store this amount of data is like shooting a mosquito with a tank.
Anything more complex then one table with 5 columns or two tables will only going to make it harder to develop and not improve performance.
You can forget about normalising and any fancy stuff you learn about databases in school. String field for a primary key would be as fast as integer when we talking about this size of data. So don't over-optimize with trying to have integers field that have state based on bitmask!

Also remember that static (non dynamic) information about the game does not need to be stored in the database, that all include everything that does not change, i.e
all token/card properties such as name, tooltips, "strength", color, etc. This is stored in material.inc.php and server has access to it from anywhere, as well as client
if you send it with getAllDatas(). The only reason store some of it in database if it can affect your queries (i.e. type of token).

Usually design process will contain the following steps:
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model
* Mapping - now map real game to that model
* Encoding - now represent this model in database and material file with reasonable amount of fields

Example: '''The card game'''

* In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it
* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but as part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in your database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position itself usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html
* For dynamic stuff we should try to reduce amount of fields we need, i.e. we need a field for card, so its one, we need to know what zone cards belong to, its 2, and we have possible few other fields, but if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Another Example: '''The euro game'''

See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]

So the piece mapping for non-grid based
games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here:
[https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php tokens.php].

<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

See [[Game database model: dbmodel.sql]] for details about editing the file.

Note: the simpler the database is the less debugging of db issues you have to deal with including database migration. The tokens database above - if you use it you never have to worry about migration because you don't need extra tables in 95% of the games.
Here are some example of how real games are mapped to such database:

'''Chess'''

- chess is grid base game and normally you would use positional columns, but just for the sake of argument, the chess game will look like this
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_white
|f3
|0
|-
|P_black_2
|c6
|0
|-
|K_black
|e8
|1
|}
And the state in this case indicated that kind was moved for example (which means castling cannot be performed)

'''Classic card game'''

Lets pretend we need 2 decks for that game
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_spades_1
|hand_ff0000
|0 /* state not used for hand */
|-
|10_hearts_2
|tableau_ff0000
|2 /* position */
|-
|10_hearts_1
|tableau_common
|1 /* face down */
|}

'''Eminent Domain (card game)'''

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|card_tech_23
|hand_ff0000
|0 /* state not used for hand */
|-
|card_planet_19
|tableau_ff0000
|1 /* face up */
|-
|reource_s_22 /* silicon */
|card_planet_19
|2 /* production state */
|-
|fighter_F_1
|tableau_ff0000
|0
|}

You can also look at other games that use Tokens database and access layer: Nippon, Dungeon Petz, Lewis & Clark, Battleship, Russian Railroads, Khronos

== Implement Game Setup ==

Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page
and implement these step by step populating the database (using db access API).
Game initialization is performed in php method setupNewGame, this method is called once when game table is created.
Game notifications cannot be sent during this time.

== Implement One time game model synchronisation ==

Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix getAllDatas function
to return all possible data we need to reconstruct the game. The template for getAllDatas already taking care of player info, but you
have to alter it to return all other data from database visible to the "current" player.

After that on the client side we should display this data, so in your .js file in setup function (which is the receiver of getAllDatas) you add calls that handle data send by server, usually by calling animation function such as "placeToken" or "placeCard".

== Create State Machine ==

Now you need to create a game state machine.

The state handling spread across 4 files, so you have to make sure all the pieces are connected together.
The state machine states.inc.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

Please first watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine]
and then please read [[Your game state machine: states.inc.php]].

Now the state machine should be relatively simple. If you find yourself with machine with more than 20 states its probably not the way to go.
Not all the player interactions need separate states, a lot of things can be implemented directly on client, i.e. if your player need to select
a reward token, which offers choice of resource, instead of two states on server just have one state on server and possible few states on client (client side states)
to collect this info.

== Handle Turn Order ==

If your game goes in clockwise order in natural sitting position nothing really needed you just use standard API and you are good. However if position is complecated
it may require some trickery.

Usually turn order is done by "game state" (see state machine above). Basically it would be two choices:
* Turn order depends on game situation (such as we take player with highest number of red cubes)
* Turn order is custom and assign on previos step - i.e. we not playing in clockwise order anymore. In this case you either need to extend player table with new order info (CANNOT use player_no column) or use order markers that come with game (i.e. marker_ff0000 on position_1). In this we can build player array in right order and pick next player based on previous player using existing helper function such as $this->createNextPlayerTable($player_ids)

== Implement Notification handling ==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications send by server.
So previously we hooked onclick js handler right to client animation, in real game its a two
step operation. When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].

Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want
to avoid sending data to server until step is complete (which may involve direct client side animation). See [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Selection|Multi-Step Interactions]]

Part of the sending notifications would be to update player's scoring, BGA uses standard control for score (on JS side), see [[Game_interface_logic:_yourgamename.js#Update_players_score|Update Player's Score]].

In BGA there is only two ways interact with the server (officially)
* Initial data dump - when JS client starts it gets all current data via setup() method
* Game actions - ajaxcall from client, it returns error or ok (not data), then server send butch of notifications to client

Note current ajaxcall is super vebosy and prone to errors, I suggest to use helper function. It does a lot of stuff you must do anyways.
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = []; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server

if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, its is optional param - you rarely need it
}
},
</pre>

When you insert a single action you have to update multiples files:
* in ggg.js add ajaxcall, i.e. something like
this.addActionButton('pass',_('Pass'),()=>this.ajaxcallwrapper('pass'));
* in states.php - add action 'pass' to list of possible actions
'possibleactions' => ['pass','playCard']
* in action.php - add action hander, see https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php
* in game.php - add action hander, there you must do the following
** call checkAction to validate the action
** possible do more game specific check to validate what player doing is legal (even its not possible from your js side - player can cheat - not allow that)
** do some database maniplations, using access api
** send notifications - this is the "reply" for action
** transition to new state (it very rare that user will remain in the same state, except for multi-active states)
* back to ggg.js add notification subsciption and notification handler (two separate things)

== Wrap Up ==

* Implement game progression (getGameProgression() in php)
* Implement Zombie turn (zombieTurn() in php)
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
* The games logs should explain what happened if player was not looking
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Make sure all UI strings are marked for translation
* UI elements which are images (i.e. tokens, cards) should have tooltips

== Alpha ==
When you think you game is completely working there is still bunch of stuff you have to do/check before telling admin that game is ready, please go though this [[Pre-release checklist]].

If you think its completely ready, let admin know (studio@boardgamearena.com) and it they will push it to alpha.

Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:
* Links to the rules (in multiple languages if available).
* Links to teaching videos.
* In the "On the web" section, links to:
** The official website for the game (if there is one).
** The BoardGameGeek page for the game.
* Consider writing a summary of the rules.

== Level Up ==

When you successfully created a basic game and you want more, its time to make it fancy!

* Add game externtions and variants using gameoptions file
* Add user preferences for customizations
* Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs
* You can use fancy scoring board at the end of game instead of default nothing
* And finally super cool dice rolling, card flipping and victory points evaporating effects

Create a game in BGA Studio: Complete Walkthrough

2022-01-18T22:31:28Z

Grandepezzin: /* Create Initial Layout and Game Graphics */

{{Studio_Framework_Navigation}}

== Introduction ==

This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using BGA Studio framework.

Before you read this material, you must:
* Read the overall presentations of the BGA [[Studio]].
* Some-what know the languages used by BGA Studio: PHP, SQL, HTML, CSS, Javascript
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]
* Create a game using one of the available tutorials. Don't bother with a new game if you have not completed at least one of the tutorials.

If you are stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].
If you're uncomfortable posting on the public forum you can send messages directly to developers who post answers on that forum but NOT the BGA admins.
If you find typos in this wiki - fix it.

== Select a First Game ==

For your first '''real''' game you must either
* Select a game from [https://en.studio.boardgamearena.com/licensing Available Licenses]
* Or from the Public Domain

But what if the game you want is not there? If you are able to successfully publish your first game, you would gain the trust of the BGA admins and they will be happy to assist you in obtaining a license for a game you really want to do or you can request a license yourself. You can read more about game licenses on [[BGA Game licenses]] page.

Once you selected the game but before creating a new project, please take a few seconds to check that someone is not already developing this game. If it is the case, maybe you can propose to join the project?

[http://en.studio.boardgamearena.com/#!projects Check the list of current projects]

Even if you see a few projects with name of the game they may not be active. There are a lot of abandoned game projects. If it's not clear by the status, post to Developers forum asking if anybody actively working on the project or send a message to developers listed for the abandoned projects, and at the same time ask admins on the same forum post to send you graphics for that game if they have them (there a button on [https://en.studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but it will just send email).

If your goal was to fix bugs in an existing project, first try to locate on studio, projects developed by bga admins are not in the studio. Then get read only access to the project and you can create your own as a copy of the existing one. Contact existing project admin about getting write access to the original project or if they willing to take your patches - apply them.

If you want to take over an existing project first ask on forum to see if project is abandoned, then get read only access (via project list) and see if this worth using it, if it has no code or graphics just start from the scratch, don't worry about project name it can be renamed later.

== Create a project ==

If you have not already, you have to create a project in BGA Studio for this game. If the original game name is taken use gamenameYOURINITIALS
template, i.e."heartsla". Don't worry too much about the name, if game would be good enough to be publish it will be renamed to original name.

Find and start the game in turn based mode, make sure it works.

Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.
Note: if you have not setup [http://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#File_Sync FTP auto-sync] yet, do it now, manually copying files is a no-starter.

Update your project status in [http://en.studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for license" or "waiting for graphics" or combination of those.

== Development Tools ==

At some point you need to setup your development environment which consist of multiple tools, such as
* Editor or IDE
* Browser with dev tools
* File sync tools
* BGA Web tools
* Image manipulation tools
* Version control tools

Please scan though articles from [[Studio#BGA_Studio_user_guide]] especially related to debugging and tools, there is a lot of useful info there.

== Hook version control system ==

If its a real game I would commit the code to version control right at start. You going to find yourself in the situation
when game does not even start anymore and no way of debugging it unless you have a way to revert. That is where version control becomes very handy.
If you don't know what I am talking about then at least back-up your files after each of major steps. Starting now.
You can also create a project on github, but make sure '''you don't commit original publisher graphics files''' and '''you don't include a file with your sftp password''' (github is automatically crawled for passwords by hackers; a hacking attempt occurred on BGA studio for this reason in June 2020).
You can (and should) also commit your modification periodically via studio's control panel.

== Obtain game graphics ==

If you developing a game from Available Licenses games, ask the admins to send you graphics by contacting studio@boardgamearena.com. While that request is being processed (it can take time, as it often requires some back and forth between the admins and the publishers) you can proceed to next step - project creation.

If you don't get original graphics you go to '''Scavenger Hunt'''

* If you developing a public domain card game you can borrow standard cards from BGA generic assets, see [[Common_board_game_elements_image_resources]]
* Standard game pieces - meeples, cubes, dice can be found here as well [[Common_board_game_elements_image_resources]]
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you lucky they also sometime have boards and token scans in "Game Pieces" section of Images
* If that fail google "boardgame <name>" and check Images section
* Get the rules PDF as well, there tools that allows you to extract graphics from PDF, which usually good for meeples, cubes and such (can use pdfimages command line tool)

Once you get the graphics one way or another you have to massage it to fit in the BGA criteria, which usually involves
* If publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down
* For non square tiles and game pieces you need transparency
* Usually you chop off scoring "ring" around the board of the game since scoring track not needed for online adaptation

More details about graphics requirements can be found here [[Game art: img directory]].

[[File:Rrr_search.png]]

== Obtain game documentation ==

Also at this time obtain a electronic copy of rules, such as PDF (English version).

Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such
as cheat-sheets (may be easier to get a data from these then trying to scrub pdf). You create and place them in the doc/ folder of the project then
exclude them from version control. There is also a misc/ folder now but it will hold up to 1 Mb of data files which would be checked in, so rules pdf's may not fit there.

== Update game infos and box graphics ==

Even it does not nothing yet start with making sure game looks descent in the game selector, meaning it has nice box graphics and information is correct.

For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].
What you would do for real game you would go to http://boardgamegeek.com find the game and use the information from web-site to fill the gameinfos.

The next step is to replace game_box.png with proper images, usually you can find all images including publisher logo on boardgamegeek website.

Details about images can be found here: [[Game art: img directory]].

Now important step. You have to LOAD these files in studio website through control panel. So go to Control Panel -> Manager Games -> YOURPROJECT
and press Reload for 'Reload game informations' and 'Reload game box image'

[[File:Gamepanel_sharedcode.png]]

Now try to start the game again. If you some-how introduced a syntax error in gameinfos file it may not actually work (game won't start).
Always use "Express Start" button to start the game. You should see a standard state prompt from template. You should see X players on the right, testdude0 .. testdudeX-1.
To switch between them press the red arrow button near their names, it will open another tab. This way you don't need to login and logout from multiple accounts!

== Fix source copyright ==

Now since you have your own project, you want put your name in the copyright header, so replace

© <Your name here> <Your email address here>
with
© John Snow <jsnow@gameofthrones.com>

Well not exactly this but whatever your real name is. For all files in project directory, its about 10 files. Make sure project still starts after that :)

== Reduce the Rules ==

Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of lack of patience or skill.
To keep sane, start the game with *reduced* rules and try to complete that first.

* If it has any expansions - do not even attempt to deal with them, not even - "I will just add graphics for them now and not use" - waste of time if you don't complete basic
* If it has advanced rules - start with basic rules only, i.e. "beginner game"
* If it has special rules for 2 player vs 4, start with most basic form (i.e. 4), restrict to 4 players
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)
* Any sort of rules that you think can be removed and not included in base - set aside for now
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later

== Design Game Elements ==
Technically game elements are already designed by board game designer but your job is to map it to program space.
Each physical piece (card, token, cube) will leave footprints all over the code (unfortunatly in multiple disconnected places).
To prepare the game you need to sort out these elements, i.e. categorize. I usually have to the following categorization (in object oriented view):
* Instance - all individual pieces are instances, i.e. two red cubes are two instances of 'red cube' type (class)
* Type - element type which distinctly represents that element in appearence (i.e. red cube is different type than blue cube)
* Super Type - one of more common types that similar properties (i.e. red OR cube)
* Player color - supertype specific for player color (sometimes there is no colors but like player 1 - but is conceptually the same, I use color because its easier to track)

Personally I like to encode my elements in string using reverse dns notation listing all the properties above, i.e.
meeple_ff0000_7 - this is instance #7 of type meeple_ff0000 (red meeple)
Or
card_yellow_magic_2 - this is instance #2 of yellow card (in this case yellow is color of deck not related to player color) that can do magic

So every game element would be in the

1. Database - instances. The db record would be something like
key|location|state
meeple_ff0000_7|slot_action_2|1
meeple_ff0000_2|tableau_ff0000|0
2. Material file - types and supertypes, we never need repeating info here, so never list individual instances but only types or supertypes, in this case we don't really need to define red meeple vs blue meeple
'meeple'=>{'name'=>totranslate('Meeple')}
3. Client (js, css, tpl, etc) - instances and types. For example my meeple will be like
<pre>
<div id="meeple_ff0000_7" class="meeple meeple_ff0000"></div>
</pre>
with .css something like
.meeple { background-image: url(img/tokens.png); width: 2em; height: 2em;}
.meeple_ff0000 {background-position: 20% 0%;}
4. Game php - setup and logic. During setup you have to generate all the pieces and place them in right positions. Also sometimes you need to reference elements to code the logic (I usually try to encode all rules in material file as much as possible)

For complex card games I think it is the best to keep all these info and rules in spreadsheet and generate other files such as material.inc.php.
See more info below about design of the individual layers.

== Create Initial Layout and Game Graphics ==

Mentally it is easier to start with game layout and graphics pieces. Even when nothing is working its give you moral satisfaction!

There are a few ways how the html could have been generated. You could have started with nothing and generate
it all by javascript, or you could have started with complete game markup in html and make javascript just hide and move pieces around. BGA framework also provides a third way, which is mix of both, plus a template engine to generate HTML using PHP. The only thing that is really annoying about the template engine is that you cannot put any translatable strings in the template (which means any visible text at all). If you are using the template approach all strings have to extracted as variables and injected through PHP (.view.php). This page explains the template engine in great detail:[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl|Template Engine]].

The other disadvantage of the template engine is you cannot run and debug it locally, in the beginning of development it's a lot faster run off local pages,
you can do it with some trickery described here [[Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout|Tools and Tips for BGA Studio]]

During this step you have to decide what technical solutions you will be using, such as
* Use inline positioning of all moving pieces, controlled by JS. There are a few classes that already exist in Studio to help with that (see [[Studio#Game_interface_.28Client_side.29|Game Interface - Client Side]]). OR use html/css layout engine to position pieces (my personal choice).
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contain 200-300 pieces, it seems wrong but actually its faster to type all of this up in html/css when trying write than debug code for page generator.
Static HTML markup also means you have to use players color or abstracted player number (such as red is 1, blue is 2) not player id's anywhere in JS, since player id is dynamic by nature.

Start by creating and mapping all games assets, best way is probably to open rule book on "boardgame contents" page and go through every piece. Every pieces of boardgame would have its "print" in multiple files in your game:
* Some sort if "div" in html, where id of element match id of element in database (easiest way)
* Css for the element (either unique or for class), usually with background propery refering to part of sprite image
* Entry in material.inc.php referring to static properties of the element, i.e. name, tooltip, rules, etc
* Entry in .tpl file to represent static or initial location on the table OR creation template

Here are some specific examples:

'''Game Board'''

Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically
<pre>
<div id="board" class="board shadow board4p"> ... </div>
</pre>
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board whcih is diffrent than 2 ppl board)
<pre>
.board {
position: relative;
width: 980px;
height: 433px;
margin-bottom: 5px;
}

.board4p {
background-image: url(img/board4p.jpg);
}
</pre>
That wold be pretty much it for the board itself, as it does not really need a tooltip so we don't need entry in material.inc.php

'''Game Board Slots'''

These are interactive areas on the board, usually illustrated as such. In most cases you can get away with rectangular shapes, but sometimes you have to create circle or oval shapes (and in really advanced case would be some svg paths). For slots you can do the following:

Entry in material.inc.php
<pre>
$this->token_types = array(
...
'slot_action_2' => array(
'type' => 'slot_action',
'name' => clienttranslate("2 Gray Track Advancements"),
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),
'o'=>"1,0,0,gg", // automatic rules
),
...
</pre>

Entry in template inside the "board" div
<pre>
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div>
</pre>

Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)
<pre>
.slot_action_2 {
top: 83px;
left: 37px;
}
.slot_action {
position: absolute;
width: 46px;
height: 26px;
padding: 9px 7px 6px 4px;
}
</pre>

'''Meeples''' - also cards, tokens, other mobile stuff

In css these guys will use "sprite" images with transparency, so it will look like this this
<pre>
.meeple {
background-image: url(img/tokens.png);
width: 25px;
height: 25px;
}
.meeple_ff0000 { /* red */
background-position: 14% 0%;
}
</pre>
As for creation you can either generate them using template (where whole thing wrapped in template block and {COLOR} replace with all possible colors in .view.php
<pre>
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div>
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div>
...
</pre>

Or you can declare a template js var in .tpl file
<pre>
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom
</pre>
and create in js, like this
<pre>
var tokenDiv = this.format_block('jstpl_mepple', {
"color" : color,
"num" : i
}); // this in js code somewhere before placing it
</pre>
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.

When do you create dom element matching game element?
* If you have static layout you create it in .tpl file and its always there, but during initial setup or during notification it moved in proper spot (including "removed from the game" spot)
* If you dynamically generated pieces you create the element during notification, and sometimes during animation. Also don't forgot to hook event listener to it if its interactive.

One of the greatest parts about the web is all client side code can be viewed in your browser, so if you wondering how something is done in another BGA game just load the page and spy on it! In Chrome that would be right click and "Inspect Element". That would immediately show html of the given element alongside with css used for it (on the right). Another great way to learn is you can add yourself to any BGA project as read only from the project page!

So at the end of this stage you should complete the following (keeping in mind reduced rules/material for first iteration):
* Create a layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc
* Create css and html snippets for all game pieces: boards, tokens, meeples, etc. Place them all in initial template (even if they're not supposed to be visible at start). I.e. create fake player's hand with cards, put meeples on the board
* Hook layout to number of players and colors picked by the game and test with multiple players
* Figure out what you want to display in mini-player boards and hook it up
* Create material.inc.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements

If at this time you don't have graphics yet create pieces with just css, you can use shape, background color and object text using css ::after construct to fake the pieces.

[[File:Injected_text.png]]

== Hook Input and Animation ==

This step can be done before or after some of the server steps, or you go in iterations switching back and forward until you get it done, up to you.

At this time you want to hook clicking on pieces and buttons and provide some reaction, such of moving a piece. The handler code will be replaced later by the server hook, but at the beginning you want your game to be alive as early as possible.

Usually all pieces will be hooked to onclick during JS "setup" method, in addition if you create elements during server notification they have to be hooked up at that time.

You can play with animation effects you want put in place, in general all the pieces that move in real game should be moving, such as meeples, resources tokens/cubes, cards, vp tokens.
Regular piece animation is provided by BGA framework, but if you use html layout positioning not inline positioning you have to remove absolute positions (inline position styling) after each move. The set of functions for relative position token animation can found in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js

Also its a good idea to give player a visual cues on what game elements are clickable now, usually it will be a style, such as "active_slot", with visual effect of white dashed outline (outline is better then border, because border changes will make piece slightly move since it changes the size) or box-shadow (i.e. neon glow)

If you read [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] you know that you should not get carried away with animation, you are creating a board game not a video game... That also applies to sound effects (in general, you should not use any sounds effects beside already provided by framework).

See [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]] and [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.

== Create Database Schema ==

At some point you have to design your game database. Do it sooner then later since it would be harder to change it later, since some
code decisions would be based on that.

If you have grid-based abstract game use template from reversi, if you have a card game use template from hearts (the cards one also commented out in generated template for your project). The cards database goes with php class called [[Deck]].

In general make it as simple as possible.
Think about it, your game has 300 pieces (likely less). Using database to store this amount of data is like shooting a mosquito with a tank.
Anything more complex then one table with 5 columns or two tables will only going to make it harder to develop and not improve performance.
You can forget about normalising and any fancy stuff you learn about databases in school. String field for a primary key would be as fast as integer when we talking about this size of data. So don't over-optimize with trying to have integers field that have state based on bitmask!

Also remember that static (non dynamic) information about the game does not need to be stored in the database, that all include everything that does not change, i.e
all token/card properties such as name, tooltips, "strength", color, etc. This is stored in material.inc.php and server has access to it from anywhere, as well as client
if you send it with getAllDatas(). The only reason store some of it in database if it can affect your queries (i.e. type of token).

Usually design process will contain the following steps:
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model
* Mapping - now map real game to that model
* Encoding - now represent this model in database and material file with reasonable amount of fields

Example: '''The card game'''

* In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it
* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but as part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in your database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position itself usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html
* For dynamic stuff we should try to reduce amount of fields we need, i.e. we need a field for card, so its one, we need to know what zone cards belong to, its 2, and we have possible few other fields, but if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).
<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Another Example: '''The euro game'''

See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]

So the piece mapping for non-grid based
games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here:
[https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php tokens.php].

<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

See [[Game database model: dbmodel.sql]] for details about editing the file.

Note: the simpler the database is the less debugging of db issues you have to deal with including database migration. The tokens database above - if you use it you never have to worry about migration because you don't need extra tables in 95% of the games.
Here are some example of how real games are mapped to such database:

'''Chess'''

- chess is grid base game and normally you would use positional columns, but just for the sake of argument, the chess game will look like this
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_white
|f3
|0
|-
|P_black_2
|c6
|0
|-
|K_black
|e8
|1
|}
And the state in this case indicated that kind was moved for example (which means castling cannot be performed)

'''Classic card game'''

Lets pretend we need 2 decks for that game
{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|Q_spades_1
|hand_ff0000
|0 /* state not used for hand */
|-
|10_hearts_2
|tableau_ff0000
|2 /* position */
|-
|10_hearts_1
|tableau_common
|1 /* face down */
|}

'''Eminent Domain (card game)'''

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|card_tech_23
|hand_ff0000
|0 /* state not used for hand */
|-
|card_planet_19
|tableau_ff0000
|1 /* face up */
|-
|reource_s_22 /* silicon */
|card_planet_19
|2 /* production state */
|-
|fighter_F_1
|tableau_ff0000
|0
|}

You can also look at other games that use Tokens database and access layer: Nippon, Dungeon Petz, Lewis & Clark, Battleship, Russian Railroads, Khronos

== Implement Game Setup ==

Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page
and implement these step by step populating the database (using db access API).
Game initialization is performed in php method setupNewGame, this method is called once when game table is created.
Game notifications cannot be sent during this time.

== Implement One time game model synchronisation ==

Now at any point in the game we need to make sure that database information can be reflected back in UI, so we fix getAllDatas function
to return all possible data we need to reconstruct the game. The template for getAllDatas already taking care of player info, but you
have to alter it to return all other data from database visible to the "current" player.

After that on the client side we should display this data, so in your .js file in setup function (which is the receiver of getAllDatas) you add calls that handle data send by server, usually by calling animation function such as "placeToken" or "placeCard".

== Create State Machine ==

Now you need to create a game state machine.

The state handling spread across 4 files, so you have to make sure all the pieces are connected together.
The state machine states.inc.php defines all the states, and function handlers on php side in a form of string,
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.

Please first watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine]
and then please read [[Your game state machine: states.inc.php]].

Now the state machine should be relatively simple. If you find yourself with machine with more than 20 states its probably not the way to go.
Not all the player interactions need separate states, a lot of things can be implemented directly on client, i.e. if your player need to select
a reward token, which offers choice of resource, instead of two states on server just have one state on server and possible few states on client (client side states)
to collect this info.

== Handle Turn Order ==

If your game goes in clockwise order in natural sitting position nothing really needed you just use standard API and you are good. However if position is complecated
it may require some trickery.

Usually turn order is done by "game state" (see state machine above). Basically it would be two choices:
* Turn order depends on game situation (such as we take player with highest number of red cubes)
* Turn order is custom and assign on previos step - i.e. we not playing in clockwise order anymore. In this case you either need to extend player table with new order info (CANNOT use player_no column) or use order markers that come with game (i.e. marker_ff0000 on position_1). In this we can build player array in right order and pick next player based on previous player using existing helper function such as $this->createNextPlayerTable($player_ids)

== Implement Notification handling ==

Now to implement things for real we have hook UI actions to ajax calls, and process notifications send by server.
So previously we hooked onclick js handler right to client animation, in real game its a two
step operation. When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends
notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].

Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want
to avoid sending data to server until step is complete (which may involve direct client side animation). See [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Selection|Multi-Step Interactions]]

Part of the sending notifications would be to update player's scoring, BGA uses standard control for score (on JS side), see [[Game_interface_logic:_yourgamename.js#Update_players_score|Update Player's Score]].

In BGA there is only two ways interact with the server (officially)
* Initial data dump - when JS client starts it gets all current data via setup() method
* Game actions - ajaxcall from client, it returns error or ok (not data), then server send butch of notifications to client

Note current ajaxcall is super vebosy and prone to errors, I suggest to use helper function. It does a lot of stuff you must do anyways.
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = []; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server

if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, its is optional param - you rarely need it
}
},
</pre>

When you insert a single action you have to update multiples files:
* in ggg.js add ajaxcall, i.e. something like
this.addActionButton('pass',_('Pass'),()=>this.ajaxcallwrapper('pass'));
* in states.php - add action 'pass' to list of possible actions
'possibleactions' => ['pass','playCard']
* in action.php - add action hander, see https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php
* in game.php - add action hander, there you must do the following
** call checkAction to validate the action
** possible do more game specific check to validate what player doing is legal (even its not possible from your js side - player can cheat - not allow that)
** do some database maniplations, using access api
** send notifications - this is the "reply" for action
** transition to new state (it very rare that user will remain in the same state, except for multi-active states)
* back to ggg.js add notification subsciption and notification handler (two separate things)

== Wrap Up ==

* Implement game progression (getGameProgression() in php)
* Implement Zombie turn (zombieTurn() in php)
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)
* The games logs should explain what happened if player was not looking
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data
* Make sure all UI strings are marked for translation
* UI elements which are images (i.e. tokens, cards) should have tooltips

== Alpha ==
When you think you game is completely working there is still bunch of stuff you have to do/check before telling admin that game is ready, please go though this [[Pre-release checklist]].

If you think its completely ready, let admin know (studio@boardgamearena.com) and it they will push it to alpha.

Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:
* Links to the rules (in multiple languages if available).
* Links to teaching videos.
* In the "On the web" section, links to:
** The official website for the game (if there is one).
** The BoardGameGeek page for the game.
* Consider writing a summary of the rules.

== Level Up ==

When you successfully created a basic game and you want more, its time to make it fancy!

* Add game externtions and variants using gameoptions file
* Add user preferences for customizations
* Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs
* You can use fancy scoring board at the end of game instead of default nothing
* And finally super cool dice rolling, card flipping and victory points evaporating effects