http://en.doc.boardgamearena.com/api.php?action=feedcontributions&user=Een&feedformat=atom
Board Game Arena - User contributions [en]
2024-03-28T22:02:20Z
User contributions
MediaWiki 1.39.0
http://en.doc.boardgamearena.com/index.php?title=Gamehelpkoikoi&diff=15962
Gamehelpkoikoi
2023-02-06T17:46:03Z
<p>Een: clarify by using a special section for draws</p>
<hr />
<div>[[Category:Card games]]<br />
== Game play ==<br />
<br />
* Each player is dealt 8 cards and 8 cards are placed in the middle.<br />
* One player goes first.<br />
* If a instant winning hand is dealt it is scored and a new round is started.<br />
** Otherwise play as normal.<br />
* On your turn, you can capture a card in the middle with a card from your hand.<br />
** Those cards must be of the same month.<br />
** Place the card from your hand and the captured card in your winning zone.<br />
* Otherwise you must discard a card and place it in the middle.<br />
* Draw a card from the deck<br />
** You must capture if possible<br />
** Otherwise it is discarded <br />
* If there are 3 cards from the same month they are placed in a stack.<br />
* The player with the last card from that month may capture the stack.<br />
* If you form a ''yaku'' you must either score it or shout ''koi-koi''.<br />
* If scored, you get those points multiplied by the multiplier and the round end.<br />
* If not scored, the round continues and you cannot score that ''yaku'' until you have formed another ''yaku''.<br />
* If an opponent scores a ''yaku'', you lose your points.<br />
* End the game after a number of rounds (or months).<br />
* At the end of the game, the player with the most points (or kobans) wins!<br />
<br />
== About yaku (card combinations) ==<br />
<br />
You can use the '''in game help icon''' to display a popup listing all the possible yaku and how many points they are worth. <br />
<br />
All the yaku are '''combinative''', except the "Bright" cards yaku, which are exclusive (you will always score the biggest available).<br />
<br />
== About multipliers ==<br />
<br />
As is often the case with traditional games, there are a lot of variants for playing Koi-koi, especially in regards to scoring.<br />
<br />
For Board Game Arena, two variants are provided through the options when creating the game:<br />
<br />
=== Soft "Koi!" ===<br />
<br />
Adapted from [http://www.sloperama.com/hanafuda/rules.html the Sloperama site rules] which is all about saying "Koi!".<br />
Of course you run the risk of your opponent making a yaku and scoring for the month (round) before you can score yourself, but in exchange for that risk, each time you will get '''a multiplier''' so that if you manage to increase your score with another yaku, you will score a lot more.<br />
Also, a starting multiplier will be set for the month if some "Bright cards" have been drawn for the field when dealing for the month.<br />
So this is an aggressive variant with a lot of points available if you push your luck.<br />
<br />
=== Hard "Koi!" === <br />
<br />
Adapted from [https://web.archive.org/web/20120421175954/http://hanafubuki.org/koikoi.html the Hanafubuki site rules] which is less incentive to call "Koi!" since you won't get a multiplier just for saying "Koi!". Instead, '''your opponent''' will!<br />
If you say "Koi!" at least once, then if your opponent manages to score their score will be doubled.<br />
Still, at some point you'll risk it, because if you manage to improve your yaku to score 7 points or more, then '''your score''' will be doubled.<br />
<br />
== About draws ==<br />
<br />
Please also note how draws are handled:<br />
* if a month ends by lack of cards in hand and no player has managed to form a yaku, the dealer for the month (first player) gets 6 points ('''"dealer's privilege"''');<br />
* if a month ends by lack of cards in hand and at least a player managed to form a yaku (and said "Koi!" to continue), it's a draw and nobody gets any points.<br />
<br />
== About "Viewing" yaku ==<br />
<br />
A few variants have been implementend for the "Viewing the Moon" and "Viewing the Cherry Blossoms" yaku:<br />
<br />
=== Viewing yaku enabled ===<br />
<br />
Both yaku are available (this is the default).<br />
<br />
=== Rain ruins the party ===<br />
<br />
If a player captures at least one card of November (rain), the party is ruined, both yaku are unavailable for this player.<br />
<br />
=== Viewing yaku disabled ===<br />
<br />
Both yaku are unavailable.<br />
<br />
== About "First play" ==<br />
<br />
Getting the first play (and thus being the first to choose from the field) is a nice advantage.<br />
Some variants have been made available upon request:<br />
<br />
=== Winner starts the next month ===<br />
<br />
The winner for the current month gets to play first the next month (this is the default).<br />
<br />
=== Loser starts the next month ===<br />
<br />
The player who lost this month gets to play first the next month.<br />
<br />
=== Alternate starting player ===<br />
<br />
The player who didn't get to play first this month will play first the following month.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=How_to_join_BGA_developer_team%3F&diff=15595
How to join BGA developer team?
2022-12-21T08:35:17Z
<p>Een: Remove sandbox link (discontinued)</p>
<hr />
<div><br />
== Is this right for me ==<br />
<br />
Before joining please consider if this is right for you, it is right if<br />
* You like board games and programming and you think it would be a good hobby<br />
* You really want to fix some bugs in already published games<br />
* You want to create a game from public domain (e.g. chinese checkers, bridge, etc.)<br />
* You were hired or persuaded by somebody else to create game adaptation on bga<br />
<br />
<br />
On the other hand<br />
<br />
* If you think you can implement any of the games from top 100 on BGG. We checked and we don't have the license to do it, and if we do, it's already implemented or under way.<br />
* If you are an amateur game designer and you think you can play test a game on BGA platform, it's not a right place, players here like known games. Digital adaptations are very expensive (or time consuming) it won't be worth the effort.<br />
* If you trying to use this platform for something which is not a board game adaptation (e.g. video game, online skill test, etc.). It won't be allowed.<br />
* You are a student who just took first your programming course and think it's a good way to practice web skills. BGA Studio is not an easy framework to use, see skill set below.<br />
* If you think you can make make a lot of money of it, it's not going to happen. But recently it has been increase in demand for paid work, so it is possible to make SOME money this way. <br />
<br />
<br />
Required skills for BGA studio projects:<br />
<br />
* If you are an experienced software developer you can goto next section<br />
* If you are not an experienced developer or not a developer <br />
** You are required to know or learn 5 languages: JavaScript, PHP, SQL, HTML and CSS<br />
** You need to know the basics of object oriented programming, web development and database development<br />
** You need to know how to setup and use development tools and setup remote file synchronization<br />
** You need to know how to use image manipulation software (e.g. Paint.net, Gimp, Photoshop, etc.)<br />
<br />
<br />
As a volunteer developer for BGA, what is expected from me?<br />
<br />
* Nothing is really expected (but on the other hand, do not expect much from anybody else)<br />
* If you manage to get your game across finish line (i.e. published) it is generally expected that you will also fix the bugs. But if you cannot - nobody can force you to do anything (but they may take down the game if maintainer cannot be found)<br />
* The code you wrote will remain with BGA and they can do whatever they want with it (but you can also do whatever you want with your own copy)<br />
* There is documentation, forum and chat with other developers available to help<br />
<br />
What do I get out of it?<br />
<br />
* It is fun to develop a game. And you do it all by yourself!!!<br />
* You can greatly improve your web development skills in ancient web technology and dealing with tiny databases<br />
* You can talk directly to game publishers and game designers of your favorite games and even play with them!<br />
* Eventually you will become famous (in small circles of BGA players who read credits)<br />
<br />
== How to create BGA Studio development account ==<br />
<br />
Registering on BGA Studio is simple and automatic from:<br />
https://studio.boardgamearena.com/<br />
<br />
To register, you must agree with [http://en.doc.boardgamearena.com/images/0/02/BGA_TC_Dev_en.pdf '''BGA Terms & Conditions for developers''']. It's very light, so as to get to the fun part faster.\\\\<br />
<br />
During registration if you will get a database error that user already exists ignore it.<br />
<br />
Once registered, you will get by email<br />
* one login / password to access files through SFTP<br />
* one login / password to access the database (for your games in progress)<br />
* ten logins with numeric suffixes from 0 to 9 and a common simple password to test games on the studio website while developing.<br />
<br />
<br />
If you did not get email, search for "Welcome on BGA Studio" in your email client (just like that), it sometimes ends up in junk folder.<br />
<br />
If you cannot find it, and you use some weird proprietary email address, it possible that your mail server denies emails from bga. <br />
You can try to register again with the same email, but it likely fail telling you that your account has already been created. But if you have standard email such as gmail, yahoo, outlook use it instead.<br />
<br />
You can get the welcome email re-sent from the login page using the "Welcome email not received?" link.<br />
In case of a persistent issue, you can file a support request from the [https://studio.boardgamearena.com/support studio support page].<br />
<br />
<br />
== Ok, I registered, how to start? ==<br />
<br />
Then... well that's all, you can start!<br />
<br />
See [[Studio#Great.2C_I.27m_in.21_..._How_should_I_start.3F|Great, I'm in! ... How should I start?]]<br />
<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Pre-release_checklist&diff=15162
Pre-release checklist
2022-10-31T12:56:04Z
<p>Een: </p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
If you think your game is ready to be reviewed by by BGA admins and/or Publisher (aka go to Alpha stage) please consult this checklist first<br />
<br />
=== Move from Dev to Alpha ===<br />
# ''' License '''<br />
## BGA must have a license for the game for a project to be moved to production, even to alpha. If you don't have license yet you can continue checking other stuff from the list below, but at the end it cannot be moved until license situation is cleared.<br />
# ''' Metadata and graphics '''<br />
## [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game. That includes game tags. <b>Important!!!</b> tags are only read during the first deploy.<br />
## Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.<br />
## You have added a game_banner.jpg and some game_displayX.jpg images to make the game page pretty (NB: on the studio, you have to create a build for these images to appear on the studio game page)<br />
## There are no images in the img directory that are not needed anymore<br />
## Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])<br />
## Each image should not exceed 4Mb<br />
## Total size should not exceed 10Mb, image compression should be used otherwise (it also helps a lot to re-encode images as indexed palette vs RBG). If you have legitimate reason to have more than 10Mb (i.e. expansions), you have to make a note of that when requesting move to alpha<br />
## If you use extra fonts, they should be freeware (please include a .txt with the licence information in addition to the font files)<br />
# ''' Server side '''<br />
## When giving their turn to a player, you give them some extra time with the giveExtraTime() function<br />
## Game progression is implemented (getGameProgression() in php)<br />
## Zombie turn is implemented (zombieTurn() in php). Note: it can only be tested if you explicitly click on the quit button to create a zombie. If you are expelled it does not generated a Zombie.<br />
## You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)<br />
## Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)<br />
## You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data<br />
## Database: make sure you do not programmatically manage transactions or call queries that change database schema or even TRUNCATE (queries that would cause implicit commit) during normal game opearations<br />
## Database: make sure you DB schema would be sufficient to complete the game and good enough for possible expantions, changing db schema schema after the release even in alpha is very challenging (it is possible but much better if you don't need to deal with it)<br />
# ''' Client side '''<br />
## Check that you use ajaxcall only on player actions and never initiated programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors. This can also break replays and tutorials. ''Exception: sometimes you can do no-op moves with timeouts (i.e. user has only one choice, but its unwise to reveal this information by skipping user turn), timeout has to be canceling itself if state transition happen automaticaly (i.e. during reply)''<br />
# ''' User Interface '''<br />
## Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]<br />
## Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.<br />
## If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.<br />
## If your game elements become blurry or pixellated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]<br />
## Non-self explanatory graphic elements should have tooltips<br />
## Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.<br />
## A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected<br />
## If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.<br />
# ''' Special testing '''<br />
## Click "Use minified JS" and "Use minified CSS" buttons on the game management page, then test your game. This will prevent you from having a panic attack when the game releases in alpha and it is stuck in "Connecting to game".<br />
## Game is tested with spectator (non player observer): change the testuser in the URL to see the game as another user (same URL as when clicking on red arrow). As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.<br />
## Game is tested with in-game replay from last move feature (by clicking on notification log items).<br />
## After finishing a game, it is possible to watch the replay (using the "Replay game" button on the table page) from game start to game end without errors.<br />
## Game works in Chrome and Firefox browsers at least. Also very recommended to test in Edge and Safari.<br />
## Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)<br />
## Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn<br />
## Test your game in 3D mode (if it makes sense; 3D mode can also be disabled through the 'enable_3d' parameter for gameinfos.inc.php, but if it "mostly works", it can be nice to keep it activated even if 2D is more appropriate for the game, just because it's fun to look at)<br />
## Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]<br />
# ''' Cleanup '''<br />
## Remove all unnecessary console.log and other tracing from your js code (Note: technically it is removed by minimizer, but not console.error)<br />
## Remove all unnecessary debug logging from your php code<br />
## Copyright headers in all source files have your name<br />
## Remove unncessery files from main folder (can move some to misc folder)<br />
## Remove all unused graphics from img/ folder<br />
# ''' Static Analysis '''<br />
## Some of the checks above are automated, to run them go to control panel, go to your project and select "Check project" button (it will open like a game table, and you click on Start button to run analysis)<br />
# ''' Finally move to Alpha status '''<br />
## If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it.<br />
## Create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").<br />
## Really ready? Click on the '''Request ALPHA status''' button available above your just built version. You cannot deploy yourself from the "manage game" page until this first ALPHA deploy has been done by the admins. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed. Note: you can also ask for moving your project to "private Alpha" - in this case you will invite people manually rather than having your game immediately visible to the whole BGA reviewers community. When you press you button you should receive acknowledgement email, you can reply to this email with more details if needed.<br />
* ''' Wait '''<br />
** When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps.<br />
<br />
=== Move from Alpha to Beta ===<br />
# The implementation '''must be approved by the publisher''' (if not a public domain game)<br />
# Generally it is recommended (but not essential) to have at least 10 approvals from reviewer with rank > 3.5 and not too many bugs opened<br />
# If the game is well-received (preferably game rating ≥4.5) and there are no pending issues the game may pass as administrative discretion without 10+ approvals<br />
# Click on the '''Request BETA status''' button available above your latest build. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed.<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Create_a_game_in_BGA_Studio:_Complete_Walkthrough&diff=14772
Create a game in BGA Studio: Complete Walkthrough
2022-09-19T11:32:02Z
<p>Een: Support page</p>
<hr />
<div>== Introduction ==<br />
<br />
This document is not a tutorial, but step by step instructions on how to build your own first game adaptation using BGA Studio framework.<br />
<br />
Before you read this material, you must:<br />
* Read the overall presentations of the BGA [[Studio]].<br />
* Some-what know the languages used by BGA Studio: PHP, SQL, HTML, CSS, Javascript<br />
* Setup your development environment [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]<br />
* 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.<br />
<br />
<br />
If you are stuck or have questions about this page post on [https://forum.boardgamearena.com/viewforum.php?f=12 BGA Developers forum].<br />
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.<br />
If you find typos in this wiki - fix them.<br />
<br />
== Select a First Game ==<br />
<br />
For your first '''real''' game you must either<br />
* Select a game from [https://studio.boardgamearena.com/licensing Available Licenses]<br />
* Or from the Public Domain<br />
<br />
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.<br />
<br />
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?<br />
<br />
[http://studio.boardgamearena.com/#!projects Check the list of current projects]<br />
<br />
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 the 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 to post to send you graphics for that game if they have them (there a button on [https://studio.boardgamearena.com/licensing Available Licenses] page to request graphics, but it will just send an email).<br />
<br />
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.<br />
<br />
If you want to take over an existing project first ask on the forum to see if the project is abandoned, then get read only access (via project list) and see if this is 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.<br />
<br />
== Create a project ==<br />
<br />
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<br />
template, i.e."heartsla". Don't worry too much about the name, if the game is good enough to publish, it will be renamed to its original name. <br />
<br />
Find and start the game in turn based mode, make sure it works.<br />
<br />
Second, modify the text in .tpl file, reload the page in the browser and make sure your ftp sync works as expected.<br />
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.<br />
<br />
Update your project status on [http://studio.boardgamearena.com/#!studio Control Panel > Manage games] page, you can say "development started" or "waiting for the license" or "waiting for graphics" or a combination of those.<br />
<br />
<br />
<br />
== Development Tools ==<br />
<br />
At some point, you need to setup your development environment which consists of multiple tools, such as<br />
* Editor or IDE<br />
* Browser with dev tools<br />
* File sync tools<br />
* BGA Web tools<br />
* Image manipulation tools<br />
* Version control tools<br />
<br />
Please scan through articles from [[Studio#BGA_Studio_user_guide]] especially those related to debugging and tools, there is a lot of useful info there.<br />
<br />
== Hook version control system ==<br />
<br />
If it's a real game, I would commit the code to version control right at the start. You are going to find yourself in a situation where 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.<br />
If you don't know what I am talking about then at least back-up your files after each of the major steps. Starting now.<br />
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).<br />
You can (and should) also commit your modification periodically via Studio Control Panel.<br />
<br />
== Obtain game graphics ==<br />
<br />
If you developing a game from the Available Licenses section, ask the admins to send you graphics by using the '''Request Art Files''' button available on the studio license page. 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 the next step - project creation.<br />
<br />
If you don't get original graphics you go to '''Scavenger Hunt'''<br />
<br />
* If you developing a public domain card game you can borrow standard cards from BGA generic assets, see [[Common_board_game_elements_image_resources]]<br />
* Standard game pieces - meeples, cubes, dice can be found here as well [[Common_board_game_elements_image_resources]]<br />
* Go to boardgamegeek.com find your game and obtain 3D game box image, 2D box image, and if you are lucky they also sometimes have boards and token scans in "Game Pieces" section of Images<br />
* If that fails, google "boardgame <name>" and check the Images section<br />
* Get the rules PDF as well, there're tools that allow you to extract graphics from PDF, which are usually good for meeples, cubes and such (can use pdfimages command line tool)<br />
<br />
Once you get the graphics one way or another you have to massage them to fit in the BGA criteria, which usually involves<br />
* If the publisher sends graphics in one token/card per file mode, you have to stitch them in sprite and scale down<br />
* For non square tiles and game pieces you need transparency<br />
* Usually you chop off the scoring "ring" around the board of the game since the scoring track is not needed for online adaptation<br />
<br />
More details about graphics requirements can be found here [[Game art: img directory]].<br />
<br />
[[File:Rrr_search.png]]<br />
<br />
== Obtain game documentation ==<br />
<br />
Also at this time obtain an electronic copy of rules, such as PDF (English version). <br />
<br />
Also grab any other documents you may find on boardgamegeek such as FAQ, additional Reference books, and user created assistant documents, such<br />
as cheat-sheets (may be easier to get data from these than trying to scrub pdf). You create and place them in the doc/ folder of the project then<br />
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.<br />
<br />
<br />
== Update game info and box graphics ==<br />
<br />
Even if is not playable yet, start with making sure the game looks descent in the game selector, meaning it has nice box graphics and the information is correct. <br />
<br />
For that we need to edit [[Game_meta-information: gameinfos.inc.php|gameinfos.inc.php]].<br />
What you would do for the real game you would go to http://boardgamegeek.com find the game and use information from the website to fill the gameinfos.<br />
<br />
<br />
The next step is to replace game_box.png with proper images, usually, you can find all images including the publisher logo on the boardgamegeek website.<br />
<br />
Game metadata images, such box image are now managed in separate tool.<br />
<br />
Details about images can be found here: [[Game art: img directory]].<br />
<br />
<br />
<br />
[[File:Gamepanel_sharedcode.png]]<br />
<br />
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).<br />
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.<br />
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!<br />
<br />
== Fix source copyright ==<br />
<br />
Now since you have your own project, you want to put your name in the copyright header, so replace<br />
<br />
© <Your name here> <Your email address here><br />
with<br />
© John Snow <jsnow@gameofthrones.com><br />
<br />
Well not exactly this but whatever your real name is. For all files in the project directory, it's about 10 files. Make sure the project still starts after that :)<br />
<br />
== Reduce the Rules ==<br />
<br />
Programming a game will take a lot more time than you may think. Most of the projects in the studio are abandoned because of a lack of patience or skill.<br />
To keep sane, start the game with *reduced* rules and try to complete that first.<br />
<br />
* 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<br />
* If it has advanced rules - start with basic rules only, i.e. "beginner game"<br />
* If it has special rules for 2 players vs 4, start with the most basic form (i.e. 4), restrict to 4 players <br />
* If it has 50 unique cards of 2 each - start with 2 unique cards with 25 each (just to keep it moving)<br />
* Any sort of rules that you think can be removed and not included in base - set aside for now <br />
* Ignore any sort of cool animations - dice rolling, card flipping, choo-choo sounds of the trains - all this fluff can be added later<br />
<br />
<br />
== Design Game Elements ==<br />
Technically game elements are already designed by a board game designer but your job is to map them to program space.<br />
Each physical piece (card, token, cube) will leave footprints all over the code (unfortunately in multiple disconnected places).<br />
To prepare the game you need to sort out these elements, i.e. categorize. I usually have the following categorization (in object oriented view):<br />
* Instance - all individual pieces are instances, i.e. two red cubes are two instances of 'red cube' type (class)<br />
* Type - element type which distinctly represents that element in appearance (i.e. red cube is a different type than blue cube)<br />
* Super Type - one of the more common types that similar properties (i.e. red OR cube)<br />
* Player color - supertype specific for player color (sometimes there are no colors but like player 1 - but is conceptually the same, I use color because it's easier to track)<br />
<br />
Personally, I like to encode my elements in a string using reverse DNS notation listing all the properties above, i.e.<br />
meeple_ff0000_7 - this is instance #7 of type meeple_ff0000 (red meeple)<br />
Or<br />
card_yellow_magic_2 - this is instance #2 of a yellow card (in this case yellow is the color of the deck, not related to player color) that can do magic<br />
<br />
So every game element would be in the<br />
<br />
1. Database - instances. The db record would be something like <br />
key|location|state<br />
meeple_ff0000_7|slot_action_2|1<br />
meeple_ff0000_2|tableau_ff0000|0<br />
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<br />
'meeple'=>{'name'=>totranslate('Meeple')}<br />
3. Client (js, css, tpl, etc) - instances and types. For example my meeple will be like <br />
<pre><br />
<div id="meeple_ff0000_7" class="meeple meeple_ff0000"></div><br />
</pre><br />
with .css something like<br />
.meeple { background-image: url(img/tokens.png); width: 2em; height: 2em;}<br />
.meeple_ff0000 {background-position: 20% 0%;}<br />
4. Game php - setup and logic. During setup, you have to generate all the pieces and place them in the right positions. Also sometimes you need to reference elements to code the logic (I usually try to encode all rules in the material file as much as possible)<br />
<br />
For complex card games, I think it is best to keep all these info and rules in a spreadsheet and generate other files such as material.inc.php.<br />
See more info below about the design of the individual layers.<br />
<br />
== Create Initial Layout and Game Graphics ==<br />
<br />
Mentally it is easier to start with the game layout and graphics pieces. Even when nothing is working it gives you moral satisfaction!<br />
<br />
There are a few ways how the html could have been generated. You could have started with nothing and generate<br />
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 be 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]].<br />
<br />
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, <br />
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]]<br />
<br />
During this step you have to decide what technical solutions you will be using, such as<br />
* 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).<br />
* Use BGA template engine OR create all ui elements by JS OR manually write or generate complete html markup. The game usually contains 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.<br />
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.<br />
<br />
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 piece of boardgame would have its "print" in multiple files in your game:<br />
* Some sort of "div" in html, where id of element match id of element in database (easiest way)<br />
* Css for the element (either unique or for class), usually with background property refering to part of sprite image<br />
* Entry in material.inc.php referring to static properties of the element, i.e. name, tooltip, rules, etc<br />
* Entry in .tpl file to represent a static or initial location on the table OR creation template<br />
<br />
Here are some specific examples:<br />
<br />
'''Game Board'''<br />
<br />
Create entry in .tpl file for the board, it will be static entry as we never need to create this dynamically<br />
<pre><br />
<div id="board" class="board shadow board4p"> ... </div><br />
</pre><br />
Create entry in .css file for this board and other board variants (in example below we have 4 ppl board which is diffrent than 2 ppl board)<br />
<pre><br />
.board {<br />
position: relative;<br />
width: 980px;<br />
height: 433px;<br />
margin-bottom: 5px;<br />
}<br />
<br />
.board4p {<br />
background-image: url(img/board4p.jpg);<br />
}<br />
</pre><br />
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<br />
<br />
<br />
'''Game Board Slots'''<br />
<br />
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:<br />
<br />
Entry in material.inc.php<br />
<pre><br />
$this->token_types = array(<br />
...<br />
'slot_action_2' => array(<br />
'type' => 'slot_action',<br />
'name' => clienttranslate("2 Gray Track Advancements"),<br />
'tooltip' => clienttranslate("This action gives you two advancements of gray track. You cannot use this action if you cannot complete all advancements."),<br />
'o'=>"1,0,0,gg", // automatic rules<br />
),<br />
...<br />
</pre><br />
<br />
Entry in template inside the "board" div<br />
<pre><br />
<div id="slot_action_2" class="slot_action_2 slot_action slot_w_1 slot"></div><br />
</pre><br />
<br />
Entry in .css with absolute position within the board (its actually better to use percentage - would be easier to scale later)<br />
<pre><br />
.slot_action_2 {<br />
top: 83px;<br />
left: 37px;<br />
}<br />
.slot_action {<br />
position: absolute;<br />
width: 46px;<br />
height: 26px;<br />
padding: 9px 7px 6px 4px;<br />
}<br />
</pre><br />
<br />
'''Meeples''' - also cards, tokens, other mobile stuff<br />
<br />
In CSS these guys will use "sprite" images with transparency, so it will look like this this:<br />
<pre><br />
.meeple {<br />
background-image: url(img/tokens.png);<br />
width: 25px;<br />
height: 25px;<br />
}<br />
.meeple_ff0000 { /* red */<br />
background-position: 14% 0%;<br />
}<br />
</pre><br />
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<br />
<pre><br />
<div id="meeple_{COLOR}_1" class="meeple meeple_{COLOR} meepleable"></div><br />
<div id="meeple_{COLOR}_2" class="meeple meeple_{COLOR} meepleable"></div><br />
...<br />
</pre><br />
<br />
Or you can declare a template js var in .tpl file <br />
<pre><br />
var jstpl_mepple = '<div id="meeple_${color}_${num}" class="meeple meeple_${color} meepleable"></div>'; // this is in .tpl file at the bottom<br />
</pre><br />
and create in js, like this<br />
<pre><br />
var tokenDiv = this.format_block('jstpl_mepple', {<br />
"color" : color,<br />
"num" : i<br />
}); // this in js code somewhere before placing it<br />
</pre><br />
If you dealing with cards and decks, there are pre-build components that can generate stuff for you.<br />
<br />
When do you create dom element matching game element?<br />
* 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)<br />
* 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.<br />
<br />
<br />
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!<br />
<br />
So at the end of this stage you should complete the following (keeping in mind reduced rules/material for first iteration):<br />
* Create a layout of the game, with positioning of main board, player areas, zones, other supporting areas, etc<br />
* 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<br />
* Hook layout to number of players and colors picked by the game and test with multiple players<br />
* Figure out what you want to display in mini-player boards and hook it up<br />
* Create material.inc.php and populate with initial values (names, tooltips, rules) for all relevant game elements or classes of elements<br />
<br />
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.<br />
<br />
<br />
[[File:Injected_text.png]]<br />
<br />
<br />
== Create Database Schema ==<br />
<br />
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<br />
code decisions would be based on that.<br />
<br />
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]].<br />
<br />
In general make it as simple as possible. <br />
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.<br />
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.<br />
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!<br />
<br />
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<br />
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<br />
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).<br />
<br />
Usually design process will contain the following steps:<br />
* Design game model - model that represent your game in progress, such as at any given step you can restore the game from that model<br />
* Mapping - now map real game to that model<br />
* Encoding - now represent this model in database and material file with reasonable amount of fields<br />
<br />
Example: '''The card game'''<br />
<br />
* 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<br />
* 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)<br />
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either<br />
* 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.<br />
* The card state is very simple, it's usually "face up/face down", "tapped/untapped", "right side up/up side down"<br />
* 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.<br />
* 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<br />
* Now for mapping we should consider what info changes and what info is static, static info is always candidate for material file or html<br />
* 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<br />
* 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<br />
<br />
You can also use cards database schema and [[Deck]] implementation for most purposes (even you not dealing with cards).<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `card` (<br />
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`card_type` varchar(16) NOT NULL,<br />
`card_type_arg` int(11) NOT NULL,<br />
`card_location` varchar(16) NOT NULL,<br />
`card_location_arg` int(11) NOT NULL,<br />
PRIMARY KEY (`card_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
Another Example: '''The euro game'''<br />
<br />
See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]<br />
<br />
<br />
So the piece mapping for non-grid based <br />
games can be in most case represented by (string: token_key, string: location, int: state), example of such database schema can be found here:<br />
[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].<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `token` (<br />
`token_key` varchar(32) NOT NULL,<br />
`token_location` varchar(32) NOT NULL,<br />
`token_state` int(10),<br />
PRIMARY KEY (`token_key`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
</pre><br />
<br />
<br />
See [[Game database model: dbmodel.sql]] for details about editing the file.<br />
<br />
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.<br />
Here are some example of how real games are mapped to such database:<br />
<br />
'''Chess''' <br />
<br />
- 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<br />
{| class="wikitable"<br />
|+token<br />
! token_key<br />
! token_location<br />
! token_state<br />
|-<br />
|Q_white<br />
|f3<br />
|0<br />
|-<br />
|P_black_2<br />
|c6<br />
|0<br />
|-<br />
|K_black<br />
|e8<br />
|1<br />
|}<br />
And the state in this case indicated that kind was moved for example (which means castling cannot be performed)<br />
<br />
<br />
'''Classic card game''' <br />
<br />
Lets pretend we need 2 decks for that game<br />
{| class="wikitable"<br />
|+token<br />
! token_key<br />
! token_location<br />
! token_state<br />
|-<br />
|Q_spades_1<br />
|hand_ff0000<br />
|0 /* state not used for hand */<br />
|-<br />
|10_hearts_2<br />
|tableau_ff0000<br />
|2 /* position */<br />
|-<br />
|10_hearts_1<br />
|tableau_common<br />
|1 /* face down */<br />
|}<br />
<br />
'''Eminent Domain (card game)''' <br />
<br />
{| class="wikitable"<br />
|+token<br />
! token_key<br />
! token_location<br />
! token_state<br />
|-<br />
|card_tech_23<br />
|hand_ff0000<br />
|0 /* state not used for hand */<br />
|-<br />
|card_planet_19<br />
|tableau_ff0000<br />
|1 /* face up */<br />
|-<br />
|reource_s_22 /* silicon */<br />
|card_planet_19<br />
|2 /* production state */<br />
|-<br />
|fighter_F_1<br />
|tableau_ff0000<br />
|0<br />
|}<br />
<br />
<br />
You can also look at other games that use Tokens database and access layer: Nippon, Dungeon Petz, Lewis & Clark, Battleship, Russian Railroads, Khronos<br />
<br />
== Implement Game Setup ==<br />
<br />
Once you have your database schema you can do a proper game setup. Usually you open rulebook on the "Game Setup" page<br />
and implement these step by step populating the database (using db access API).<br />
Game initialization is performed in php method setupNewGame, this method is called once when game table is created.<br />
Game notifications cannot be sent during this time.<br />
<br />
It very hard to debug this method, so this is how we recommend to structure it:<br />
<br />
<pre><br />
protected function setupNewGame($players, $options = []) { <br />
<br />
// here is some generate code from template LEAVE IT UNTOUCHED<br />
...<br />
<br />
$this->initTables(); // this is YOUR new method<br />
}<br />
<br />
function initTables() {<br />
try {<br />
$players = $this->loadPlayersBasicInfos();<br />
// code the function<br />
$this->activeNextPlayer(); // just in case so its not 0<br />
$this->initStats(); // to be coded<br />
// Setup the initial game situation here<br />
$this->initGameTables(); // to be coded<br />
// beggining of the turn for active player (if player state if first state)<br />
$player_id = $this->getActivePlayerId();<br />
$this->incStat(1, 'turns_number', $player_id);<br />
$this->incStat(1, 'turns_number');<br />
} catch ( Exception $e ) {<br />
// logging does not actually work in game init :(<br />
// but if you calling from php chat it will work<br />
$this->error("Fatal error while creating game");<br />
$this->dump('err', $e);<br />
}<br />
}<br />
</pre><br />
<br />
For more tricks debugging this See [https://en.doc.boardgamearena.com/Practical_debugging#Debugging_setupNewGame Debugging setupNewGame]<br />
<br />
For the init stats, its likely that all of the are int and you can just use this genetic initializer, but your stats have to start with game_ prefix (verbatim):<br />
<pre><br />
public function initStats()<br />
{<br />
// INIT GAME STATISTIC<br />
$all_stats = $this->getStatTypes();<br />
$player_stats = $all_stats['player'];<br />
// auto-initialize all stats that starts with game_<br />
// we need a prefix because there is some other system stuff<br />
foreach ($player_stats as $key => $value) {<br />
if (startsWith($key, 'game_')) {<br />
$this->initStat('player', $key, 0);<br />
}<br />
if ($key === 'turns_number') {<br />
$this->initStat('player', $key, 0);<br />
}<br />
}<br />
$table_stats = $all_stats['table'];<br />
foreach ($table_stats as $key => $value) {<br />
if (startsWith($key, 'game_')) {<br />
$this->initStat('table', $key, 0);<br />
}<br />
if ($key === 'turns_number') {<br />
$this->initStat('table', $key, 0);<br />
}<br />
}<br />
}<br />
</pre><br />
<br />
As for init game tables - if you have SQL layer you can use it to initialize everything, if not - the best would be to push everything in php array and then do one inset at the end (after all the fiddling and shuffling).<br />
<br />
For example for the token database above, I will push all data into array, then at the end run insert, i.e.<br />
<br />
$values=[]; <br />
$values [] = "('meeple_ff0000_1', 'home_ff0000', 0)"; // this is actually string not array<br />
...<br />
$sql = "INSERT INTO tokens (token_id, place_id, state) VALUES " . implode($values, ',');<br />
$this->DbQuery($sql);<br />
<br />
== Implement One time game model synchronisation ==<br />
<br />
<br />
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<br />
to return all possible data we need to reconstruct the game. The template for getAllDatas already taking care of player info, but you <br />
have to alter it to return all other data from database visible to the "current" player.<br />
<br />
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".<br />
<br />
So this is roughtly what you need to include in getAllDatas():<br />
<br />
* Extra player info <br />
* Material file variables, unfortunately they are not included automatically. Note - I strongly recommend using only one variable for generic data information, such as $this->token_types. If you start splitting it i.e. card_types, meeple_types, building_types - it very hard to deal with this programmatically it will be lots of switches. Also call it the same as in php - otherwise its really hard to correlate.<br />
* Game options (if you know how to access them on cient without passing via getAllData() edit this wiki). Example has generic code to pass all options, but you can use custom individual options<br />
* Dump of database tables filtered by current player view<br />
* To be fancy you can also include php constans so you can access them in js as well, example not included<br />
<br />
<pre><br />
protected function getAllDatas() {<br />
$result = [];<br />
<br />
// 1. Get information about players<br />
// Note: you can retrieve some extra field you added for "player" table in "dbmodel.sql" if you need it.<br />
// would have been much better if its just * but we not looking for easy solutions here! so it all have to be aliases<br />
$sql = "SELECT player_id id, player_score score, player_no no FROM player"; // note - the framework will all bunch of more fields<br />
$result ['players'] = self::getCollectionFromDb($sql);<br />
<br />
// 2. Material data<br />
$result['token_types'] = $this->token_types;<br />
// 3. Game options<br />
$table_options = $this->getTableOptions();<br />
$result ['table_options'] = [];<br />
foreach ( $table_options as $option_id => $option ) {<br />
$value = 0;<br />
if (array_key_exists($option_id, $this->gamestate->table_globals)) {<br />
$value = (int) $this->gamestate->table_globals [$option_id];<br />
}<br />
$result ['table_options'] [$option_id] = $option;<br />
$result ['table_options'] [$option_id] ['value'] = $value;<br />
}<br />
// 4. Rest of the database filtered by current player<br />
$current_player_id = self::getCurrentPlayerId(); // !! We must only return informations visible by this player !!<br />
$result ['tokens'] = [];<br />
$players_basic = $this->loadPlayersBasicInfos();<br />
foreach ( $players_basic as $player_id => $player_info ) {<br />
$color = $player_info ['player_color'];<br />
// tableau is public info<br />
$result ['tokens']+=$this->tokens->getTokensInLocation("tableau_$color"); // this is sql access layer for tokens table but it can be just raw SQL query with getCollectionFromDb kind of call<br />
// hand if private info<br />
if ($current_player_id==$player_id) {<br />
$result ['tokens']+=$this->tokens->getTokensInLocation("hand_$color");<br />
} else {<br />
$result ['counters']["hand_$color"]=$this->tokens->countTokensInLocation("hand_$color");<br />
}<br />
}<br />
$result ['counters']["deck]=$this->tokens->countTokensInLocation("deck");<br />
$result ['counters']["discard"]=$this->tokens->countTokensInLocation("discard");<br />
<br />
return $result;<br />
}<br />
</pre><br />
<br />
== Create State Machine ==<br />
<br />
Now you need to create a game state machine. <br />
<br />
The state handling spread across 4 files, so you have to make sure all the pieces are connected together.<br />
The state machine states.inc.php defines all the states, and function handlers on php side in a form of string,<br />
and if any of these functions are not implemented it would be very hard to debug because it will break in random places.<br />
<br />
Please first watch this again [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine BGA game state machine]<br />
and then please read [[Your game state machine: states.inc.php]].<br />
<br />
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.<br />
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<br />
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)<br />
to collect this info.<br />
<br />
It is important to implement proper state handling on the client, usually it results in big switch in onUpdateActionButtons method.<br />
<pre><br />
onUpdateActionButtons: function(stateName, args) {<br />
console.log('onUpdateActionButtons: ' + stateName + " " + this.isCurrentPlayerActive() + " args:", args);<br />
if (!this.isCurrentPlayerActive()) return;<br />
<br />
switch (stateName) {<br />
case 'playerTurn':<br />
dojo.query('.card').addClass('active_slot'); // activate board elements, when using static connector, see user input below<br />
// add buttons<br />
this.addActionButton('button_pass', _('Pass'), () => {<br />
this.ajaxcallwrapper('pass');<br />
});<br />
// case...<br />
}<br />
<br />
if (this.on_client_state && !$('button_cancel')) {<br />
this.addActionButton('button_cancel', _('Cancel'), 'cancelLocalStateEffects', 0, 0, 'gray');<br />
this.addTooltip('button_cancel', _("This means cancel current action and start thinking"), '');<br />
}<br />
},<br />
<br />
</pre><br />
<br />
I keep onLeavingState pretty generic (and onEnteringState just for logging)<br />
<pre><br />
onLeavingState: function (stateName) {<br />
console.log('Leaving state: ' + stateName);<br />
dojo.query('.active_slot').removeClass('active_slot');<br />
dojo.query('.selected').removeClass('selected');<br />
}, <br />
<br />
</pre><br />
<br />
<br />
== Handle Turn Order ==<br />
<br />
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<br />
it may require some trickery.<br />
<br />
Usually turn order is done by "game state" (see state machine above). Basically it would be two choices:<br />
* Turn order depends on game situation (such as we take player with highest number of red cubes)<br />
* 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)<br />
<br />
Handling turn order would go to the game state which is usually follows active player state.<br />
<br />
== Hook User Input ==<br />
<br />
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.<br />
<br />
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.<br />
<br />
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), that part is done in onUpdateActionsButtons (see above)<br />
<br />
So classic is static handlers, means handler is added in setup method using framework connect function:<br />
<br />
this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );<br />
<br />
This is what is advertized in tutorials, however this is best suited for static html model - where elements are not deleted and recreated. When elements created dinamically if you using this method please be aware of memory leaks - this<br />
method stores the pointer to dom element in arrays of handlers (to be able to disconnect later), but if element is deleted you must call this.disconnect before deleting with same node reference, or it will leak.<br />
<br />
If you using this method your handlers usually look like big ugly switch because it usually depending on state it will do right thing or deny action, typically it will look this this:<br />
<br />
<br />
onCard: function(event) {<br />
dojo.stopEvent(event);<br />
var id = event.currentTarget.id;<br />
console.trace("on slot " + id);<br />
if (!id) return null;<br />
// check player is active<br />
if (!this.isCurrentPlayerActive()) {<br />
this.showMessage(__("lang_mainsite", "This is not your turn"), "error");<br />
return false;<br />
}<br />
// check node is marked with "active_slot" class (class name is whatever you want)<br />
if (!dojo.hasClass(id, 'active_slot')) {<br />
this.showMoveUnauthorized();<br />
return false;<br />
}<br />
switch (this.gamedatas.gamestate.name) {<br />
case 'playerTurn': // in this case we directly sending data to the server<br />
this.ajaxcallwrapper('playCard',id); // note that this wrapper also calls 'checkAction' on action parameter<br />
return true;<br />
case 'playerDiscard': // in this case we need to collect more information, so we using cient state for that<br />
dojo.addClass(id,'selected'); // mark card<br />
this.setClientState("client_playerTurnSelectBonus", {<br />
descriptionmyturn: _('${you} must select bonus for discard'),<br />
});<br />
return true;<br />
default:<br />
this.showMoveUnauthorized();<br />
return false;<br />
}<br />
},<br />
<br />
You can also manage listeners yourself (vanilla event listeners or dojo). In this case be aware of registering double listener. See more example in [[Game_interface_logic:_yourgamename.js#Players_input|Player's Input]].<br />
<br />
Alternative to static handler are dynamic handlers which are only installed on elements that are active for specific game state, given the example above we would register the listeners in playerTurn state, i.e.<br />
in onUpdateActionButtons for playerTurn:<br />
<pre><br />
dojo.query('.card').forEach((node) => {<br />
dojo.addClass(node, 'active_slot');<br />
dojo.addClass(node, 'temp_click_handler');<br />
this.connect(node, 'click', event=>this.ajaxcallwrapper('playCard',event.currentTarget.id));<br />
});<br />
</pre><br />
Above we did not need to do the heavy validation because we only presumably added handler in right state to right node and right active player (and removed correctly in between!)<br />
<br />
And in onLeavingState we will disconnect all of them (important!):<br />
<pre><br />
dojo.query('.temp_click_handler').forEach((node) => {<br />
dojo.removeClass(node, 'active_slot');<br />
dojo.removeClass(node, 'temp_click_handler');<br />
this.disconnect(node, 'click');<br />
});<br />
</pre><br />
<br />
When user clicks on something, client sends an ajax call to server, server processes it and updates database, server sends<br />
notification in response, client hooks animations to server notification. See [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].<br />
<br />
Exception to this is client states, if you need to process two step user interaction such as select meeple, place meeple, you may want <br />
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]]<br />
<br />
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]].<br />
<br />
In BGA there is only two ways interact with the server (officially)<br />
* Initial data dump - when JS client starts it gets all current data via setup() method<br />
* Game actions - ajaxcall from client, it returns error or ok (not data), then server send butch of notifications to client<br />
<br />
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.<br />
<pre><br />
ajaxcallwrapper: function(action, args, handler) {<br />
if (!args) args = []; // this allows to skip args parameter for action which do not require them<br />
<br />
args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server<br />
<br />
if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared<br />
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff <br />
this, (result) => { }, // success result handler is empty - it is never needed<br />
handler); // this is real result handler - it called both on success and error, its is optional param - you rarely need it<br />
}<br />
},<br />
</pre><br />
<br />
<br />
<br />
When you insert a single action you have to update multiples files:<br />
* in ggg.js add ajaxcall, i.e. something like <br />
this.addActionButton('pass',_('Pass'),()=>this.ajaxcallwrapper('pass'));<br />
* in states.php - add action 'pass' to list of possible actions<br />
'possibleactions' => ['pass','playCard']<br />
* in action.php - add action hander, see https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php<br />
* in game.php - add action hander, there you must do the following<br />
** call checkAction to validate the action<br />
** 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)<br />
** do some database maniplations, using access api<br />
** send notifications - this is the "reply" for action<br />
** transition to new state (it very rare that user will remain in the same state, except for multi-active states)<br />
* back to ggg.js add notification subsciption and notification handler (two separate things)<br />
<br />
== Implement Notification handling and Animation ==<br />
<br />
To handle notification you have to subscribe to it and implement the handlers, see [[Game_interface_logic:_yourgamename.js#Notifications|JS Notifications]].<br />
<br />
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. <br />
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 <br />
<br />
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).<br />
<br />
See [[Game_interface_logic:_yourgamename.js#Access_and_manipulate_the_DOM|Animation and DOM Manipulation]] for JS reference.<br />
<br />
<br />
== Wrap Up ==<br />
<br />
* Implement game progression (getGameProgression() in php)<br />
* Implement Zombie turn (zombieTurn() in php)<br />
* Define and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)<br />
* The games logs should explain what happened if player was not looking<br />
* You need to implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data<br />
* Make sure all UI strings are marked for translation<br />
* UI elements which are images (i.e. tokens, cards) should have tooltips<br />
<br />
== Alpha ==<br />
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]].<br />
<br />
If you think its completely ready, create a build and click on the "Request ALPHA status" button and admins will check your game and push it to alpha.<br />
<br />
Finally, visit the game page for your alpha game (https://boardgamearena.com/gamepanel?game=…) to add the following information if you can:<br />
* Links to the rules (in multiple languages if available).<br />
* Links to teaching videos.<br />
* In the "On the web" section, links to:<br />
** The official website for the game (if there is one).<br />
** The BoardGameGeek page for the game.<br />
* Consider writing a summary of the rules.<br />
<br />
Note: later can be done by community members, you don't actually have to do it yourself<br />
<br />
== Level Up ==<br />
<br />
When you successfully created a basic game and you want more, it's time to make it fancy!<br />
<br />
* Add game externtions and variants using gameoptions file<br />
* Add user preferences for customizations<br />
* Use theming! That involves replacing hardwood background, changing tooltips, using different sounds, different fonts, changing state prompt and logs<br />
* You can use fancy scoring board at the end of game instead of default nothing<br />
* And finally super cool dice rolling, card flipping and victory points evaporating effects<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=BGA_Game_licenses&diff=14771
BGA Game licenses
2022-09-19T11:29:37Z
<p>Een: Support page</p>
<hr />
<div><br />
== What is a "license" exactly? ==<br />
<br />
Almost all games on the Board Game Arena platform are adaptations of existing commercial "real" board games. In order to host an adaptation of one of these board games on a website, the copyright owners must first grant a license/authorisation to this website.<br />
<br />
== Are all games on BGA licensed by their respective copyright owners? ==<br />
<br />
Yes, for all games that are not in the public domain, BGA has been granted an authorisation to create and host an online version.<br />
<br />
== Where can I find a list of games for which a license has already been granted? ==<br />
<br />
[https://studio.boardgamearena.com/#!licensing Check the list of available licenses]<br />
<br />
(NB: this page is restricted to developers registered in BGA studio. You'll need to enter your BGA studio credentials to access it)<br />
<br />
== What if I start developing a game that is not on the "Available licences" list? ==<br />
<br />
We allow developers to start any project in the Studio. But when you submit your project to go live on BGA, it will be rejected during the review process if BGA doesn't hold a proper license for the game.<br />
<br />
Exception: games in the public domain are of course not concerned.<br />
<br />
== Wow, I WANT to develop a game on this list! ==<br />
<br />
Great! :)<br />
<br />
But before creating a new project, please takes some seconds to check that someone is not already developing this game. If it is the case, maybe you can propose to join the project?<br />
<br />
[http://studio.boardgamearena.com/projects Check the list of current projects]<br />
<br />
Also, first thing to do when starting a project of that list is to request the game image files. Sometimes we already have them, sometimes we'll have to ask the publisher. Since it can be a while between the time the publisher grants the license and when a developer starts a project, this contact also allows to check that everything is still ok on the licensing side.<br />
<br />
Try establishing a contact with the publisher or designer before developing a new game. To release the implementation as a public game, the publisher must approve the game during alpha test phase. Without publisher support your game will remain private indefinitely.<br />
<br />
== What needs to be done to add a game on this list? ==<br />
<br />
The copyright owners have to give an license/authorisation to BGA.<br />
<br />
Publishers do not have to pay anything to BGA for this, they just need to give their "go". Most of the time, publishers want to have a formal agreement and we sign a contract with them.<br />
<br />
== Why aren't all the best-selling games that I love on that list? ==<br />
<br />
As you can imagine, the more popular a game is, the most difficult it can be to get an agreement to host this game on BGA.<br />
<br />
So if you are thinking about a very popular game that is not on this list, the reason is most likely "we asked but it was not possible" and not "we didn't think of it".<br />
<br />
We are really happy to have been able to build a very nice platform that managed to convince some of the most prestigious publishers to host their games here, but of course we can't convince -everyone-.<br />
<br />
== I want to make my prototype/unpublished game available on BGA ==<br />
<br />
This is possible, BUT most of the time, we consider this is a bad idea for the following reasons:<br />
* if your game has not been published yet, there is certainly a good reason - most of the time there is still some more work to do on the game itself. Publishing a game on BGA that is not 100% finalized won't help you to finalize it.<br />
* as a rule of thumb, popular board games on BGA are games that are popular in the real world. As a consequence prototypes most likely won't get a big audience on BGA.<br />
* we also advise you against developing your own game: games adaptation are better when there is a designer whose focus is on the gameplay and a developer whose focus is on the implementation.<br />
<br />
So you definitely can develop your prototype/unpublished game on BGA, but we encourage you to think twice about it and do it only if you are in one/several of the situations below:<br />
* the game is going to be published in the near future<br />
* the game design process is really 100% done: the game is ready to be published in its current shape (ex: self-publishing game, game in a crowdfunding process...)<br />
* you want to test your game with a big number of players to fine-tune some minor things ("balance" of the game).<br />
<br />
== What if I really want to develop a particular game that is NOT on the list of "Available licences"? ==<br />
<br />
This is the most frequently asked question, so for a detailed answer please follow the white rabbit down these numbered instructions:<br />
<br />
=== 1: Determine the Publisher ===<br />
<br />
First, you should determine who is the owner of the digital rights of the game. Most of the time, this is the original publisher of the game. The original publisher is not always easy to find, because very often board games are translated and published in different countries by a local publisher.<br />
<br />
To find the original publisher:<br />
* check in which country the game has been published first (ex: If it's in Poland, the original publisher is probably Polish).<br />
* check the copyright notice at the end of the rules, where the original publisher is mentioned almost every time.<br />
* very often, if two publishers are mentioned on a gamebox, the well-known publisher is the local publisher from your country and the other one is the original publisher.<br />
<br />
Special case: if the game is themed with a prestigious licence (Star Wars, Lord of the Rings, some TV show, some well known novel...), you can stop here immediately: contracts between game publishers and prestigious licenses owners are very restrictive, and there is 99% chance that an online adaptation on BGA would be impossible to manage.<br />
<br />
Continue to 2.<br />
<br />
=== 2: Check Publisher Relation with BGA ===<br />
<br />
Read the list of publishers from the [https://studio.boardgamearena.com/#!licensing Available licenses] page to check if BGA is already working with this publisher.<br />
<br />
If YES, proceed to 3.<br />
If NO, jump to 4.<br />
<br />
However, if the publisher is listed as "not working with BGA", you can stop here immediately. It happens that some publishers are not convinced or interested by online boardgaming and it is their right to think so. The BGA team regularly meets new publishers during board games events to show them the platform, so we're working on this but -again- we cannot convince everyone.<br />
<br />
=== 3: Check Publisher's Other Available Licenses ===<br />
<br />
Is there already in the list a game licensed by this publisher that is available to be developed or under development?<br />
<br />
If YES: as a rule of thumb, we do not ask more than one game to a publisher at a time. When we ask a license for a game, the publisher naturally expects that this game will be developed and published online. So we develop and publish a game before asking for another.<br />
If you really want to develop another game from this particular publisher, the best option for you is to help develop the game that is currently licensed and then ask us to request the game you'd like to develop.<br />
<br />
If NO: you can click on "template email" at the top of the licensing page to display a form that will help you generate an email to send to the publisher to request a new license.<br />
<br />
And if you are unsure, please check with us by filing a support request from the [https://studio.boardgamearena.com/support studio support page] (it's always a good idea to ask if you are not sure ;) )<br />
<br />
=== 4: Publisher is not in the list ===<br />
<br />
We have never worked with this publisher before.<br />
<br />
If you have already developed a game on BGA, you can click on "template email" at the top of the [https://studio.boardgamearena.com/#!licensing Available licenses page] to display a form that will help you generate an email to send to the publisher to request a new license.<br />
<br />
If this is your first game on BGA, we advise you to start with a game already on the list. Why? Because unfortunately, sometimes developers request a license, and then don't finish the development. When asking for a license, it's better if you have already shown your ability to realise an adaptation.<br />
<br />
Special case: if you know the publisher PERSONALLY, or have some contact there, please suggest them to check our page for game publishers https://boardgamearena.com/#!gamepublishers where they'll get information and find an email template to send to us if they are interested in granting BGA a license.<br />
<br />
Special case #2: if you are the publisher, represent the publisher, or the license owner (i.e. author of unpublished game) please check out https://boardgamearena.com/#!gamepublishers and if you are interested contact us by email! (you can use the email template available on this page).<br />
<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Pre-release_checklist&diff=14770
Pre-release checklist
2022-09-19T11:28:38Z
<p>Een: Move to Alpha / Beta buttons</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
If you think your game is ready to be reviewed by by BGA admins and/or Publisher (aka go to Alpha stage) please consult this checklist first<br />
<br />
=== Move from Dev to Alpha ===<br />
# ''' License '''<br />
## BGA must have a license for the game for a project to be moved to production, even to alpha. If you don't have license yet you can continue checking other stuff from the list below, but at the end it cannot be moved until license situation is cleared.<br />
# ''' Metadata and graphics '''<br />
## [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game. That includes game tags. <b>Important!!!</b> tags are only read during the first deploy.<br />
## Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.<br />
## You have added a game_banner.jpg and some game_displayX.jpg images to make the game page pretty (NB: on the studio, you have to create a build for these images to appear on the studio game page)<br />
## There are no images in the img directory that are not needed anymore<br />
## Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])<br />
## Each image should not exceed 4Mb<br />
## Total size should not exceed 10Mb, image compression should be used otherwise (it also helps a lot to re-encode images as indexed palette vs RBG). If you have legitimate reason to have more than 10Mb (i.e. expansions), you have to make a note of that when requesting move to alpha<br />
## If you use extra fonts, they should be freeware (please include a .txt with the licence information)<br />
# ''' Server side '''<br />
## When giving their turn to a player, you give them some extra time with the giveExtraTime() function<br />
## Game progression is implemented (getGameProgression() in php)<br />
## Zombie turn is implemented (zombieTurn() in php). Note: it can only be tested if you explicitly click on the quit button to create a zombie. If you are expelled it does not generated a Zombie.<br />
## You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)<br />
## Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)<br />
## You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data<br />
## Database: make sure you do not programmatically manage transactions or call queries that change database schema or even TRUNCATE (queries that would cause implicit commit) during normal game opearations<br />
## Database: make sure you DB schema would be sufficient to complete the game and good enough for possible expantions, changing db schema schema after the release even in alpha is very challenging (it is possible but much better if you don't need to deal with it)<br />
# ''' Client side '''<br />
## Check that you use ajaxcall only on player actions and never initiated programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors. This can also break replays and tutorials. ''Exception: sometimes you can do no-op moves with timeouts (i.e. user has only one choice, but its unwise to reveal this information by skipping user turn), timeout has to be canceling itself if state transition happen automaticaly (i.e. during reply)''<br />
# ''' User Interface '''<br />
## Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]<br />
## Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.<br />
## If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.<br />
## If your game elements become blurry or pixellated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]<br />
## Non-self explanatory graphic elements should have tooltips<br />
## Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.<br />
## A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected<br />
## If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.<br />
# ''' Special testing '''<br />
## Click "Use minified JS" and "Use minified CSS" buttons on the game management page, then test your game. This will prevent you from having a panic attack when the game releases in alpha and it is stuck in "Connecting to game".<br />
## Game is tested with spectator (non player observer): change the testuser in the URL to see the game as another user (same URL as when clicking on red arrow). As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.<br />
## Game is tested with in-game replay from last move feature (by clicking on notification log items).<br />
## After finishing a game, it is possible to watch the replay (using the "Replay game" button on the table page) from game start to game end without errors.<br />
## Game works in Chrome and Firefox browsers at least. Also very recommended to test in Edge and Safari.<br />
## Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)<br />
## Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn<br />
## Test your game in 3D mode (if it makes sense; 3D mode can also be disabled through the 'enable_3d' parameter for gameinfos.inc.php, but if it "mostly works", it can be nice to keep it activated even if 2D is more appropriate for the game, just because it's fun to look at)<br />
## Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]<br />
# ''' Cleanup '''<br />
## Remove all unnecessary console.log and other tracing from your js code (Note: technically it is removed by minimizer, but not console.error)<br />
## Remove all unnecessary debug logging from your php code<br />
## Copyright headers in all source files have your name<br />
## Remove unncessery files from main folder (can move some to misc folder)<br />
## Remove all unused graphics from img/ folder<br />
# ''' Static Analysis '''<br />
## Some of the checks above are automated, to run them go to control panel, go to your project and select "Check project" button (it will open like a game table, and you click on Start button to run analysis)<br />
# ''' Finally move to Alpha status '''<br />
## If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it.<br />
## Create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").<br />
## Really ready? Click on the '''Request ALPHA status''' button available above your just built version. You cannot deploy yourself from the "manage game" page until this first ALPHA deploy has been done by the admins. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed. Note: you can also ask for moving your project to "private Alpha" - in this case you will invite people manually rather than having your game immediately visible to the whole BGA reviewers community.<br />
* ''' Wait '''<br />
** When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps.<br />
<br />
=== Move from Alpha to Beta ===<br />
# The implementation '''must be approved by the publisher''' (if not a public domain game)<br />
# Generally it is recommended (but not essential) to have at least 10 approvals from reviewer with rank > 3.5 and not too many bugs opened<br />
# If the game is well-received (preferably game rating ≥4.5) and there are no pending issues the game may pass as administrative discretion without 10+ approvals<br />
# Click on the '''Request BETA status''' button available above your latest build. Clicking this button will file a request in the BGA ticketing system and you'll receive a confirmation email allowing to reply to add some information on the ticket if needed.<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Studio_FAQ&diff=14769
Studio FAQ
2022-09-19T11:20:28Z
<p>Een: Welcome email + support page</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is a place where we will collect and answer frequently asked questions.<br />
<br />
== What is the PHP reference version? ==<br />
<br />
Your game module should be compatible with PHP 7.4.<br />
Some other version information can be found here https://en.doc.boardgamearena.com/Studio_file_reference#software_versions.<br />
<br />
== What should I use to access the files through SFTP? ==<br />
<br />
There is a lot of tools to do that. Use the one you are the most comfortable with.<br />
<br />
On Linux Gnome, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.<br />
<br />
On Windows, there is for example the [http://winscp.net/ WinSCP client].<br />
<br />
See [[Tools_and_tips_of_BGA_Studio#File_Sync]] for more details.<br />
<br />
== I can't edit the files in my game directory, it looks like they are readonly. What's happening? ==<br />
<br />
You can lose access sometimes if you add another developer as read/write or admin.<br />
<br />
To fix you can re-add yourself as Admin. Never remove youself! Just type your own name in user list and select Admin role (in control panel on studio for a specific game).<br />
<br />
Maybe there is a maintenance operation underway.<br />
<br />
If you don't get access back after some time (say one or two hours), please post on dev forum.<br />
<br />
If you are still an admin for your game, re-add yourself as admin - it restores your permissions.<br />
<br />
== What is the working language on BGA studio? ==<br />
<br />
Working language is '''English'''.<br />
<br />
Variables and functions must be named with English words.<br />
<br />
Comments must be written in English.<br />
<br />
Game interface strings and game logs must be written in English.<br />
<br />
== How can I provide translation in my language? == <br />
<br />
The community will translate the game in all language after the game release with the collaborative translation interface can be used to translate into other languages.<br />
<br />
Check [[Translations]] to see how to make your game translatable.<br />
<br />
== I updated the images in the 'img' folder of my game, but they don't show? ==<br />
<br />
'''Concerning game_box.png, game_icon.png and publisher.png''':<br />
You must use "Reload game box image" function from "Control Panel / Manage Games / Your game" to make your change visible.<br />
<br />
'''Concerning other images''':<br />
Other images used during the game are immediately available without any action.<br />
If the images still don't show after that, please try emptying your browser cache and reloading the page (i.e. press reload holding Ctrl button).<br />
<br />
== I added some game options / some game statistics / some game infos but they don't show? ==<br />
<br />
When you modify one of these 3 files, you need to use the corresponding update action from "Control Panel / Manage Games / Your Game" in order we can take this information into account.<br />
<br />
== Should I use images free from copyright? ==<br />
<br />
If you are developing a game in the public domain, yes (or you can make your own if you feel it's better). <br />
<br />
If you are developing a game for which we have a licence, we will usually provide art files from the publisher.<br />
<br />
You can also used shared images provided by boardgame arena - logos, some action buttons, card, meeples, decks.<br />
<br />
If you looking for an icon for an action (i.e. arrow, zoom, search, gears, etc), BGA has access to Font Awesome. It is awesome. But please check icon set for a version that BGA has installed.<br />
<br />
== I registered on Studio but did not receive email ==<br />
<br />
If you did not get email, search for "Welcome on BGA Studio" in your email client (just like that), it sometimes ends up in junk folder.<br />
<br />
If you cannot find it, and you use some weird proprietary email address, it possible that your mail server denies emails from bga. <br />
You can try to register again with the same email, but it likely fail telling you that your account has already been created. But if you have standard email such as gmail, yahoo, outlook use it instead.<br />
<br />
You can get the welcome email re-sent from the login page using the "Welcome email not received?" link.<br />
In case of a persistent issue, you can file a support request from the [https://studio.boardgamearena.com/support studio support page].<br />
<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=How_to_join_BGA_developer_team%3F&diff=14768
How to join BGA developer team?
2022-09-19T11:18:06Z
<p>Een: support page</p>
<hr />
<div><br />
== Is this right for me ==<br />
<br />
Before joining please consider if this is right for you, it is right if<br />
* You like board games and programming and you think it would be a good hobby<br />
* You really want to fix some bugs in already published games<br />
* You want to create a game from public domain (e.g. chinese checkers, bridge, etc.)<br />
* You were hired or persuaded by somebody else to create game adaptation on bga<br />
<br />
<br />
On the other hand<br />
<br />
* If you think you can implement any of the games from top 100 on BGG. We checked and we don't have the license to do it, and if we do, it's already implemented or under way.<br />
* If you are an amateur game designer and you think you can play test a game on BGA platform, it's not a right place, players here like known games. Digital adaptations are very expensive (or time consuming) it won't be worth the effort.<br />
* If you trying to use this platform for something which is not a board game adaptation (e.g. video game, online skill test, etc.). It won't be allowed.<br />
* You are a student who just took first your programming course and think it's a good way to practice web skills. BGA Studio is not an easy framework to use, see skill set below.<br />
* If you think you can make make a lot of money of it, it's not going to happen. But recently it has been increase in demand for paid work, so it is possible to make SOME money this way. <br />
<br />
<br />
Required skills for BGA studio projects:<br />
<br />
* If you are an experienced software developer you can goto next section<br />
* If you are not an experienced developer or not a developer <br />
** You are required to know or learn 5 languages: JavaScript, PHP, SQL, HTML and CSS<br />
** You need to know the basics of object oriented programming, web development and database development<br />
** You need to know how to setup and use development tools and setup remote file synchronization<br />
** You need to know how to use image manipulation software (e.g. Paint.net, Gimp, Photoshop, etc.)<br />
* If you don't have the skills above however there is new feature, called Studio Sandbox! The only language is required there is JavaScript. Check this out https://studio.boardgamearena.com/sandbox<br />
<br />
<br />
As a volunteer developer for BGA, what is expected from me?<br />
<br />
* Nothing is really expected (but on the other hand, do not expect much from anybody else)<br />
* If you manage to get your game across finish line (i.e. published) it is generally expected that you will also fix the bugs. But if you cannot - nobody can force you to do anything (but they may take down the game if maintainer cannot be found)<br />
* The code you wrote will remain with BGA and they can do whatever they want with it (but you can also do whatever you want with your own copy)<br />
* There is documentation, forum and chat with other developers available to help<br />
<br />
What do I get out of it?<br />
<br />
* It is fun to develop a game. And you do it all by yourself!!!<br />
* You can greatly improve your web development skills in ancient web technology and dealing with tiny databases<br />
* You can talk directly to game publishers and game designers of your favorite games and even play with them!<br />
* Eventually you will become famous (in small circles of BGA players who read credits)<br />
<br />
== How to create BGA Studio development account ==<br />
<br />
Registering on BGA Studio is simple and automatic from:<br />
https://studio.boardgamearena.com/<br />
<br />
To register, you must agree with [http://en.doc.boardgamearena.com/images/0/02/BGA_TC_Dev_en.pdf '''BGA Terms & Conditions for developers''']. It's very light, so as to get to the fun part faster.\\\\<br />
<br />
During registration if you will get a database error that user already exists ignore it.<br />
<br />
Once registered, you will get by email<br />
* one login / password to access files through SFTP<br />
* one login / password to access the database (for your games in progress)<br />
* ten logins with numeric suffixes from 0 to 9 and a common simple password to test games on the studio website while developing.<br />
<br />
<br />
If you did not get email, search for "Welcome on BGA Studio" in your email client (just like that), it sometimes ends up in junk folder.<br />
<br />
If you cannot find it, and you use some weird proprietary email address, it possible that your mail server denies emails from bga. <br />
You can try to register again with the same email, but it likely fail telling you that your account has already been created. But if you have standard email such as gmail, yahoo, outlook use it instead.<br />
<br />
You can get the welcome email re-sent from the login page using the "Welcome email not received?" link.<br />
In case of a persistent issue, you can file a support request from the [https://studio.boardgamearena.com/support studio support page].<br />
<br />
<br />
== Ok, I registered, how to start? ==<br />
<br />
Then... well that's all, you can start!<br />
<br />
See [[Studio#Great.2C_I.27m_in.21_..._How_should_I_start.3F|Great, I'm in! ... How should I start?]]<br />
<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Contact_BGA_Studio&diff=14767
Contact BGA Studio
2022-09-19T11:12:23Z
<p>Een: Support page</p>
<hr />
<div>== Purpose ==<br />
This page is to find solutions for technical issues or manual steps related to games development on BGA Studio.<br />
<br />
To contact BGA team if you are a player or a publisher (i.e. not a game software developer) please use this form https://en.boardgamearena.com/faq?anchor=faq_team_contact<br />
<br />
<br />
== Studio Accounts Management ==<br />
<br />
BGA player account is not the same as studio account (even if you name them the same).<br />
<br />
* Create studio account https://studio.boardgamearena.com (if you already logged in logout first)<br />
* Resend welcome email (original) https://studio.boardgamearena.com/account?page=welcomeemail<br />
** Same if you forgot database or ftp account<br />
** Still cannot get email, tried searching in junk for BGA, contact studio (see below) with subject "STUDIO ACCOUNT ACCESS: <account>"<br />
* Forgot password https://studio.boardgamearena.com/account?page=lostpassword<br />
* Cannot ftp<br />
** See section "Help with Game development or setup"<br />
* Upload ssh key https://studio.boardgamearena.com/controlpanel<br />
<br />
== Studio Games Management ==<br />
<br />
* Game management control panel located in Gear link if you click on your Account circle, direct link https://studio.boardgamearena.com/controlpanel<br />
** This allow to create project, delete project and manage projects<br />
* Access to other project source code <br />
** Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/projects page (almost any project). <br />
** If project is not there - its either does not have bgg id, already published (in this case check radio button on this page) or was not developed on studio (some old games). <br />
** You can also try to use direct link https://studio.boardgamearena.com/gamepanel?game=template (replace template with game name in the link)<br />
** If you prefer github see https://en.doc.boardgamearena.com/BGA_Code_Sharing<br />
* Access to frontend<br />
** Even if you cannot get source access via studio, you can see the java code, css and images asset by using Browser dev tools, see [[Practical_debugging]]<br />
* Push game to Alpha or Beta<br />
** You cannot do it yourself, you have to go though checklist first https://en.doc.boardgamearena.com/Pre-release_checklist then email studio account (see details on that page)<br />
* Your project seems to be deleted after you came back a year after - create a new project with SAME name as before (you have to remember name) - it will be restored<br />
* You have permission issues syncing files, but you are admin - re-add yourself as admin via control panel. DO NOT delete yourself, just type name, select Admin and click add.<br />
* You managed to delete yourself from your own project - require admin interferance - contact studio (see below) with subject "STUDIO GAME ACCESS: <gamename>"<br />
* You want to take over abandoned game<br />
** Please first ask on dev forum - it may not be actually abandoned<br />
** You don't actually need to use that project, CLONE the game using control panel (create new project with similar name, copy over). If you don't abandon your project, finish the game and its ready to be published - admin can rename it <br />
* If you really think you need read or write access which you cannot get yourself - contact studio (see below) with subject "STUDIO GAME ACCESS: <gamename>"<br />
<br />
== Help with Game development or setup ==<br />
<br />
If you stuck or looking for help in regards to development (even if you think there is bug in framework) please contact fellow developers first before attempting to contact any of admins<br />
<br />
* Google it, you may find an answer unlreated to bga<br />
* Post question of DISCORD chat server for BGA developers (invite link https://discord.gg/YxEUacY). Do not go there if you are bga user, there is another server for that!<br />
* Search and/or post on [http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]<br />
* If you think there is bug in studio or APIs check these bugs [https://studio.boardgamearena.com/bugs Bug tracking system FOR STUDIO issues and APIs]. You can also submit a bug there<br />
<br />
Also some specific reading may help<br />
* Studio development setup - [[Tools and tips of BGA Studio]]<br />
* Debugging - [[Practical debugging]]<br />
* Completely Stuck - [[Troubleshooting]]<br />
* Anything else - [[Studio]]<br />
<br />
<br />
== Help with Game assets or licenses ==<br />
<br />
* https://studio.boardgamearena.com/licensing<br />
* Graphics help https://en.doc.boardgamearena.com/Game_art:_img_directory<br />
* Request game assets (graphcs) *Missing Link*<br />
<br />
== Last resort ==<br />
<br />
You can file a request that will land in the BGA ticketing system from the [https://studio.boardgamearena.com/support studio support page].<br />
<br />
Pretty please use text above to solve your problems before filing a support request.<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=14488
Game meta-information: gameinfos.inc.php
2022-08-25T11:35:25Z
<p>Een: </p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
__TOC__<br />
<br />
== Overview ==<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Note: if you broke gameinfos and cannot load management page reload using direct URL https://studio.boardgamearena.com/admin/studio/reloadGameInfos.html?game= (with your game name at the end of url).<br />
<br />
Most information provided in this file are self-explainable.<br />
<br />
See sections below for specific cases.<br />
<br />
== Publisher/Designer fields ==<br />
<br />
These fields should match the publisher/designer for the game. In the case of a public domain name, they should be left empty (empty string '')<br />
<br />
== Beta ==<br />
<br />
You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
<br />
== Time Profiles ==<br />
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
<br />
== Number of players ==<br />
<br />
'''players'''<br />
'players' => array( 3, 4, 6 ),<br />
<br />
* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.<br />
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.<br />
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.<br />
<br />
'''suggest_player_number''' / '''not_recommend_player_number'''<br />
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.<br />
<br />
<br />
== Colors ==<br />
<br />
'''player_colors'''<br />
'player_colors' => array( "ff0000", "008000", "0000ff", "ffa500", "ffffff" ),<br />
<br />
This array defines the default player colors, theoretically this can be bigger then maximum number of players but you have to support all of the in your game.<br />
Your setupNewGame in php is responsible for attributing these values to players. See section "Player color preferences" in [[Main_game_logic:_yourgamename.game.php]] for details.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
The score in this case should be 1 for the winner and 0 for the losers.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to true (even if the comment in your game file say the opposite).<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
A maximum of '''ten''' tags can be attributed to your game (not counting complexity and duration tags).<br />
<br />
Tags are useful to place your game in the correct game list section and to give a good quick overview of what the game is about to players.<br />
<br />
'''⚠ Note''': The ''order'' of the tags is very important too, you'll have to put the most relevant first.<br />
<br />
'''⚠ Note''': tags are <b style="color:darkred">only read during the first deploy</b> from the file <code>gameinfos.inc.php</code> ; afterwards, setting tags for a game is done via the [[Game_metadata_manager|Game Metadata Manager]].<br />
<br />
Game complexity (you '''must''' specify one tag '''and only one''' from this category):<br />
* <code>2</code>: Casual games<br />
* <code>3</code>: For regular players<br />
* <code>4</code>: For core gamers<br />
<br />
Duration tags (only indicative - the correct tag will be automatically set by BGA after a while):<br />
* <code>10</code>: Short game (<10 minutes)<br />
* <code>11</code>: Medium length game (10 minutes to 30 minutes)<br />
* <code>12</code>: Long game (>30mn)<br />
<br />
Other tags:<br />
* <code>20</code>: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* <code>22</code>: Prototype (This game has not been published yet)<br />
* <code>23</code>: Classic (This game is a classic from Public Domain)<br />
* <code>25</code>: Party game<br />
* <code>26</code>: Family<br />
* <code>27</code>: Miniatures (figurines)<br />
* <code>28</code>: Recommended in Realtime<br />
* <code>29</code>: Recommended in Turnbased<br />
* <code>30</code>: Best for 2 (best with 2 players) (automatically added to games for 2p only)<br />
<br />
Theme tags:<br />
* <code>100</code>: Fantasy<br />
* <code>101</code>: Science-Fiction<br />
* <code>102</code>: Historical<br />
* <code>103</code>: Adventure<br />
* <code>104</code>: Exploration<br />
* <code>105</code>: Conquest<br />
* <code>106</code>: Building<br />
* <code>107</code>: Western<br />
* <code>108</code>: Espionage<br />
* <code>109</code>: Trains<br />
* <code>110</code>: Sport<br />
* <code>111</code>: Economy<br />
* <code>112</code>: Aviation<br />
* <code>113</code>: Surreal/Silly/Absurd<br />
* <code>114</code>: Animals<br />
* <code>115</code>: Wargame<br />
* <code>1</code>: Abstract game<br />
<br />
Mechanism tags:<br />
* <code>200</code>: Cards (cards plays a central role in this game)<br />
* <code>201</code>: Dice<br />
* <code>202</code>: Solo<br />
* <code>203</code>: Worker placement<br />
* <code>204</code>: Hand management<br />
* <code>205</code>: Bluffing<br />
* <code>206</code>: Tile placement<br />
* <code>207</code>: Combos<br />
* <code>208</code>: Area Majority<br />
* <code>209</code>: Race<br />
* <code>210</code>: Collection<br />
* <code>211</code>: Cooperative<br />
* <code>212</code>: Random<br />
* <code>213</code>: Speed<br />
* <code>214</code>: Asymmetrical<br />
* <code>215</code>: Communication<br />
* <code>216</code>: Conquest<br />
* <code>217</code>: Team<br />
* <code>218</code>: Bidding<br />
* <code>219</code>: Objectives<br />
* <code>220</code>: Trick-taking<br />
* <code>221</code>: Resource management<br />
* <code>222</code>: Roles<br />
* <code>223</code>: Roll & Write<br />
* <code>224</code>: Push your luck<br />
* <code>225</code>: Voting<br />
* <code>226</code>: Word games<br />
* <code>227</code>: Deck Building<br />
* <code>228</code>: Engine building<br />
* <code>229</code>: Drafting<br />
* <code>230</code>: Player elimination<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),<br />
<br />
== Tie breaker description ==<br />
Describe tie breaker score calculation (player_score_aux in player table).<br />
<br />
Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.<br />
<br />
Example:<br />
'tie_breaker_description' => totranslate("Number of remaining cards in hand"),<br />
<br />
== Multiple tie breaker management ==<br />
<br />
If your game has multiple tie breakers, here is what you should do.<br />
<br />
Let's take this example: "In case of a tie, the winner is the game with the most remaining money, then number of buildings built, then number of cards in your hand".<br />
<br />
In this example, your "score_aux" field is probably calculated like this:<br />
<br />
10000 * (remaining_money ) + 100 * (buildings_built) + (number_of_cards)<br />
<br />
In this case, you should add the following in gameinfos.inc.php:<br />
<br />
'tie_breaker_split' => array( 10000, 100 , 1 ),<br />
<br />
It means that the first tie breaker has been multiplied by 10000, the second by 100, and the third by 1.<br />
<br />
Using this, the result screen will be adapted to show exactly what is needed. For example:<br />
* When 2 players are tied, it will show their remaining money.<br />
* If their remaining money are equal, it will show the number of building built in addition to the remaining money.<br />
* If these two tie breaker are still the same, it will show the 3 tie breaking values.<br />
<br />
== Language dependency ==<br />
<br />
If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]<br />
<br />
== Game page warning ==<br />
<br />
If a specific warning is needed on the game page (to discuss and validate with admins) it can be displayed from the game infos. For example for Texas Hold'em:<br />
<br />
'gamepanel_page_warning' => totranslate("There is no real money involved on BGA: this game has the mechanism of Poker but is using points instead of real money."),<br />
<br />
== Coop Elo Mode ==<br />
<br />
For cooperative games, by default players will earn as many Elo points as the score. <br />
<br />
For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill and/or where the number of players has a significant impact on the difficulty, we have to set up a reference scale for Elo points (between 1300 and 2500). Players regularly winning with a specific difficulty setting will have their Elo nearing this value asymptotically over time.<br />
<br />
For this, you have to set up the coop_elo_mode parameter.<br />
<br />
'''Warning: While this can reflect player skills more precisely compared to flat ELO gain, players may abandon losing games or avoid new players to prevent ELO loss.'''<br />
<br />
Related discussion - https://forum.boardgamearena.com/viewtopic.php?f=3&t=24363<br />
<br />
Here is an example using options and win/loss (score 1/0):<br />
<br />
'coop_elo_mode' => [<br />
'type' => 'points_references',<br />
'references' => [<br />
// Difficulty 1<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
// Difficulty 2<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
// Difficulty 3<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
// Difficulty 4<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
// Difficulty 5<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
],<br />
],<br />
<br />
Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:<br />
<br />
'coop_elo_mode' => array(<br />
'type' => 'points_references',<br />
'references' => array(<br />
array(<br />
'players_nbr' => 2,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1350,<br />
2 => 1425,<br />
3 => 1500,<br />
4 => 1576,<br />
5 => 1651,<br />
6 => 1727,<br />
7 => 1802,<br />
8 => 1878,<br />
9 => 1953,<br />
10 => 2029,<br />
11 => 2104,<br />
12 => 2180<br />
)<br />
),<br />
array(<br />
'players_nbr' => 3,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1400,<br />
2 => 1470,<br />
3 => 1541,<br />
4 => 1612,<br />
5 => 1683,<br />
6 => 1754,<br />
7 => 1825,<br />
8 => 1895,<br />
9 => 1966,<br />
10 => 2018,<br />
11 => 2095,<br />
12 => 2250<br />
)<br />
),<br />
array(<br />
'players_nbr' => 4,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1430,<br />
2 => 1505,<br />
3 => 1580,<br />
4 => 1655,<br />
5 => 1730,<br />
6 => 1805,<br />
7 => 1880,<br />
8 => 1955,<br />
9 => 2030,<br />
10 => 2105,<br />
11 => 2180,<br />
12 => 2330<br />
)<br />
),<br />
array(<br />
'players_nbr' => 5,<br />
// 'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1480,<br />
2 => 1558,<br />
3 => 1636,<br />
4 => 1714,<br />
5 => 1792,<br />
6 => 1870,<br />
7 => 1949,<br />
8 => 2027,<br />
9 => 2105,<br />
10 => 2183,<br />
11 => 2261,<br />
12 => 2340<br />
)<br />
)<br />
)<br />
),<br />
<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Tutorials_checklist&diff=13531
Tutorials checklist
2022-06-09T13:14:31Z
<p>Een: </p>
<hr />
<div>In order to allow for a full-fledged tutorial to be built for the game you have adapted on BGA studio:<br />
# the game replay archive generated for the game must be valid (you should be able to run the replay from start to finish without errors using the "Replay game" function on a finished table)<br />
# each action of the replay should be replayable by triggering it manually (i.e. by reproducing the exact same sequence as done played originally during the game<br />
# each element of the game interface should be available for attaching a comment or a highlight component on it.<br />
<br />
You can read more about building tutorials in practice here: https://boardgamearena.com/tutorialfaq<br />
<br />
<br />
If a player trying to create a tutorial reports you an issue about 1) or 2), the most likely reason for the issue is that you have triggered this.ajaxcall() programmatically in a notification handling function or a callback instead of only on a user interface action.<br />
<br />
If a player trying to create a tutorial reports you an issue about 3), you might have some overlapping elements preventing to access the "div" tag of an important interface element to attach tutorial content to it.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Tutorials_checklist&diff=13530
Tutorials checklist
2022-06-09T13:13:06Z
<p>Een: </p>
<hr />
<div>In order to allow for a full-fledged tutorial to be built for the game you have adapted on BGA studio:<br />
# the game replay archive generated for the game must be valid (you should be able to run the replay from start to finish without errors using the "Replay game" function on a finished table)<br />
# each action of the replay should be replayable by triggering it manually (ie by reproducing the exact same sequence as done played originally during the game<br />
# each element of the game interface should be available for attaching a comment or a highlight element on it.<br />
<br />
You can read more about building tutorials in practice here: https://boardgamearena.com/tutorialfaq<br />
<br />
<br />
If a player trying to create a tutorial reports you an issue about 1) or 2), the most likely reason for the issue is that you have triggered this.ajaxcall() programmatically in a notification handling function or a callback instead of only on a user interface action.<br />
<br />
If a player trying to create a tutorial reports you an issue about 3), you might have some overlapping elements preventing to access the "div" tag of an important interface element to attach tutorial content to it.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Tutorials_checklist&diff=13529
Tutorials checklist
2022-06-09T13:12:00Z
<p>Een: Initial version</p>
<hr />
<div>In order to allow for a full-fledged tutorial to be built for the game you have adapted on BGA studio:<br />
1) the game replay archive generated for the game must be valid (you should be able to run the replay from start to finish without errors using the "Replay game" function on a finished table)<br />
2) each action of the replay should be replayable by triggering it manually (ie by reproducing the exact same sequence as done played originally during the game<br />
3) each element of the game interface should be available for attaching a comment or a highlight element on it.<br />
<br />
You can read more about building tutorials in practice here: https://boardgamearena.com/tutorialfaq<br />
<br />
If a player trying to create a tutorial reports you an issue about 1) or 2), the most likely reason for the issue is that you have triggered this.ajaxcall() programmatically in a notification handling function or a callback instead of only on a user interface action.<br />
<br />
If a player trying to create a tutorial reports you an issue about 3), you might have some overlapping elements preventing to access the "div" tag of an important interface element to attach tutorial content to it.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Studio&diff=13528
Studio
2022-06-09T13:00:06Z
<p>Een: /* BGA Studio user guide */ add tutorials checklist entry</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
[[File:Bga_studio_small.jpg]]<br />
<br />
Note: Please DO NOT translate Studio Documentation, so that there can be one place where you can find the latest information available.<br />
<br />
__TOC__<br />
<br />
== What is Board Game Arena Studio? ==<br />
<br />
'''Board Game Arena Studio''' is a platform to build online board game adaptations using the Board Game Arena platform.<br />
<br />
It is open to any gamer with software development skills :)<br />
<br />
BGA Studio website: https://studio.boardgamearena.com<br />
<br />
Original announcement on BGA forum: https://forum.boardgamearena.com/viewtopic.php?f=10&t=1973<br />
<br />
== Discover BGA Studio in 5 presentations ==<br />
<br />
Why, how, what... to start discovering BGA Studio, we prepared 5 "powerpoint" presentations for you:<br />
<br />
* [http://www.slideshare.net/boardgamearena/5-reasons-why-you-should-use-bga-studio-for-your-online-board-game 5 reasons why you should use BGA Studio for your online board game] (or [http://en.doc.boardgamearena.com/images/5/58/1-why-developing.pdf Download as PDF])<br />
* [http://www.slideshare.net/boardgamearena/the-8-steps-to-create-a-board-game-on-board-game-arena The 8 steps to create a board game on Board Game Arena] (or [http://en.doc.boardgamearena.com/images/1/1e/2-8-steps-to-realize.pdf Download as PDF])<br />
* [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] (or [http://en.doc.boardgamearena.com/images/7/79/3-thebgaframework.pdf Download as PDF])<br />
* [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine] (or [http://en.doc.boardgamearena.com/images/9/98/4-gamestates.pdf Download as PDF])<br />
* [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] (or [http://en.doc.boardgamearena.com/images/7/76/5-guidelines.pdf Download as PDF])<br />
<br />
== How to join the BGA developer team? ==<br />
<br />
Please see this page: [[How to join BGA developer team?]]<br />
<br />
== Great, I'm in! ... How should I start? ==<br />
<br />
If you didn't already, check the presentations at the top of this page to get the basics.<br />
<br />
Then, you should checkout the [[First steps with BGA Studio]] to make sure that runs fine.<br />
<br />
After that, we strongly advise you to take one of these game creation tutorials:<br />
* [[Tutorial reversi]] - an abstract strategy game played on an 8×8 uncheckered board for 2 players<br />
* [[Tutorial gomoku]] - an abstract strategy game tic-tac-toe style for 2 players<br />
* [[Tutorial hearts]] - a card game for 4 players<br />
<br />
Then start editing files and see what happens! ;)<br />
<br />
Once you're done with tutorials, you can start a real game (or join existing project)<br />
* [[Create a game in BGA Studio: Complete Walkthrough]] <br />
<br />
If you have any questions, please check out the [[Studio FAQ]] or [[Contact BGA Studio]].<br />
<br />
<br />
To search wiki pages on studio enter this text in search bar: <br />
"Category:Studio" white rabbit <br />
That is if you want to search for white rabbit<br />
<br />
== BGA Studio documentation ==<br />
<br />
=== BGA Studio Framework reference ===<br />
<br />
This part of the documentation focuses on the development framework itself: functions and methods available to build your game.<br />
<br />
[[Studio file reference|File structure of a BGA game]]<br />
<br />
==== Game logic (Server side) ====<br />
<br />
* [[Main game logic: yourgamename.game.php]]<br />
* [[Your game state machine: states.inc.php]]<br />
* [[Game database model: dbmodel.sql]]<br />
* [[Players actions: yourgamename.action.php]]<br />
* [[Game material description: material.inc.php]]<br />
* [[Game statistics: stats.inc.php]]<br />
<br />
==== Game interface (Client side) ====<br />
<br />
* [[Game interface logic: yourgamename.js]]<br />
* [[Game art: img directory]]<br />
* [[Game interface stylesheet: yourgamename.css]]<br />
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]<br />
* [[Your game mobile version]]<br />
<br />
==== Other components ====<br />
<br />
* [[Translations]] (how to make your game translatable)<br />
* [[Game options and preferences: gameoptions.inc.php]]<br />
* [[Game meta-information: gameinfos.inc.php]]<br />
* [[Game replay]]<br />
* [[3D]]<br />
<br />
<br />
=== BGA Studio game components reference ===<br />
<br />
Game components are useful tools you can use in your game adaptations.<br />
<br />
JS:<br />
<br />
* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).<br />
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).<br />
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.<br />
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).<br />
* [[Draggable]]: a JS component to manage drag'n'drop actions.<br />
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.<br />
* [[Anti-Stock]]:Code snippets in ValinaJS/HTML5 to do what stock does (that is if you cannot beat Stock into submission)<br />
<br />
PHP:<br />
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).<br />
<br />
Reference for classes in game class hierarchy<br />
<br />
* [[Table]]: a PHP class that you inherit from for the game php<br />
<br />
=== BGA Studio user guide ===<br />
<br />
This part of the documentation is a user guide for the BGA Studio online development environment.<br />
<br />
Lifecycle<br />
<br />
* [[BGA game Lifecycle]]<br />
* [[Create a game in BGA Studio: Complete Walkthrough]]<br />
* [[Pre-release checklist]] - Go throught this list if you think you done development<br />
* [[Post-release phase]]<br />
<br />
<br />
Tools and Advice<br />
* [[BGA Studio Guidelines]]<br />
* [[Tutorials checklist]]<br />
* [[I wish I knew this when I started]] - one liners on most common missed features, mistakes, etc with further doc references<br />
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment<br />
** [[Practical debugging]] - Tips focused on debugging<br />
** [[Studio logs]] - Instructions for log access<br />
** [[Troubleshooting]] - Most common "I am really stuck" situations<br />
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks<br />
** [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game<br />
** [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner<br />
** [[Bots and Artificial Intelligence]] - How to add AI/Bots to the game<br />
* [[Studio FAQ]]<br />
<br />
Sharing<br />
* [[Common board game elements image resources]] - Dice, meeples, cubes, etc<br />
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links<br />
<br />
== Other resources ==<br />
<br />
[http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]<br />
<br />
[https://studio.boardgamearena.com/bugs Bug tracking system FOR STUDIO issues and APIs]<br />
<br />
DISCORD chat server/room invite link https://discord.gg/YxEUacY if it does not work check this topic https://forum.boardgamearena.com/viewtopic.php?f=12&t=17403&hilit=discord<br />
<br />
Developer BLOGS https://bga-devs.github.io/blog/<br />
<br />
[[Contact BGA Studio]]<br />
<br />
== Software Versions ==<br />
<br />
Versions currently used by BGA framework:<br />
<br />
* Dojo Toolkit 1.15<br />
* PHP: 7.4<br />
* SQL: MySQL 5.7<br />
* JS/CSS/HTML: limited by what minimization tools support [[Game_interface_logic:_yourgamename.js#Javascript_minimization_.28after_July_2020.29]]<br />
* Font Awesome: 4.7 https://fontawesome.com/v4.7/icons/<br />
<br />
=== PHP Extensions Used ===<br />
<br />
The following PHP extensions are - as of May 8th, 2022 - in use in BGA Studio and available:<br />
<br />
* date<br />
* libxml<br />
* openssl<br />
* pcre<br />
* zlib<br />
* filter<br />
* hash<br />
* Reflection<br />
* SPL<br />
* session<br />
* standard<br />
* sodium<br />
* apache2handler<br />
* mysqlnd<br />
* PDO<br />
* xml<br />
* apcu<br />
* bz2<br />
* calendar<br />
* ctype<br />
* curl<br />
* dom<br />
* mbstring<br />
* FFI<br />
* fileinfo<br />
* ftp<br />
* gd<br />
* gettext<br />
* gmp<br />
* iconv<br />
* igbinary<br />
* json<br />
* exif<br />
* msgpack<br />
* mysqli<br />
* pdo_mysql<br />
* apc<br />
* posix<br />
* readline<br />
* shmop<br />
* SimpleXML<br />
* sockets<br />
* sysvmsg<br />
* sysvsem<br />
* sysvshm<br />
* tokenizer<br />
* v8js<br />
* xmlreader<br />
* xmlwriter<br />
* xsl<br />
* zip<br />
* Phar<br />
* memcached<br />
* Zend OPcache<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_interface_logic:_yourgamename.js&diff=13527
Game interface logic: yourgamename.js
2022-06-09T12:55:21Z
<p>Een: /* this.ajaxcall(url, parameters, obj_callback, callback, callback_error, ajax_method) */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the main file for your game interface. Here you will define:<br />
<br />
* Which actions on the page will generate calls to the server.<br />
* What happens when you get a notification for a change from the server and how it will show in the browser. <br />
<br />
<br />
__TOC__<br />
<br />
== File structure ==<br />
<br />
The details of how the file is structured are described below with comments on the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* '''constructor''': here you can define global variables for your whole interface.<br />
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.<br />
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.<br />
* '''onLeavingState''': this method is called when leaving a game state.<br />
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.<br />
* ''(utility methods)'': this is where you can define your utility methods.<br />
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).<br />
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.<br />
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.<br />
<br />
<br />
More details:<br />
<br />
;setup(gamedatas) <br />
This method must set up the game user interface according to current game situation specified in parameters.<br />
The method is called each time the game interface is displayed to a player, ie:<br />
<br />
- when the game starts<br />
<br />
- when a player refreshes the game page (F5)<br />
<br />
"gamedatas" argument contains all datas retrieved by your "getAllDatas" PHP method.<br />
<br />
;onEnteringState(stateName, args)<br />
This method is called each time we are entering into a new game state.<br />
You can use this method to perform some user interface changes at this moment.<br />
To access state arguments passed via calling arg* method use args.args.<br />
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.<br />
<br />
'''Warning''': for multipleactiveplayer states:<br />
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/unactive status.<br />
If you are doing initialization of some structure which do not depend on active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator) <br />
for the main switch in that method.<br />
<br />
See more details in [[Your_game_state_machine:_states.inc.php#Diffrence_between_Single_active_and_Multi_active_states]]<br />
<br />
;onLeavingState(stateName)<br />
This method is called each time we are leaving a game state.<br />
You can use this method to perform some user interface changes at this moment (i.e. cleanup).<br />
<br />
;onUpdateActionButtons(stateName, args)<br />
In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.<br />
To access state arguments passed via calling arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.<br />
This method is called when active or multiactive player changes. In classic "activePlayer" state this method is called before the onEnteringState state.<br />
In multipleactiveplayer state it is a mess. The sequencing of calls would depends on either you get into that state from transitions OR from reloading the whole game (i.e. F5).<br />
<br />
See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]<br />
<br />
== General tips ==<br />
<br />
; this.player_id<br />
: ID of the player on whose browser the code is running.<br />
<br />
; this.isSpectator<br />
: Flag set to true if the user at the table is a spectator (not a player).<br />
: Note: This is a variable, not a function.<br />
: Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].<br />
<br />
; this.gamedatas<br />
: Contains the initial set of data to init the game, created at game start or by game refresh (F5).<br />
: You can update it as needed to keep an up-to-date reference of the game on the client side if you need it. (Most of the time this is unnecessary).<br />
: ''Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the table administrator to store data.''<br />
: ''Updating and using it after initialization might break some features relying on it.''<br />
<br />
; this.isCurrentPlayerActive()<br />
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.<br />
<br />
; this.getActivePlayerId()<br />
: Return the ID of the active player, or null if we are not in an "activeplayer" type state.<br />
<br />
; this.getActivePlayers()<br />
: Return an array with the IDs of players who are currently active (or an empty array if there are none).<br />
<br />
; this.bRealtime<br />
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.<br />
<br />
; g_replayFrom<br />
: Global contains reply number in live game, it is set to undefined (i.e. not set) when it is not a reply mode, so consequentially the good check is '''g_replayFrom !== undefined''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "reply from this move" in the log)<br />
<br />
; g_archive_mode<br />
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)<br />
<br />
; this.instantaneousMode<br />
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)<br />
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.<br />
<br />
; g_tutorialwritten<br />
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.<br />
{<br />
author: "91577332",<br />
id: "576",<br />
mode: "view"<br />
status: "alpha"<br />
version_override: null<br />
viewer_id: "84554161"<br />
}<br />
<br />
You may consider making a function like this, to detect if the game is in a read-only state:<br />
<br />
// Returns true for spectators, instant replay (during game), archive mode (after game end)<br />
isReadOnly: function () {<br />
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;<br />
}<br />
<br />
== Dojo framework ==<br />
<br />
BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].<br />
<br />
The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.<br />
<br />
To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.<br />
<br />
== Javascript minimization (after July 2020) ==<br />
<br />
For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).<br />
<br />
NB: it has been reported that there is an issue with this minifier and percentage values for opacity.<br />
<br />
== Accessing and manipulating the DOM ==<br />
<br />
'''$('some_html_element_id')'''<br />
<br />
The $() function is used to get an HTML element using its "id" attribute.<br />
<br />
Example 1: modify the content of a "span" element:<br />
<br />
<pre><br />
In your HTML code:<br />
<span id="a_value_in_the_game_interface">1234</span><br />
<br />
In your Javascript code:<br />
$('a_value_in_the_game_interface').innerHTML = "9999";<br />
</pre><br />
<br />
Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.<br />
Note²: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e. <br />
<pre><br />
foo: function(card) {<br />
card = $(card); // now its node, no need to write if (typeof card === 'string') ...<br />
// but its good idea to check for null here<br />
...<br />
}<br />
</pre><br />
<br />
<br />
'''dojo.style'''<br />
<br />
With dojo.style you can modify the CSS property of any HTML element in your interface.<br />
<br />
Examples:<br />
<br />
<pre><br />
// Make an element disappear<br />
dojo.style( 'my_element', 'display', 'none' );<br />
<br />
// Give an element a 2px border<br />
dojo.style( 'my_element', 'borderWidth', '2px' );<br />
<br />
// Change the background position of an element<br />
// (very practical when you are using CSS sprites to transform an element to another)<br />
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );<br />
</pre><br />
<br />
Note: you must always use dojo.style to modify the CSS properties of HTML elements.<br />
<br />
Note²: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).<br />
<br />
'''Vanila JS style'''<br />
$('my_element').style.display='none'; // set<br />
var display = $('my_element').style.display; // get<br />
$('my_element').style.removeProperty('display'); // remove<br />
<br />
'''dojo.addClass''', '''dojo.removeClass''', '''dojo.hasClass''', '''dojo.toggleClass'''<br />
<br />
In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).<br />
<br />
Advantages are:<br />
* All your CSS stuff remains in your CSS file.<br />
* You can add/remove a list of CSS modifications with a simple function and without error.<br />
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.<br />
<br />
Example from ''Reversi'':<br />
<br />
<pre><br />
// We add "possibleMove" to an element<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
<br />
// In our CSS file, the class is defined as:<br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
<br />
// So we've applied 4 CSS property changes in one line of code.<br />
<br />
// ... and when we need to check if a square is a possible move on the client side:<br />
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{ ... }<br />
<br />
// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
</pre><br />
<br />
Conclusion: We encourage you to use '''dojo.addClass''', '''dojo.removeClass''' and '''dojo.hasClass''' to make your life easier :)<br />
<br />
'''dojo.attr'''<br />
<br />
With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.<br />
<br />
Exemple:<br />
<pre><br />
// Get the title of a node<br />
var title = dojo.attr( id, 'title' );<br />
// Change the height of a node<br />
dojo.attr( 'img_growing_tree', 'height', 100 );<br />
</pre><br />
<br />
'''Vanila JS attr'''<br />
<br />
$(token).id=new_id; // set attr for "id"<br />
var id = $(token).id; // get<br />
<br />
<br />
'''dojo.query'''<br />
<br />
With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.<br />
<br />
Example:<br />
<pre><br />
// All elements with class "possibleMove":<br />
var elements = dojo.query( '.possibleMove' );<br />
<br />
// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):<br />
dojo.query( '#board .token' ).length;<br />
</pre><br />
<br />
But what is really cool with dojo.query is that you can combine it with almost all methods above.<br />
<br />
Examples:<br />
<pre><br />
// Trigger a method when the mouse enter in any element with class "meeple":<br />
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );<br />
<br />
// Hide all meeples who are on the board<br />
dojo.query( '#board .meeple' ).style( 'display', 'none' );<br />
</pre><br />
<br />
'''Vanila JS query'''<br />
<br />
var cards=document.querySelectorAll(".hand .card");// all cards in all hands<br />
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand<br />
var card=document.querySelector(".hand .card");// first card or null if none (super handy)<br />
<br />
'''dojo.place'''<br />
<br />
dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.<br />
<br />
<pre><br />
// Insert your HTML code as a child of a container element<br />
dojo.place( "<your html code>", "your_container_element_id" );<br />
<br />
// Replace the container element with your new html<br />
dojo.place( "<your html code>", "your_container_element_id", "replace" );<br />
<br />
</pre><br />
<br />
The third parameter of dojo.place can take various interesting values:<br />
<br />
"replace" : (see description above).<br />
<br />
"first" : Places the node as a child of the reference node. The node is placed as the first child.<br />
<br />
"last" (default) : Places the node as a child of the reference node. The node is placed as the last child.<br />
<br />
"before" : places the node right before the reference node.<br />
<br />
"after" : places the node right after the reference node.<br />
<br />
"only" : replaces all children of the reference node with the node.<br />
<br />
positive integer: This parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child. <br />
<br />
See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]<br />
<br />
Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".<br />
<br />
But you can also relocate elements like that. Note: it won't animate if you do that.<br />
<br />
<br />
'''dojo.empty'''<br />
<br />
Remove all children of the node element<br />
dojo.empty('my_hand');<br />
<br />
'''dojo.destroy'''<br />
<br />
Remove the element<br />
<br />
dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode<br />
<br />
'''dojo.create'''<br />
<br />
Create element<br />
<br />
dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"<br />
<br />
'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''<br />
<br />
Same as dojo.style(), but for all the nodes set with the specified cssClassName<br />
<br />
'''this.format_block'''<br />
This bga function that takes global var from template file and substitute variables, typical use would be<br />
<br />
var player = gamedatas.players[player_id];<br />
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file <br />
<br />
'''this.format_string'''<br />
This bga function just substitute variables in a string, i.e.<br />
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );<br />
<br />
'''this.format_string_recursive'''<br />
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.<br />
<br />
=== Animations ===<br />
<br />
'''Dojo Animations'''<br />
<br />
BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).<br />
<br />
However, most of the time, you can just use methods below, which are built on top of Dojo Animation.<br />
<br />
Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.<br />
<br />
Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.<br />
<br />
<br />
'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''<br />
<br />
You can use slideToObject to "slide" an element to a target position.<br />
<br />
Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.<br />
<br />
The parameters are:<br />
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.<br />
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.<br />
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.<br />
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.<br />
<br />
BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.<br />
<br />
Example:<br />
<pre><br />
this.slideToObject( "some_token", "some_place_on_board" ).play();<br />
</pre><br />
<br />
<br />
'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''<br />
<br />
This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".<br />
<br />
Example: slide a token to some place on the board, 10 pixels to the bottom:<br />
<pre><br />
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();<br />
</pre><br />
<br />
'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''<br />
<br />
This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.<br />
<br />
slideTemporaryObject does all of this for you:<br />
* mobile_obj_html is a piece of HTML code that represent the object to slide.<br />
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.<br />
* from is the ID of the origin of the slide.<br />
* to is the ID of the target of the slide.<br />
* duration/delay works exactly like in "slideToObject"<br />
<br />
Example:<br />
<pre><br />
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();<br />
</pre><br />
<br />
'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''<br />
<br />
This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.<br />
<br />
It works the same as this.slideToObject and takes the same arguments, but it starts the animation. <br />
<br />
Example:<br />
<pre><br />
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );<br />
</pre><br />
<br />
'''this.fadeOutAndDestroy( node, duration, delay )'''<br />
<br />
This function fade out the target HTML node, then destroy it. Its starts the animation.<br />
<br />
Example:<br />
<pre><br />
this.fadeOutAndDestroy( "a_card_that_must_disappear" );<br />
</pre><br />
<br />
CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.<br />
<br />
'''Rotating elements'''<br />
<br />
You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.<br />
<br />
This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.<br />
<br />
IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):<br />
<br />
<pre><br />
var transform;<br />
dojo.forEach(<br />
['transform', 'WebkitTransform', 'msTransform',<br />
'MozTransform', 'OTransform'],<br />
function (name) {<br />
if (typeof dojo.body().style[name] != 'undefined') {<br />
transform = name;<br />
}<br />
});<br />
// ... and then use "transform" as the name of your CSS property for rotation<br />
</pre><br />
<br />
Note: This wiki was probably written 10 years ago - now all modern broser support 'transform' so just ignore this and use transform.<br />
<br />
<br />
'''Animation Callbacks'''<br />
<br />
If you wish to run some code only after an animation has completed you can do this by linking a callback method.<br />
<br />
<pre><br />
var animation_id = this.slideToObject( mobile_obj, target_obj, duration, delay );<br />
dojo.connect(animation_id, 'onEnd', dojo.hitch(this, 'callback_function', parameters));<br />
animation_id.play();<br />
<br />
…<br />
<br />
callback_function: function(params) {<br />
// this will be called after the animation ends<br />
},<br />
</pre><br />
<br />
If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).<br />
<br />
=== Moving elements ===<br />
<br />
'''this.placeOnObject( mobile_obj, target_obj )'''<br />
<br />
placeOnObject works exactly like "slideToObject", except that the effect is immediate and that it is centered.<br />
<br />
This is not really an animation, but placeOnObject is frequently used before starting an animation.<br />
<br />
Example:<br />
<pre><br />
// (We just created an object "my_new_token")<br />
<br />
// Place the new token on current player board<br />
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );<br />
<br />
// Then slide it to its position on the board<br />
this.slideToObject( "my_new_token", "a_place_on_board" ).play();<br />
</pre><br />
<br />
'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''<br />
<br />
This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".<br />
<br />
''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.<br />
<br />
'''this.attachToNewParent( mobile_obj, target_obj )'''<br />
<br />
With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of <br />
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.<br />
<br />
Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.<br />
<br />
Why using this method?<br />
<br />
Changing the HTML parent of an element can be useful for the following reasons:<br />
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.<br />
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.<br />
<br />
CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).<br />
<br />
== Players input ==<br />
<br />
<br />
==== dojo.connect(element, event, context, method) ====<br />
<br />
Used to associate a player event with one of your notification methods.<br />
<br />
Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):<br />
<pre><br />
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );<br />
</pre><br />
Same idea but base on query (i.e. all element of 'pet' class)<br />
dojo.query(".pet").connect('onclick', this, 'onPet');<br />
<br />
Note: the methods described here are the only correct ways to associate a player input event to your code, and you should not use anything else.<br />
<br />
==== this.connect(element, event, handler) ====<br />
<br />
Used to associate a player event with one of your notification methods.<br />
<br />
this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );<br />
<br />
Or you can use an in-place handler<br />
<br />
this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );<br />
<br />
Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.<br />
<br />
<br />
==== this.connectClass(cssClassName, event, handler) ====<br />
<br />
Same as connect(), but for all the nodes set with the specified cssClassName.<br />
<pre><br />
this.connectClass('pet', 'onclick', 'onPet');<br />
</pre><br />
<br />
====this.disconnect(element, event)====<br />
<br />
Disconnect event handler (previously registered with this.connect or this.connectClass).<br />
<br />
this.disconnect( $('my_element'), 'onclick');<br />
<br />
Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.<br />
<br />
==== this.disconnectAll() ====<br />
<br />
Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)<br />
<br />
==== this.checkAction(action, nomessage) ====<br />
<br />
Check if player can do the specified action by taking into account:<br />
* current game state<br />
* interface locking (a player can't do any action if an action is already in progress)<br />
<br />
return true if action is authorized (i.e: the action is listed as a "possibleaction" in current game state).<br />
<br />
return false and display an error message if not authorized (display no message if nomessage parameter is true). <br />
The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".<br />
<br />
Example:<br />
<pre><br />
function onClickOnGameElement( evt ) {<br />
if( this.checkAction( "my_action" ) ) {<br />
// Do the action<br />
}<br />
}<br />
</pre><br />
<br />
==== this.checkPossibleActions(action, nomessage) ====<br />
<br />
* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account (bug or feature?)<br />
<br />
Check if player can do the specified action by taking into account:<br />
* current game state<br />
<br />
<br />
==== this.ajaxcall(url, parameters, obj_callback, callback, callback_error, ajax_method) ====<br />
<br />
This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.<br />
<br />
* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"<br />
* parameters: an array of parameter to send to the game server. <br />
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call.<br />
** Note: Restricted parameter names (please don't use them):<br />
*** "action"<br />
*** "module"<br />
*** "class"<br />
* obj_callback: must be set to "this".<br />
* callback: a function to trigger when the server returns and everything went fine (not used, as all data handling is done via notifications).<br />
* callback_error: (optional and rarely used) a function to trigger when the server returns an error. if no error this function is called with parameter value false.<br />
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.<br />
<br />
Usage:<br />
<pre><br />
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true, <br />
arg1: myarg1, <br />
arg2: myarg2, <br />
...<br />
}, this, function( result ) {<br />
// Do some stuff after a successful call<br />
// NB : usually not needed as changes must be handled by notifications<br />
// You should NOT modify the interface in a callback or it will most likely break the framework replays (or make it inaccurate)<br />
// You should NOT make another ajaxcall in a callback in order not to create race conditions<br />
} );<br />
</pre><br />
<br />
Note: to reduce the boilerplate code you can define your own wrapper, which will do checking, locking and allow to skip parameters, for example<br />
<pre><br />
ajaxcallwrapper: function(action, args, handler) {<br />
if (!args) {<br />
args = [];<br />
}<br />
args.lock = true;<br />
<br />
if (this.checkAction(action)) {<br />
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, this, (result) => { }, handler);<br />
}<br />
},<br />
</pre><br />
This can be called like this which is a lot more compact<br />
<pre><br />
this.ajaxcallwrapper('playDraw');<br />
this.ajaxcallwrapper('playMove', {card: id})<br />
</pre><br />
<br />
==== this.isInterfaceLocked() ====<br />
<br />
When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).<br />
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors.<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Notifications ==<br />
<br />
When something happens on the server side, your game interface Javascript logic received a notification.<br />
<br />
Here's how you can handle these notifications on the client side.<br />
<br />
=== Subscribe to notifications ===<br />
<br />
Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.<br />
<br />
Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):<br />
<br />
<pre><br />
// In setupNotifications method:<br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
</pre><br />
<br />
Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.<br />
<br />
Then, you have to define your "notif_playDisc" method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".<br />
<br />
Example:<br />
<br />
PHP<br />
<br />
<pre><br />
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );<br />
</pre><br />
<br />
JavaScript<br />
<br />
<pre><br />
//You can access the "myArgument" like this:<br />
notif_myNotification: function( notif )<br />
{<br />
alert( "myArgument = " + notif.args.myArgument );<br />
}<br />
</pre><br />
<br />
=== The notification Object received by client ===<br />
<br />
When sending a notification on your PHP, the client side will receive an Object with the following attributes:<br />
<br />
* args : This is the arguments that you passed on your notification method on php<br />
* bIsTableMsg : Boolean, is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)<br />
* channelorig : information about table ID (formatted as : "/table/t[TABLE_NUMBER]")<br />
* gamenameorig : name of the game<br />
* log: the log information as written in PHP function<br />
* move_id : ID of the move associated with the notification<br />
* table_id : ID of the table<br />
* time : UNIX GMT time<br />
* type : name of the notification<br />
* uid : identifier of the notification<br />
<br />
'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''<br />
<br />
=== Synchronous notifications ===<br />
<br />
When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.<br />
<br />
However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.<br />
<br />
As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.<br />
<br />
Here's how we do this, right after our subscription:<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler<br />
</pre><br />
<br />
-----<br />
<br />
It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.<br />
<br />
For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.<br />
<br />
* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!<br />
<br />
<pre><br />
setupNotifications: function () {<br />
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );<br />
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic<br />
...<br />
},<br />
<br />
notif_cardPlayed: function (notif) {<br />
// MUST call setSynchronousDuration<br />
<br />
// Example 1: From notification args (PHP)<br />
this.notifqueue.setSynchronousDuration(notif.args.duration);<br />
...<br />
<br />
// Or, example 2: Match the duration to a Dojo animation<br />
var anim = dojo.fx.combine([<br />
...<br />
]);<br />
anim.play();<br />
this.notifqueue.setSynchronousDuration(anim.duration);<br />
},<br />
</pre><br />
<br />
=== WARNING: combining synchronous and ignored notifications ===<br />
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):<br />
<br />
<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre><br />
<br />
then you CANNOT do<br />
<br />
<pre>this.notifqueue.setSynchronous('myNotif');</pre><br />
<br />
as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.<br />
<br />
The workaround is to set a "dummy" time:<br />
<br />
<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre><br />
<br />
whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.<br />
<br />
<br />
=== Ignoring notifications ===<br />
Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.<br />
<br />
The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").<br />
<br />
In X.game.php<br />
<pre><br />
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [<br />
'player_id' => $playerId,<br />
'player_name' => $this->getActivePlayerName()<br />
]);<br />
<br />
$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [<br />
"type" => $card["type"],<br />
"cardName" => $this->getCardName($card["type"])<br />
]);<br />
</pre><br />
<br />
The problem with this approach is that the active player will receive two notifications:<br />
* Player1 received a card<br />
* You received Ace of Hearts<br />
<br />
Hence, notification ignoring. Similar to setting a synchronous notification above, you can set up a check whether a notification should be ignored:<br />
<pre><br />
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );<br />
</pre><br />
<br />
NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.<br />
<br />
'''setIgnoreNotificationCheck(notificationId, predicate)'''<br />
This method will set a check whether any of notifications of specific type should be ignored.<br />
<br />
The parameters are:<br />
* notificationId: before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored<br />
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored<br />
<br />
IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.<br />
<br />
IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should preserve it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].<br />
<br />
=== Pre-defined notification types ===<br />
<br />
'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.<br />
<br />
'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)<br />
<br />
// You can call this on php side without doing anything on client side<br />
self::notifyAllPlayers( 'message', 'hello', [] );<br />
<br />
'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.<br />
<br />
<pre><br />
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds<br />
</pre><br />
<br />
== Tooltips ==<br />
<br />
'''this.addTooltip( nodeId, helpStringTranslated, actionStringTranslated, delay )'''<br />
<br />
Add a simple text tooltip to the DOM node.<br />
<br />
Specify 'helpStringTranslated' to display some information about "what is this game element?".<br />
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".<br />
<br />
You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.<br />
<br />
When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.<br />
<br />
Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).<br />
<br />
Example:<br />
<pre><br />
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );<br />
</pre><br />
<br />
Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique<br />
<br />
'''this.addTooltipHtml( nodeId, html, delay )'''<br />
<br />
Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).<br />
<br />
'''this.addTooltipToClass( cssClass, helpStringTranslated, actionStringTranslated, delay )'''<br />
<br />
Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.<br />
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );<br />
<br />
IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.<br />
<br />
'''this.addTooltipHtmlToClass( cssClass, html, delay )'''<br />
<br />
Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).<br />
<br />
IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.<br />
<br />
'''this.removeTooltip( nodeId )'''<br />
<br />
Remove a tooltip from the DOM node with given id.<br />
<br />
'''force tooltip to open'''<br />
<br />
If you want to force tooltip to open in reaction to some other action, i.e. click you can do this<br />
<br />
this.tooltips[id].open(id)<br />
<br />
where id is the id of the tooltip node where tooltip was installed.<br />
<br />
== Dialogs, warning messages, confirmation dialogs, ... ==<br />
<br />
=== Warning messages ===<br />
<br />
Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.<br />
<br />
Ex: someone fulfills one of the end of the game conditions, so this is the last turn.<br />
<br />
'''this.showMessage( msg, type )'''<br />
<br />
showMessage shows a message in a big rectangular area on the top of the screen of the current player.<br />
<br />
* "msg" is the string to display. It should be translated.<br />
* "type" can be set to "info", "error", or "only_to_log". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.<br />
<br />
Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.<br />
<br />
=== Confirmation dialog ===<br />
<br />
'''confirmationDialog( message, yesHandler, noHandler )'''<br />
<br />
<br />
When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.<br />
<br />
CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.<br />
<br />
The situations where you should use a confirmation dialog are the following:<br />
* It must not happen very often during a game.<br />
* It must be linked to an action that can really "kill a game" if the player does not pay attention.<br />
* It must be something that can be done by mistake (ex: a link on the action status bar).<br />
<br />
How to display a confirmation dialog:<br />
<pre><br />
this.confirmationDialog(_('Are you sure you want to bake the pie?'), () => {<br />
this.bakeThePie();<br />
}); <br />
return; // nothing should be called or done after calling this, all action must be done in the handler <br />
</pre><br />
<br />
=== Multiple choice dialog ===<br />
You can use this dialog to give user a choice with small amount of options:<br />
<pre><br />
var keys = [1,5,10];<br />
this.multipleChoiceDialog(<br />
_('How many bugs to fix?'), keys, <br />
(choice) => {<br />
var bugchoice = keys[choice];<br />
console.log('dialog callback with '+bugchoice);<br />
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} );<br />
}<br />
);<br />
</pre><br />
<br />
=== Dialogs ===<br />
<br />
As a general rule, you shouldn't use dialogs windows.<br />
<br />
BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.<br />
<br />
Sometimes although, you need to display a dialog window. Here is how you do this:<br />
<br />
<br />
<br />
// Create the new dialog over the play zone. You should store the handler in a member variable to access it later<br />
this.myDlg = new ebg.popindialog();<br />
this.myDlg.create( 'myDialogUniqueId' );<br />
this.myDlg.setTitle( _("my dialog title to translate") );<br />
this.myDlg.setMaxWidth( 500 ); // Optional<br />
<br />
// Create the HTML of my dialog. <br />
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]<br />
var html = this.format_block( 'jstpl_myDialogTemplate', { <br />
arg1: myArg1,<br />
arg2: myArg2,<br />
...<br />
} ); <br />
<br />
// Show the dialog<br />
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog<br />
this.myDlg.show();<br />
<br />
// Now that the dialog has been displayed, you can connect your method to some dialog elements<br />
// Example, if you have an "OK" button in the HTML of your dialog:<br />
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){<br />
evt.preventDefault();<br />
this.myDlg.destroy();<br />
} );<br />
<br />
If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:<br />
// Removes the default close icon<br />
this.myDlg.hideCloseIcon();<br />
<br />
// Replace the function call when it's clicked<br />
this.myDlg.replaceCloseCallback( function() { ... } );<br />
<br />
=== Scoring dialogs ===<br />
<br />
Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.<br />
<br />
Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.<br />
<br />
Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.<br />
<br />
Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":<br />
<pre><br />
// on PHP side:<br />
$this->notifyAllPlayers( "tableWindow", '', array(<br />
"id" => 'finalScoring',<br />
"title" => clienttranslate("Title of the scoring dialog"),<br />
"table" => $table<br />
) ); <br />
</pre><br />
<br />
The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.<br />
<br />
Example: display an 3x3 array of strings<br />
<pre><br />
$table = array(<br />
array( "one", "two", "three" ), // This is my first line<br />
array( "four", "five", "six" ), // This is my second line<br />
array( "seven", "height", "nine" ) // This is my third line<br />
);<br />
</pre><br />
<br />
As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:<br />
<pre><br />
$table = array(<br />
array( "one", "two", array( "str" => clienttranslate("a string with an ${argument}"), "args" => array( 'argument' => 'argument_value' ) ) ),<br />
array( "four", "five", "six" ), <br />
array( "seven", "height", "nine" )<br />
);<br />
</pre><br />
<br />
This is especially useful when you want to display player names with colors. Example from "Hearts":<br />
<pre><br />
$firstRow = array( '' );<br />
foreach( $players as $player_id => $player )<br />
{<br />
$firstRow[] = array( 'str' => '${player_name}',<br />
'args' => array( 'player_name' => $player['player_name'] ),<br />
'type' => 'header'<br />
);<br />
}<br />
$table[] = $firstRow;<br />
</pre><br />
<br />
You can also use three extra attributes in the parameter array for the notification:<br />
<br />
<pre><br />
$this->notifyAllPlayers( "tableWindow", '', array(<br />
"id" => 'finalScoring',<br />
"title" => clienttranslate("Title of the scoring dialog"),<br />
"table" => $table,<br />
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),<br />
'args' => array( 'number' => 3 ),<br />
),<br />
"footer" => '<div>Some footer</div>',<br />
"closing" => clienttranslate( "Closing button label" )<br />
) ); <br />
</pre><br />
<br />
*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors). <br />
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)<br />
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).<br />
<br />
=== Scoring animated display ===<br />
<br />
Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.<br />
You can do it with:<br />
<br />
<pre><br />
this.displayScoring( anchor_id, color, score, duration, offset_x, offset_y );<br />
</pre><br />
<br />
'''anchor_id''': ID of the element to place the animated score onto (without the '#') <br />
<br />
'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.<br />
<br />
'''score''': numeric score to display, prefixed by a '+' or '-'<br />
<br />
'''duration''': animation duration in milliseconds<br />
<br />
'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation. Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.<br />
<br />
<br />
Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.<br />
<br />
=== Speech bubble ===<br />
<br />
For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.<br />
This is done with:<br />
<br />
<pre><br />
this.showBubble(anchor_id, text, delay, duration, custom_class)<br />
</pre><br />
<br />
text - what to put in bubble, can be html actually not just text<br />
<br />
delay - in milliseconds is optional (default 0)<br />
<br />
duration - in milliseconds is optional (default 3000)<br />
<br />
custom_class - extra class to add to bubble is optional, if you need to override the default bubble style<br />
<br />
'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.<br />
<br />
Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.<br />
<br />
== Update players score ==<br />
<br />
The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the <gamename>.js setup() function. However this score must be updated as the game progresses through player notifications (notifs).<br />
<br />
<br />
Increase a player score (with a positive or negative number):<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].incValue( score_delta );<br />
</pre><br />
<br />
Set a player score to a specific value:<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].setValue( new_score );<br />
</pre><br />
<br />
Set a player score to a specific value with animation :<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].toValue( new_score );<br />
</pre><br />
<br />
Typical usage would be (that will process 'score' notification):<br />
<pre><br />
setupNotifications : function() {<br />
...<br />
dojo.subscribe('score', this, "notif_score");<br />
},<br />
notif_score: function(notif) {<br />
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);<br />
},<br />
</pre><br />
<br />
== Players panels ==<br />
<br />
=== Adding stuff to player's panel ===<br />
<br />
At first, create a new "JS template" string in your template (tpl) file:<br />
<br />
(from Gomoku example)<br />
<pre><br />
var jstpl_player_board = '\<div class="cp_board">\<br />
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\<br />
</div>';<br />
</pre><br />
<br />
Then, you add this piece of code in your JS file to add this template to each player panel:<br />
<br />
<pre><br />
// Setting up player boards<br />
for( var player_id in gamedatas.players )<br />
{<br />
var player = gamedatas.players[player_id];<br />
<br />
// Setting up players boards if needed<br />
var player_board_div = $('player_board_'+player_id);<br />
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );<br />
}<br />
</pre><br />
<br />
(Note: the code above is of course from your "setup" function in your Javascript).<br />
<br />
Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".<br />
<br />
=== Player's panel disabling/enabling ===<br />
<br />
'''this.disablePlayerPanel( player_id )'''<br />
<br />
Disable given player panel (the panel background become gray).<br />
<br />
Usually, this is used to signal that this played passes, or will be inactive during a while.<br />
<br />
Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.<br />
<br />
'''this.enablePlayerPanel( player_id )'''<br />
<br />
Enable a player panel that has been disabled before.<br />
<br />
'''this.enableAllPlayerPanels()'''<br />
<br />
Enable all player panels that has been disabled before.<br />
<br />
== Image loading ==<br />
<br />
See also [[Game_art:_img_directory]].<br />
<br />
'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.<br />
<br />
'''dontPreloadImage( image_file_name )'''<br />
<br />
Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.<br />
<br />
Example of use:<br />
<pre><br />
this.dontPreloadImage( 'cards.png' );<br />
</pre><br />
<br />
This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.<br />
<br />
Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.<br />
<pre><br />
// By default, do not preload anything<br />
this.dontPreloadImage( 'cards.png' );<br />
this.dontPreloadImage( 'clan1.png' );<br />
this.dontPreloadImage( 'clan2.png' );<br />
this.dontPreloadImage( 'clan3.png' );<br />
this.dontPreloadImage( 'clan4.png' );<br />
this.dontPreloadImage( 'clan5.png' );<br />
this.dontPreloadImage( 'clan6.png' );<br />
this.dontPreloadImage( 'clan7.png' );<br />
this.dontPreloadImage( 'clan8.png' );<br />
this.dontPreloadImage( 'clan9.png' );<br />
this.dontPreloadImage( 'clan10.png' );<br />
var to_preload = [];<br />
for( i in this.gamedatas.clans )<br />
{<br />
var clan_id = this.gamedatas.clans[i];<br />
to_preload.push( 'clan'+clan_id+'.png' );<br />
}<br />
if( to_preload.length == 5 )<br />
{<br />
this.ensureSpecificGameImageLoading( to_preload );<br />
}<br />
</pre><br />
<br />
'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.<br />
<br />
== Other useful stuff ==<br />
<br />
<br />
'''dojo.hitch'''<br />
<br />
With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.<br />
<br />
Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:<br />
<br />
<pre><br />
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {<br />
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );<br />
} ) ); <br />
</pre><br />
<br />
In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.<br />
<br />
NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this<br />
<pre><br />
this.confirmationDialog( _('Are you sure you want to make this?'), () => {<br />
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, (result) => {} );<br />
} ); <br />
</pre><br />
<br />
; updateCounters(counters)<br />
: Useful for updating game counters in the player panel (such as resources). <br />
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]<br />
: All counters must be referenced in this.gamedatas.counters and will be updated.<br />
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.<br />
<br />
<br />
;'''onScreenWidthChange()'''<br />
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.<br />
<br />
<br />
;'''updatePageTitle()'''<br />
:This function allows to update the current page title and turn description according to the game state. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before :calling the function, it allows to update the turn description without changing state.<br />
<br />
Example from Terra Mystica:<br />
<pre><br />
onClickFavorTile: function( evt ) {<br />
...<br />
if ( ... ) {<br />
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');<br />
this.updatePageTitle();<br />
this.removeActionButtons();<br />
this.addActionButton( ... );<br />
...<br />
return;<br />
}<br />
...<br />
<br />
}<br />
</pre><br />
<br />
== BGA GUI components ==<br />
<br />
BGA framework provides some useful ready-to-use components for the game interface:<br />
<br />
[[Studio#BGA_Studio_game_components_reference]]<br />
<br />
Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.<br />
<br />
Example if you are using "ebg.stock":<br />
<pre><br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter",<br />
"ebg/stock" /// <=== we are using ebg.stock module<br />
],<br />
</pre><br />
<br />
== BGA Buttons ==<br />
<br />
<br />
'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''<br />
<br />
You can use this method to add an action button in the main action status bar.<br />
<br />
Arguments:<br />
* id: an element ID that should be unique in your HTML DOM document.<br />
* label: the text of the button. Should be translatable (use _() function).<br />
* method: the name of your method that must be triggered when the player clicks on this button.<br />
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.<br />
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.<br />
* color: could be '''blue''' (default), '''red''' or '''gray'''.<br />
<br />
You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hearts example):<br />
<br />
<pre><br />
onUpdateActionButtons: function( stateName, args ) {<br />
<br />
if (this.isCurrentPlayerActive()) { <br />
switch( stateName ) {<br />
case 'giveCards':<br />
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' ); <br />
break;<br />
}<br />
}<br />
}, <br />
</pre><br />
<br />
In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.<br />
<br />
Example using blinking red button:<br />
<pre><br />
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red'); <br />
</pre><br />
<br />
Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''', <br />
if you don't like it you have to change css display value<br />
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)<br />
<br />
<br />
'''buttons with images'''<br />
<br />
You can use the same method, but add extra class to a button to disable the padding and style it, i.e.<br />
<pre><br />
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray'); <br />
dojo.addClass('button_brick','bgaimagebutton');<br />
</pre><br />
<br />
where<br />
<br />
<pre><br />
.bgaimagebutton {<br />
padding: 0px 12px;<br />
min-height: 28px;<br />
border: none;<br />
}<br />
</pre><br />
<br />
If you use this a lot, you can define a helper function, i.e.<br />
<pre><br />
/**<br />
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player<br />
* need to make a choice of resources or tokens.<br />
*/<br />
addImageActionButton: function(id, div, handler, bcolor, tooltip) {<br />
if (typeof bcolor == "undefined") {<br />
bcolor = "gray";<br />
}<br />
// this will actually make a transparent button id color = gray<br />
this.addActionButton(id, div, handler, '', false, bcolor);<br />
// remove boarder, for images it better without<br />
dojo.style(id, "border", "none");<br />
// but add shadow style (box-shadow, see css)<br />
dojo.addClass(id, "shadow bgaimagebutton");<br />
// you can also add addition styles, such as background<br />
if (tooltip) {<br />
dojo.attr(id, "title", tooltip);<br />
}<br />
return $(id);<br />
},<br />
</pre><br />
<br />
'''buttons outside of action bar'''<br />
<br />
You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.<br />
<br />
'''Examples:'''<br />
<br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a><br />
</pre><br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a><br />
</pre><br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a><br />
</pre><br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a><br />
</pre><br />
<br />
<br />
'''Note''': To see it in action, check out ''Coloretto''.<br />
<br />
Note: You can also create button using addActionButton() method, then move anywhere<br />
<pre><br />
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red'); <br />
dojo.place('commit_button','player_board');<br />
</pre><br />
<br />
'''Disabling:'''<br />
You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.<br />
For example in the '''onUpdateActionButtons''' : <br />
<pre>this.addActionButton( 'play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton', null, false, 'blue' ); //Create a blue button<br />
if (Condition == true)<br />
{<br />
dojo.addClass( 'play_button_id', 'disabled');//disable the button<br />
}</pre><br />
<br />
<br />
''' Handler with arguments '''<br />
<br />
If you want to call the handled with arguments, you can use arrow functions, like this:<br />
<pre><br />
this.addActionButton( 'commit_button', _('Confirm'), () => onConfirm(selectedCardId), null, true, 'red'); <br />
</pre><br />
<br />
== Sounds ==<br />
<br />
Add a custom sound and make it load with your interface:<br />
<br />
Add this in your template (.tpl) file:<br />
<pre><br />
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio><br />
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio><br />
</pre><br />
<br />
Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.<br />
<br />
Play the sound (from your .js file):<br />
<br />
<pre><br />
playSound('<gamename>_<yoursoundname>'); <br />
</pre><br />
<br />
<br />
Disable the standard "move" sound for this move (to replace it with your custom sound):<br />
<br />
Add this to your notification handler:<br />
<br />
<pre><br />
this.disableNextMoveSound();<br />
</pre><br />
<br />
Note: it only disable the sound for the next move.<br />
<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_interface_logic:_yourgamename.js&diff=13526
Game interface logic: yourgamename.js
2022-06-09T12:54:22Z
<p>Een: /* this.ajaxcall(url, parameters, obj_callback, callback, callback_error, ajax_method) */ mention of breaking replays/tutorials</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the main file for your game interface. Here you will define:<br />
<br />
* Which actions on the page will generate calls to the server.<br />
* What happens when you get a notification for a change from the server and how it will show in the browser. <br />
<br />
<br />
__TOC__<br />
<br />
== File structure ==<br />
<br />
The details of how the file is structured are described below with comments on the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* '''constructor''': here you can define global variables for your whole interface.<br />
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.<br />
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.<br />
* '''onLeavingState''': this method is called when leaving a game state.<br />
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.<br />
* ''(utility methods)'': this is where you can define your utility methods.<br />
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).<br />
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.<br />
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.<br />
<br />
<br />
More details:<br />
<br />
;setup(gamedatas) <br />
This method must set up the game user interface according to current game situation specified in parameters.<br />
The method is called each time the game interface is displayed to a player, ie:<br />
<br />
- when the game starts<br />
<br />
- when a player refreshes the game page (F5)<br />
<br />
"gamedatas" argument contains all datas retrieved by your "getAllDatas" PHP method.<br />
<br />
;onEnteringState(stateName, args)<br />
This method is called each time we are entering into a new game state.<br />
You can use this method to perform some user interface changes at this moment.<br />
To access state arguments passed via calling arg* method use args.args.<br />
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.<br />
<br />
'''Warning''': for multipleactiveplayer states:<br />
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/unactive status.<br />
If you are doing initialization of some structure which do not depend on active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator) <br />
for the main switch in that method.<br />
<br />
See more details in [[Your_game_state_machine:_states.inc.php#Diffrence_between_Single_active_and_Multi_active_states]]<br />
<br />
;onLeavingState(stateName)<br />
This method is called each time we are leaving a game state.<br />
You can use this method to perform some user interface changes at this moment (i.e. cleanup).<br />
<br />
;onUpdateActionButtons(stateName, args)<br />
In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.<br />
To access state arguments passed via calling arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.<br />
This method is called when active or multiactive player changes. In classic "activePlayer" state this method is called before the onEnteringState state.<br />
In multipleactiveplayer state it is a mess. The sequencing of calls would depends on either you get into that state from transitions OR from reloading the whole game (i.e. F5).<br />
<br />
See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]<br />
<br />
== General tips ==<br />
<br />
; this.player_id<br />
: ID of the player on whose browser the code is running.<br />
<br />
; this.isSpectator<br />
: Flag set to true if the user at the table is a spectator (not a player).<br />
: Note: This is a variable, not a function.<br />
: Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].<br />
<br />
; this.gamedatas<br />
: Contains the initial set of data to init the game, created at game start or by game refresh (F5).<br />
: You can update it as needed to keep an up-to-date reference of the game on the client side if you need it. (Most of the time this is unnecessary).<br />
: ''Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the table administrator to store data.''<br />
: ''Updating and using it after initialization might break some features relying on it.''<br />
<br />
; this.isCurrentPlayerActive()<br />
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.<br />
<br />
; this.getActivePlayerId()<br />
: Return the ID of the active player, or null if we are not in an "activeplayer" type state.<br />
<br />
; this.getActivePlayers()<br />
: Return an array with the IDs of players who are currently active (or an empty array if there are none).<br />
<br />
; this.bRealtime<br />
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.<br />
<br />
; g_replayFrom<br />
: Global contains reply number in live game, it is set to undefined (i.e. not set) when it is not a reply mode, so consequentially the good check is '''g_replayFrom !== undefined''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "reply from this move" in the log)<br />
<br />
; g_archive_mode<br />
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)<br />
<br />
; this.instantaneousMode<br />
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)<br />
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.<br />
<br />
; g_tutorialwritten<br />
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.<br />
{<br />
author: "91577332",<br />
id: "576",<br />
mode: "view"<br />
status: "alpha"<br />
version_override: null<br />
viewer_id: "84554161"<br />
}<br />
<br />
You may consider making a function like this, to detect if the game is in a read-only state:<br />
<br />
// Returns true for spectators, instant replay (during game), archive mode (after game end)<br />
isReadOnly: function () {<br />
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;<br />
}<br />
<br />
== Dojo framework ==<br />
<br />
BGA uses the [http://dojotoolkit.org/ Dojo Javascript framework].<br />
<br />
The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.<br />
<br />
To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.<br />
<br />
== Javascript minimization (after July 2020) ==<br />
<br />
For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).<br />
<br />
NB: it has been reported that there is an issue with this minifier and percentage values for opacity.<br />
<br />
== Accessing and manipulating the DOM ==<br />
<br />
'''$('some_html_element_id')'''<br />
<br />
The $() function is used to get an HTML element using its "id" attribute.<br />
<br />
Example 1: modify the content of a "span" element:<br />
<br />
<pre><br />
In your HTML code:<br />
<span id="a_value_in_the_game_interface">1234</span><br />
<br />
In your Javascript code:<br />
$('a_value_in_the_game_interface').innerHTML = "9999";<br />
</pre><br />
<br />
Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.<br />
Note²: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e. <br />
<pre><br />
foo: function(card) {<br />
card = $(card); // now its node, no need to write if (typeof card === 'string') ...<br />
// but its good idea to check for null here<br />
...<br />
}<br />
</pre><br />
<br />
<br />
'''dojo.style'''<br />
<br />
With dojo.style you can modify the CSS property of any HTML element in your interface.<br />
<br />
Examples:<br />
<br />
<pre><br />
// Make an element disappear<br />
dojo.style( 'my_element', 'display', 'none' );<br />
<br />
// Give an element a 2px border<br />
dojo.style( 'my_element', 'borderWidth', '2px' );<br />
<br />
// Change the background position of an element<br />
// (very practical when you are using CSS sprites to transform an element to another)<br />
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );<br />
</pre><br />
<br />
Note: you must always use dojo.style to modify the CSS properties of HTML elements.<br />
<br />
Note²: if you have to modify several CSS properties of an element, or if you have a complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).<br />
<br />
'''Vanila JS style'''<br />
$('my_element').style.display='none'; // set<br />
var display = $('my_element').style.display; // get<br />
$('my_element').style.removeProperty('display'); // remove<br />
<br />
'''dojo.addClass''', '''dojo.removeClass''', '''dojo.hasClass''', '''dojo.toggleClass'''<br />
<br />
In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications manually).<br />
<br />
Advantages are:<br />
* All your CSS stuff remains in your CSS file.<br />
* You can add/remove a list of CSS modifications with a simple function and without error.<br />
* You can test whether you applied the CSS to an element with the '''dojo.hasClass''' method.<br />
<br />
Example from ''Reversi'':<br />
<br />
<pre><br />
// We add "possibleMove" to an element<br />
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );<br />
<br />
// In our CSS file, the class is defined as:<br />
.possibleMove {<br />
background-color: white;<br />
opacity: 0.2;<br />
filter:alpha(opacity=20); /* For IE8 and earlier */ <br />
cursor: pointer; <br />
}<br />
<br />
// So we've applied 4 CSS property changes in one line of code.<br />
<br />
// ... and when we need to check if a square is a possible move on the client side:<br />
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )<br />
{ ... }<br />
<br />
// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );<br />
</pre><br />
<br />
Conclusion: We encourage you to use '''dojo.addClass''', '''dojo.removeClass''' and '''dojo.hasClass''' to make your life easier :)<br />
<br />
'''dojo.attr'''<br />
<br />
With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.<br />
<br />
Exemple:<br />
<pre><br />
// Get the title of a node<br />
var title = dojo.attr( id, 'title' );<br />
// Change the height of a node<br />
dojo.attr( 'img_growing_tree', 'height', 100 );<br />
</pre><br />
<br />
'''Vanila JS attr'''<br />
<br />
$(token).id=new_id; // set attr for "id"<br />
var id = $(token).id; // get<br />
<br />
<br />
'''dojo.query'''<br />
<br />
With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.<br />
<br />
Example:<br />
<pre><br />
// All elements with class "possibleMove":<br />
var elements = dojo.query( '.possibleMove' );<br />
<br />
// Count number of tokens (i.e., elements of class "token") on the board (i.e., the element with id "board"):<br />
dojo.query( '#board .token' ).length;<br />
</pre><br />
<br />
But what is really cool with dojo.query is that you can combine it with almost all methods above.<br />
<br />
Examples:<br />
<pre><br />
// Trigger a method when the mouse enter in any element with class "meeple":<br />
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );<br />
<br />
// Hide all meeples who are on the board<br />
dojo.query( '#board .meeple' ).style( 'display', 'none' );<br />
</pre><br />
<br />
'''Vanila JS query'''<br />
<br />
var cards=document.querySelectorAll(".hand .card");// all cards in all hands<br />
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand<br />
var card=document.querySelector(".hand .card");// first card or null if none (super handy)<br />
<br />
'''dojo.place'''<br />
<br />
dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if you must insert HTML tags and not only values.<br />
<br />
<pre><br />
// Insert your HTML code as a child of a container element<br />
dojo.place( "<your html code>", "your_container_element_id" );<br />
<br />
// Replace the container element with your new html<br />
dojo.place( "<your html code>", "your_container_element_id", "replace" );<br />
<br />
</pre><br />
<br />
The third parameter of dojo.place can take various interesting values:<br />
<br />
"replace" : (see description above).<br />
<br />
"first" : Places the node as a child of the reference node. The node is placed as the first child.<br />
<br />
"last" (default) : Places the node as a child of the reference node. The node is placed as the last child.<br />
<br />
"before" : places the node right before the reference node.<br />
<br />
"after" : places the node right after the reference node.<br />
<br />
"only" : replaces all children of the reference node with the node.<br />
<br />
positive integer: This parameter can be a positive integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child. <br />
<br />
See also full doc on dojo.place: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]<br />
<br />
Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".<br />
<br />
But you can also relocate elements like that. Note: it won't animate if you do that.<br />
<br />
<br />
'''dojo.empty'''<br />
<br />
Remove all children of the node element<br />
dojo.empty('my_hand');<br />
<br />
'''dojo.destroy'''<br />
<br />
Remove the element<br />
<br />
dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode<br />
<br />
'''dojo.create'''<br />
<br />
Create element<br />
<br />
dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"<br />
<br />
'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''<br />
<br />
Same as dojo.style(), but for all the nodes set with the specified cssClassName<br />
<br />
'''this.format_block'''<br />
This bga function that takes global var from template file and substitute variables, typical use would be<br />
<br />
var player = gamedatas.players[player_id];<br />
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file <br />
<br />
'''this.format_string'''<br />
This bga function just substitute variables in a string, i.e.<br />
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );<br />
<br />
'''this.format_string_recursive'''<br />
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.<br />
<br />
=== Animations ===<br />
<br />
'''Dojo Animations'''<br />
<br />
BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).<br />
<br />
However, most of the time, you can just use methods below, which are built on top of Dojo Animation.<br />
<br />
Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.<br />
<br />
Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.<br />
<br />
<br />
'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''<br />
<br />
You can use slideToObject to "slide" an element to a target position.<br />
<br />
Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.<br />
<br />
The parameters are:<br />
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.<br />
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.<br />
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.<br />
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.<br />
<br />
BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.<br />
<br />
Example:<br />
<pre><br />
this.slideToObject( "some_token", "some_place_on_board" ).play();<br />
</pre><br />
<br />
<br />
'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''<br />
<br />
This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".<br />
<br />
Example: slide a token to some place on the board, 10 pixels to the bottom:<br />
<pre><br />
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();<br />
</pre><br />
<br />
'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''<br />
<br />
This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.<br />
<br />
slideTemporaryObject does all of this for you:<br />
* mobile_obj_html is a piece of HTML code that represent the object to slide.<br />
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.<br />
* from is the ID of the origin of the slide.<br />
* to is the ID of the target of the slide.<br />
* duration/delay works exactly like in "slideToObject"<br />
<br />
Example:<br />
<pre><br />
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' ).play();<br />
</pre><br />
<br />
'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''<br />
<br />
This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.<br />
<br />
It works the same as this.slideToObject and takes the same arguments, but it starts the animation. <br />
<br />
Example:<br />
<pre><br />
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );<br />
</pre><br />
<br />
'''this.fadeOutAndDestroy( node, duration, delay )'''<br />
<br />
This function fade out the target HTML node, then destroy it. Its starts the animation.<br />
<br />
Example:<br />
<pre><br />
this.fadeOutAndDestroy( "a_card_that_must_disappear" );<br />
</pre><br />
<br />
CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.<br />
<br />
'''Rotating elements'''<br />
<br />
You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.<br />
<br />
This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.<br />
<br />
IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):<br />
<br />
<pre><br />
var transform;<br />
dojo.forEach(<br />
['transform', 'WebkitTransform', 'msTransform',<br />
'MozTransform', 'OTransform'],<br />
function (name) {<br />
if (typeof dojo.body().style[name] != 'undefined') {<br />
transform = name;<br />
}<br />
});<br />
// ... and then use "transform" as the name of your CSS property for rotation<br />
</pre><br />
<br />
Note: This wiki was probably written 10 years ago - now all modern broser support 'transform' so just ignore this and use transform.<br />
<br />
<br />
'''Animation Callbacks'''<br />
<br />
If you wish to run some code only after an animation has completed you can do this by linking a callback method.<br />
<br />
<pre><br />
var animation_id = this.slideToObject( mobile_obj, target_obj, duration, delay );<br />
dojo.connect(animation_id, 'onEnd', dojo.hitch(this, 'callback_function', parameters));<br />
animation_id.play();<br />
<br />
…<br />
<br />
callback_function: function(params) {<br />
// this will be called after the animation ends<br />
},<br />
</pre><br />
<br />
If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).<br />
<br />
=== Moving elements ===<br />
<br />
'''this.placeOnObject( mobile_obj, target_obj )'''<br />
<br />
placeOnObject works exactly like "slideToObject", except that the effect is immediate and that it is centered.<br />
<br />
This is not really an animation, but placeOnObject is frequently used before starting an animation.<br />
<br />
Example:<br />
<pre><br />
// (We just created an object "my_new_token")<br />
<br />
// Place the new token on current player board<br />
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );<br />
<br />
// Then slide it to its position on the board<br />
this.slideToObject( "my_new_token", "a_place_on_board" ).play();<br />
</pre><br />
<br />
'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''<br />
<br />
This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, the center of "mobile_obj" will be placed to the specified x,y position relatively to the center of "target_obj".<br />
<br />
''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.<br />
<br />
'''this.attachToNewParent( mobile_obj, target_obj )'''<br />
<br />
With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of <br />
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.<br />
<br />
Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.<br />
<br />
Why using this method?<br />
<br />
Changing the HTML parent of an element can be useful for the following reasons:<br />
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.<br />
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.<br />
<br />
CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).<br />
<br />
== Players input ==<br />
<br />
<br />
==== dojo.connect(element, event, context, method) ====<br />
<br />
Used to associate a player event with one of your notification methods.<br />
<br />
Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):<br />
<pre><br />
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );<br />
</pre><br />
Same idea but base on query (i.e. all element of 'pet' class)<br />
dojo.query(".pet").connect('onclick', this, 'onPet');<br />
<br />
Note: the methods described here are the only correct ways to associate a player input event to your code, and you should not use anything else.<br />
<br />
==== this.connect(element, event, handler) ====<br />
<br />
Used to associate a player event with one of your notification methods.<br />
<br />
this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );<br />
<br />
Or you can use an in-place handler<br />
<br />
this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );<br />
<br />
Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.<br />
<br />
<br />
==== this.connectClass(cssClassName, event, handler) ====<br />
<br />
Same as connect(), but for all the nodes set with the specified cssClassName.<br />
<pre><br />
this.connectClass('pet', 'onclick', 'onPet');<br />
</pre><br />
<br />
====this.disconnect(element, event)====<br />
<br />
Disconnect event handler (previously registered with this.connect or this.connectClass).<br />
<br />
this.disconnect( $('my_element'), 'onclick');<br />
<br />
Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.<br />
<br />
==== this.disconnectAll() ====<br />
<br />
Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)<br />
<br />
==== this.checkAction(action, nomessage) ====<br />
<br />
Check if player can do the specified action by taking into account:<br />
* current game state<br />
* interface locking (a player can't do any action if an action is already in progress)<br />
<br />
return true if action is authorized (i.e: the action is listed as a "possibleaction" in current game state).<br />
<br />
return false and display an error message if not authorized (display no message if nomessage parameter is true). <br />
The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".<br />
<br />
Example:<br />
<pre><br />
function onClickOnGameElement( evt ) {<br />
if( this.checkAction( "my_action" ) ) {<br />
// Do the action<br />
}<br />
}<br />
</pre><br />
<br />
==== this.checkPossibleActions(action, nomessage) ====<br />
<br />
* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account (bug or feature?)<br />
<br />
Check if player can do the specified action by taking into account:<br />
* current game state<br />
<br />
<br />
==== this.ajaxcall(url, parameters, obj_callback, callback, callback_error, ajax_method) ====<br />
<br />
This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features.<br />
<br />
* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"<br />
* parameters: an array of parameter to send to the game server. <br />
** Note that "lock: true" must always be specified in this list of parameters in order the interface can be locked during the server call.<br />
** Note: Restricted parameter names (please don't use them):<br />
*** "action"<br />
*** "module"<br />
*** "class"<br />
* obj_callback: must be set to "this".<br />
* callback: a function to trigger when the server returns and everything went fine (not used, as all data handling is done via notifications).<br />
* callback_error: (optional and rarely used) a function to trigger when the server returns an error. if no error this function is called with parameter value false.<br />
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.<br />
<br />
Usage:<br />
<pre><br />
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true, <br />
arg1: myarg1, <br />
arg2: myarg2, <br />
...<br />
}, this, function( result ) {<br />
// Do some stuff after a successful call<br />
// NB : usually not needed as changes must be handled by notifications<br />
// You should NOT modify the interface in a callback or it will most likely break the framework replays (or make it inaccurate)<br />
// You should NOT make another ajaxcall in a callback in order not to create race conditions<br />
} );<br />
</pre><br />
<br />
Note: to reduce the boilerplate code you can define your own wrapper, which will do checking, locking and allow to skip parameters, for example<br />
<pre><br />
ajaxcallwrapper: function(action, args, handler) {<br />
if (!args) {<br />
args = [];<br />
}<br />
args.lock = true;<br />
<br />
if (this.checkAction(action)) {<br />
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, this, (result) => { }, handler);<br />
}<br />
},<br />
</pre><br />
This can be called like this which is a lot more compact<br />
<pre><br />
this.ajaxcallwrapper('playDraw');<br />
this.ajaxcallwrapper('playMove', {card: id})<br />
</pre><br />
<br />
==== this.isInterfaceLocked() ====<br />
<br />
When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).<br />
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors.<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Notifications ==<br />
<br />
When something happens on the server side, your game interface Javascript logic received a notification.<br />
<br />
Here's how you can handle these notifications on the client side.<br />
<br />
=== Subscribe to notifications ===<br />
<br />
Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.<br />
<br />
Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):<br />
<br />
<pre><br />
// In setupNotifications method:<br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
</pre><br />
<br />
Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.<br />
<br />
Then, you have to define your "notif_playDisc" method:<br />
<br />
<pre><br />
notif_playDisc: function( notif )<br />
{<br />
// Remove current possible moves (makes the board more clear)<br />
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' ); <br />
<br />
this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );<br />
},<br />
</pre><br />
<br />
In a notification handler like our "notif_playDisc" method, you can access all notifications arguments with "notif.args".<br />
<br />
Example:<br />
<br />
PHP<br />
<br />
<pre><br />
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );<br />
</pre><br />
<br />
JavaScript<br />
<br />
<pre><br />
//You can access the "myArgument" like this:<br />
notif_myNotification: function( notif )<br />
{<br />
alert( "myArgument = " + notif.args.myArgument );<br />
}<br />
</pre><br />
<br />
=== The notification Object received by client ===<br />
<br />
When sending a notification on your PHP, the client side will receive an Object with the following attributes:<br />
<br />
* args : This is the arguments that you passed on your notification method on php<br />
* bIsTableMsg : Boolean, is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)<br />
* channelorig : information about table ID (formatted as : "/table/t[TABLE_NUMBER]")<br />
* gamenameorig : name of the game<br />
* log: the log information as written in PHP function<br />
* move_id : ID of the move associated with the notification<br />
* table_id : ID of the table<br />
* time : UNIX GMT time<br />
* type : name of the notification<br />
* uid : identifier of the notification<br />
<br />
'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''<br />
<br />
=== Synchronous notifications ===<br />
<br />
When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.<br />
<br />
However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, there are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.<br />
<br />
As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.<br />
<br />
Here's how we do this, right after our subscription:<br />
<pre><br />
dojo.subscribe( 'playDisc', this, "notif_playDisc" );<br />
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler<br />
</pre><br />
<br />
-----<br />
<br />
It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.<br />
<br />
For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.<br />
<br />
* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!<br />
<br />
<pre><br />
setupNotifications: function () {<br />
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );<br />
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic<br />
...<br />
},<br />
<br />
notif_cardPlayed: function (notif) {<br />
// MUST call setSynchronousDuration<br />
<br />
// Example 1: From notification args (PHP)<br />
this.notifqueue.setSynchronousDuration(notif.args.duration);<br />
...<br />
<br />
// Or, example 2: Match the duration to a Dojo animation<br />
var anim = dojo.fx.combine([<br />
...<br />
]);<br />
anim.play();<br />
this.notifqueue.setSynchronousDuration(anim.duration);<br />
},<br />
</pre><br />
<br />
=== WARNING: combining synchronous and ignored notifications ===<br />
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):<br />
<br />
<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre><br />
<br />
then you CANNOT do<br />
<br />
<pre>this.notifqueue.setSynchronous('myNotif');</pre><br />
<br />
as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.<br />
<br />
The workaround is to set a "dummy" time:<br />
<br />
<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre><br />
<br />
whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.<br />
<br />
<br />
=== Ignoring notifications ===<br />
Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.<br />
<br />
The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").<br />
<br />
In X.game.php<br />
<pre><br />
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [<br />
'player_id' => $playerId,<br />
'player_name' => $this->getActivePlayerName()<br />
]);<br />
<br />
$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [<br />
"type" => $card["type"],<br />
"cardName" => $this->getCardName($card["type"])<br />
]);<br />
</pre><br />
<br />
The problem with this approach is that the active player will receive two notifications:<br />
* Player1 received a card<br />
* You received Ace of Hearts<br />
<br />
Hence, notification ignoring. Similar to setting a synchronous notification above, you can set up a check whether a notification should be ignored:<br />
<pre><br />
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );<br />
</pre><br />
<br />
NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.<br />
<br />
'''setIgnoreNotificationCheck(notificationId, predicate)'''<br />
This method will set a check whether any of notifications of specific type should be ignored.<br />
<br />
The parameters are:<br />
* notificationId: before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored<br />
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored<br />
<br />
IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.<br />
<br />
IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should preserve it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].<br />
<br />
=== Pre-defined notification types ===<br />
<br />
'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.<br />
<br />
'''message''' - This defines notification that shows on players log and have no other effect (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)<br />
<br />
// You can call this on php side without doing anything on client side<br />
self::notifyAllPlayers( 'message', 'hello', [] );<br />
<br />
'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.<br />
<br />
<pre><br />
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds<br />
</pre><br />
<br />
== Tooltips ==<br />
<br />
'''this.addTooltip( nodeId, helpStringTranslated, actionStringTranslated, delay )'''<br />
<br />
Add a simple text tooltip to the DOM node.<br />
<br />
Specify 'helpStringTranslated' to display some information about "what is this game element?".<br />
Specify 'actionStringTranslated' to display some information about "what happens when I click on this element?".<br />
<br />
You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.<br />
<br />
When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.<br />
<br />
Parameter "delay" is optional. It is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browsers (see [[BGA_Studio_Guidelines|Guidelines]]).<br />
<br />
Example:<br />
<pre><br />
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );<br />
</pre><br />
<br />
Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique<br />
<br />
'''this.addTooltipHtml( nodeId, html, delay )'''<br />
<br />
Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).<br />
<br />
'''this.addTooltipToClass( cssClass, helpStringTranslated, actionStringTranslated, delay )'''<br />
<br />
Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.<br />
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );<br />
<br />
IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.<br />
<br />
'''this.addTooltipHtmlToClass( cssClass, html, delay )'''<br />
<br />
Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).<br />
<br />
IMPORTANT: all concerned nodes must exist and have IDs to get tooltips.<br />
<br />
'''this.removeTooltip( nodeId )'''<br />
<br />
Remove a tooltip from the DOM node with given id.<br />
<br />
'''force tooltip to open'''<br />
<br />
If you want to force tooltip to open in reaction to some other action, i.e. click you can do this<br />
<br />
this.tooltips[id].open(id)<br />
<br />
where id is the id of the tooltip node where tooltip was installed.<br />
<br />
== Dialogs, warning messages, confirmation dialogs, ... ==<br />
<br />
=== Warning messages ===<br />
<br />
Sometimes, there is something important that is happening in the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.<br />
<br />
Ex: someone fulfills one of the end of the game conditions, so this is the last turn.<br />
<br />
'''this.showMessage( msg, type )'''<br />
<br />
showMessage shows a message in a big rectangular area on the top of the screen of the current player.<br />
<br />
* "msg" is the string to display. It should be translated.<br />
* "type" can be set to "info", "error", or "only_to_log". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.<br />
<br />
Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.<br />
<br />
=== Confirmation dialog ===<br />
<br />
'''confirmationDialog( message, yesHandler, noHandler )'''<br />
<br />
<br />
When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.<br />
<br />
CAREFUL: the general guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.<br />
<br />
The situations where you should use a confirmation dialog are the following:<br />
* It must not happen very often during a game.<br />
* It must be linked to an action that can really "kill a game" if the player does not pay attention.<br />
* It must be something that can be done by mistake (ex: a link on the action status bar).<br />
<br />
How to display a confirmation dialog:<br />
<pre><br />
this.confirmationDialog(_('Are you sure you want to bake the pie?'), () => {<br />
this.bakeThePie();<br />
}); <br />
return; // nothing should be called or done after calling this, all action must be done in the handler <br />
</pre><br />
<br />
=== Multiple choice dialog ===<br />
You can use this dialog to give user a choice with small amount of options:<br />
<pre><br />
var keys = [1,5,10];<br />
this.multipleChoiceDialog(<br />
_('How many bugs to fix?'), keys, <br />
(choice) => {<br />
var bugchoice = keys[choice];<br />
console.log('dialog callback with '+bugchoice);<br />
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} );<br />
}<br />
);<br />
</pre><br />
<br />
=== Dialogs ===<br />
<br />
As a general rule, you shouldn't use dialogs windows.<br />
<br />
BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.<br />
<br />
Sometimes although, you need to display a dialog window. Here is how you do this:<br />
<br />
<br />
<br />
// Create the new dialog over the play zone. You should store the handler in a member variable to access it later<br />
this.myDlg = new ebg.popindialog();<br />
this.myDlg.create( 'myDialogUniqueId' );<br />
this.myDlg.setTitle( _("my dialog title to translate") );<br />
this.myDlg.setMaxWidth( 500 ); // Optional<br />
<br />
// Create the HTML of my dialog. <br />
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]<br />
var html = this.format_block( 'jstpl_myDialogTemplate', { <br />
arg1: myArg1,<br />
arg2: myArg2,<br />
...<br />
} ); <br />
<br />
// Show the dialog<br />
this.myDlg.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog<br />
this.myDlg.show();<br />
<br />
// Now that the dialog has been displayed, you can connect your method to some dialog elements<br />
// Example, if you have an "OK" button in the HTML of your dialog:<br />
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){<br />
evt.preventDefault();<br />
this.myDlg.destroy();<br />
} );<br />
<br />
If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:<br />
// Removes the default close icon<br />
this.myDlg.hideCloseIcon();<br />
<br />
// Replace the function call when it's clicked<br />
this.myDlg.replaceCloseCallback( function() { ... } );<br />
<br />
=== Scoring dialogs ===<br />
<br />
Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.<br />
<br />
Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.<br />
<br />
Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.<br />
<br />
Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":<br />
<pre><br />
// on PHP side:<br />
$this->notifyAllPlayers( "tableWindow", '', array(<br />
"id" => 'finalScoring',<br />
"title" => clienttranslate("Title of the scoring dialog"),<br />
"table" => $table<br />
) ); <br />
</pre><br />
<br />
The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.<br />
<br />
Example: display an 3x3 array of strings<br />
<pre><br />
$table = array(<br />
array( "one", "two", "three" ), // This is my first line<br />
array( "four", "five", "six" ), // This is my second line<br />
array( "seven", "height", "nine" ) // This is my third line<br />
);<br />
</pre><br />
<br />
As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:<br />
<pre><br />
$table = array(<br />
array( "one", "two", array( "str" => clienttranslate("a string with an ${argument}"), "args" => array( 'argument' => 'argument_value' ) ) ),<br />
array( "four", "five", "six" ), <br />
array( "seven", "height", "nine" )<br />
);<br />
</pre><br />
<br />
This is especially useful when you want to display player names with colors. Example from "Hearts":<br />
<pre><br />
$firstRow = array( '' );<br />
foreach( $players as $player_id => $player )<br />
{<br />
$firstRow[] = array( 'str' => '${player_name}',<br />
'args' => array( 'player_name' => $player['player_name'] ),<br />
'type' => 'header'<br />
);<br />
}<br />
$table[] = $firstRow;<br />
</pre><br />
<br />
You can also use three extra attributes in the parameter array for the notification:<br />
<br />
<pre><br />
$this->notifyAllPlayers( "tableWindow", '', array(<br />
"id" => 'finalScoring',<br />
"title" => clienttranslate("Title of the scoring dialog"),<br />
"table" => $table,<br />
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),<br />
'args' => array( 'number' => 3 ),<br />
),<br />
"footer" => '<div>Some footer</div>',<br />
"closing" => clienttranslate( "Closing button label" )<br />
) ); <br />
</pre><br />
<br />
*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors). <br />
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)<br />
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).<br />
<br />
=== Scoring animated display ===<br />
<br />
Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.<br />
You can do it with:<br />
<br />
<pre><br />
this.displayScoring( anchor_id, color, score, duration, offset_x, offset_y );<br />
</pre><br />
<br />
'''anchor_id''': ID of the element to place the animated score onto (without the '#') <br />
<br />
'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.<br />
<br />
'''score''': numeric score to display, prefixed by a '+' or '-'<br />
<br />
'''duration''': animation duration in milliseconds<br />
<br />
'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation. Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.<br />
<br />
<br />
Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.<br />
<br />
=== Speech bubble ===<br />
<br />
For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.<br />
This is done with:<br />
<br />
<pre><br />
this.showBubble(anchor_id, text, delay, duration, custom_class)<br />
</pre><br />
<br />
text - what to put in bubble, can be html actually not just text<br />
<br />
delay - in milliseconds is optional (default 0)<br />
<br />
duration - in milliseconds is optional (default 3000)<br />
<br />
custom_class - extra class to add to bubble is optional, if you need to override the default bubble style<br />
<br />
'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.<br />
<br />
Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.<br />
<br />
== Update players score ==<br />
<br />
The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the <gamename>.js setup() function. However this score must be updated as the game progresses through player notifications (notifs).<br />
<br />
<br />
Increase a player score (with a positive or negative number):<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].incValue( score_delta );<br />
</pre><br />
<br />
Set a player score to a specific value:<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].setValue( new_score );<br />
</pre><br />
<br />
Set a player score to a specific value with animation :<br />
<br />
<pre><br />
this.scoreCtrl[ player_id ].toValue( new_score );<br />
</pre><br />
<br />
Typical usage would be (that will process 'score' notification):<br />
<pre><br />
setupNotifications : function() {<br />
...<br />
dojo.subscribe('score', this, "notif_score");<br />
},<br />
notif_score: function(notif) {<br />
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);<br />
},<br />
</pre><br />
<br />
== Players panels ==<br />
<br />
=== Adding stuff to player's panel ===<br />
<br />
At first, create a new "JS template" string in your template (tpl) file:<br />
<br />
(from Gomoku example)<br />
<pre><br />
var jstpl_player_board = '\<div class="cp_board">\<br />
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\<br />
</div>';<br />
</pre><br />
<br />
Then, you add this piece of code in your JS file to add this template to each player panel:<br />
<br />
<pre><br />
// Setting up player boards<br />
for( var player_id in gamedatas.players )<br />
{<br />
var player = gamedatas.players[player_id];<br />
<br />
// Setting up players boards if needed<br />
var player_board_div = $('player_board_'+player_id);<br />
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );<br />
}<br />
</pre><br />
<br />
(Note: the code above is of course from your "setup" function in your Javascript).<br />
<br />
Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".<br />
<br />
=== Player's panel disabling/enabling ===<br />
<br />
'''this.disablePlayerPanel( player_id )'''<br />
<br />
Disable given player panel (the panel background become gray).<br />
<br />
Usually, this is used to signal that this played passes, or will be inactive during a while.<br />
<br />
Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.<br />
<br />
'''this.enablePlayerPanel( player_id )'''<br />
<br />
Enable a player panel that has been disabled before.<br />
<br />
'''this.enableAllPlayerPanels()'''<br />
<br />
Enable all player panels that has been disabled before.<br />
<br />
== Image loading ==<br />
<br />
See also [[Game_art:_img_directory]].<br />
<br />
'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.<br />
<br />
'''dontPreloadImage( image_file_name )'''<br />
<br />
Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.<br />
<br />
Example of use:<br />
<pre><br />
this.dontPreloadImage( 'cards.png' );<br />
</pre><br />
<br />
This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.<br />
<br />
Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.<br />
<pre><br />
// By default, do not preload anything<br />
this.dontPreloadImage( 'cards.png' );<br />
this.dontPreloadImage( 'clan1.png' );<br />
this.dontPreloadImage( 'clan2.png' );<br />
this.dontPreloadImage( 'clan3.png' );<br />
this.dontPreloadImage( 'clan4.png' );<br />
this.dontPreloadImage( 'clan5.png' );<br />
this.dontPreloadImage( 'clan6.png' );<br />
this.dontPreloadImage( 'clan7.png' );<br />
this.dontPreloadImage( 'clan8.png' );<br />
this.dontPreloadImage( 'clan9.png' );<br />
this.dontPreloadImage( 'clan10.png' );<br />
var to_preload = [];<br />
for( i in this.gamedatas.clans )<br />
{<br />
var clan_id = this.gamedatas.clans[i];<br />
to_preload.push( 'clan'+clan_id+'.png' );<br />
}<br />
if( to_preload.length == 5 )<br />
{<br />
this.ensureSpecificGameImageLoading( to_preload );<br />
}<br />
</pre><br />
<br />
'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.<br />
<br />
== Other useful stuff ==<br />
<br />
<br />
'''dojo.hitch'''<br />
<br />
With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.<br />
<br />
Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:<br />
<br />
<pre><br />
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {<br />
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );<br />
} ) ); <br />
</pre><br />
<br />
In the example above, using dojo.hitch, we ensure that the "this" object will be set when the callback is called.<br />
<br />
NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this<br />
<pre><br />
this.confirmationDialog( _('Are you sure you want to make this?'), () => {<br />
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, (result) => {} );<br />
} ); <br />
</pre><br />
<br />
; updateCounters(counters)<br />
: Useful for updating game counters in the player panel (such as resources). <br />
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]<br />
: All counters must be referenced in this.gamedatas.counters and will be updated.<br />
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.<br />
<br />
<br />
;'''onScreenWidthChange()'''<br />
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.<br />
<br />
<br />
;'''updatePageTitle()'''<br />
:This function allows to update the current page title and turn description according to the game state. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before :calling the function, it allows to update the turn description without changing state.<br />
<br />
Example from Terra Mystica:<br />
<pre><br />
onClickFavorTile: function( evt ) {<br />
...<br />
if ( ... ) {<br />
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');<br />
this.updatePageTitle();<br />
this.removeActionButtons();<br />
this.addActionButton( ... );<br />
...<br />
return;<br />
}<br />
...<br />
<br />
}<br />
</pre><br />
<br />
== BGA GUI components ==<br />
<br />
BGA framework provides some useful ready-to-use components for the game interface:<br />
<br />
[[Studio#BGA_Studio_game_components_reference]]<br />
<br />
Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.<br />
<br />
Example if you are using "ebg.stock":<br />
<pre><br />
define([<br />
"dojo","dojo/_base/declare",<br />
"ebg/core/gamegui",<br />
"ebg/counter",<br />
"ebg/stock" /// <=== we are using ebg.stock module<br />
],<br />
</pre><br />
<br />
== BGA Buttons ==<br />
<br />
<br />
'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''<br />
<br />
You can use this method to add an action button in the main action status bar.<br />
<br />
Arguments:<br />
* id: an element ID that should be unique in your HTML DOM document.<br />
* label: the text of the button. Should be translatable (use _() function).<br />
* method: the name of your method that must be triggered when the player clicks on this button.<br />
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.<br />
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.<br />
* color: could be '''blue''' (default), '''red''' or '''gray'''.<br />
<br />
You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hearts example):<br />
<br />
<pre><br />
onUpdateActionButtons: function( stateName, args ) {<br />
<br />
if (this.isCurrentPlayerActive()) { <br />
switch( stateName ) {<br />
case 'giveCards':<br />
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' ); <br />
break;<br />
}<br />
}<br />
}, <br />
</pre><br />
<br />
In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.<br />
<br />
Example using blinking red button:<br />
<pre><br />
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red'); <br />
</pre><br />
<br />
Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''', <br />
if you don't like it you have to change css display value<br />
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)<br />
<br />
<br />
'''buttons with images'''<br />
<br />
You can use the same method, but add extra class to a button to disable the padding and style it, i.e.<br />
<pre><br />
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray'); <br />
dojo.addClass('button_brick','bgaimagebutton');<br />
</pre><br />
<br />
where<br />
<br />
<pre><br />
.bgaimagebutton {<br />
padding: 0px 12px;<br />
min-height: 28px;<br />
border: none;<br />
}<br />
</pre><br />
<br />
If you use this a lot, you can define a helper function, i.e.<br />
<pre><br />
/**<br />
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player<br />
* need to make a choice of resources or tokens.<br />
*/<br />
addImageActionButton: function(id, div, handler, bcolor, tooltip) {<br />
if (typeof bcolor == "undefined") {<br />
bcolor = "gray";<br />
}<br />
// this will actually make a transparent button id color = gray<br />
this.addActionButton(id, div, handler, '', false, bcolor);<br />
// remove boarder, for images it better without<br />
dojo.style(id, "border", "none");<br />
// but add shadow style (box-shadow, see css)<br />
dojo.addClass(id, "shadow bgaimagebutton");<br />
// you can also add addition styles, such as background<br />
if (tooltip) {<br />
dojo.attr(id, "title", tooltip);<br />
}<br />
return $(id);<br />
},<br />
</pre><br />
<br />
'''buttons outside of action bar'''<br />
<br />
You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.<br />
<br />
'''Examples:'''<br />
<br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a><br />
</pre><br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a><br />
</pre><br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a><br />
</pre><br />
<pre><br />
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a><br />
</pre><br />
<br />
<br />
'''Note''': To see it in action, check out ''Coloretto''.<br />
<br />
Note: You can also create button using addActionButton() method, then move anywhere<br />
<pre><br />
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red'); <br />
dojo.place('commit_button','player_board');<br />
</pre><br />
<br />
'''Disabling:'''<br />
You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.<br />
For example in the '''onUpdateActionButtons''' : <br />
<pre>this.addActionButton( 'play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton', null, false, 'blue' ); //Create a blue button<br />
if (Condition == true)<br />
{<br />
dojo.addClass( 'play_button_id', 'disabled');//disable the button<br />
}</pre><br />
<br />
<br />
''' Handler with arguments '''<br />
<br />
If you want to call the handled with arguments, you can use arrow functions, like this:<br />
<pre><br />
this.addActionButton( 'commit_button', _('Confirm'), () => onConfirm(selectedCardId), null, true, 'red'); <br />
</pre><br />
<br />
== Sounds ==<br />
<br />
Add a custom sound and make it load with your interface:<br />
<br />
Add this in your template (.tpl) file:<br />
<pre><br />
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio><br />
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio><br />
</pre><br />
<br />
Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.<br />
<br />
Play the sound (from your .js file):<br />
<br />
<pre><br />
playSound('<gamename>_<yoursoundname>'); <br />
</pre><br />
<br />
<br />
Disable the standard "move" sound for this move (to replace it with your custom sound):<br />
<br />
Add this to your notification handler:<br />
<br />
<pre><br />
this.disableNextMoveSound();<br />
</pre><br />
<br />
Note: it only disable the sound for the next move.<br />
<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Pre-release_checklist&diff=13488
Pre-release checklist
2022-06-08T15:50:39Z
<p>Een: Special testing, mention the replay</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
If you think your game is ready to be reviewed by by BGA admins and/or Publisher (aka go to Alpha stage) please consult this checklist first<br />
<br />
=== Move from Dev to Alpha ===<br />
# ''' License '''<br />
## BGA must have a license for the game for a project to be moved to production, even to alpha. If you don't have license yet you can continue checking other stuff from the list below, but at the end it cannot be moved until license situation is cleared.<br />
# ''' Metadata and graphics '''<br />
## [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game. That includes game tags. <b>Important!!!</b> tags are only read during the first deploy.<br />
## Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.<br />
## You have added a game_banner.jpg and some game_displayX.jpg images to make the game page pretty (NB: on the studio, you have to create a build for these images to appear on the studio game page)<br />
## There are no images in the img directory that are not needed anymore<br />
## Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])<br />
## Each image should not exceed 4Mb<br />
## Total size should not exceed 10Mb, image compression should be used otherwise (it also helps a lot to re-encode images as indexed palette vs RBG). If you have legitimate reason to have more than 10Mb (i.e. expansions), you have to make a note of that when requesting move to alpha<br />
## If you use extra fonts, they should be freeware (please include a .txt with the licence information)<br />
# ''' Server side '''<br />
## When giving their turn to a player, you give them some extra time with the giveExtraTime() function<br />
## Game progression is implemented (getGameProgression() in php)<br />
## Zombie turn is implemented (zombieTurn() in php). Note: it can only be tested if you explicitly click on the quit button to create a zombie. If you are expelled it does not generated a Zombie.<br />
## You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)<br />
## Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)<br />
## You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data<br />
## Database: make sure you do not programmatically manage transactions or call queries that change database schema or even TRUNCATE (queries that would cause implicit commit) during normal game opearations<br />
## Database: make sure you DB schema would be sufficient to complete the game and good enough for possible expantions, changing db schema schema after the release even in alpha is very challenging (it is possible but much better if you don't need to deal with it)<br />
# ''' Client side '''<br />
## Check that you use ajaxcall only on player actions and never initiated programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors. This can also break replays and tutorials. ''Exception: sometimes you can do no-op moves with timeouts (i.e. user has only one choice, but its unwise to reveal this information by skipping user turn), timeout has to be canceling itself if state transition happen automaticaly (i.e. during reply)''<br />
# ''' User Interface '''<br />
## Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]<br />
## Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.<br />
## If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.<br />
## If your game elements become blurry or pixellated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]<br />
## Non-self explanatory graphic elements should have tooltips<br />
## Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.<br />
## A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected<br />
## If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.<br />
# ''' Special testing '''<br />
## Game is tested with spectator (non player observer): change the testuser in the URL to see the game as another user (same URL as when clicking on red arrow). As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.<br />
## Game is tested with in-game replay from last move feature (by clicking on notification log items).<br />
## After finishing a game, it is possible to watch the replay (using the "Replay game" button on the table page) from game start to game end without errors.<br />
## Game works in Chrome and Firefox browsers at least. Also very recommended to test in Edge and Safari.<br />
## Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)<br />
## Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn<br />
## Test your game in 3D mode (if it makes sense; 3D mode can also be disabled through the 'enable_3d' parameter for gameinfos.inc.php, but if it "mostly works", it can be nice to keep it activated even if 2D is more appropriate for the game, just because it's fun to look at)<br />
## Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]<br />
# ''' Cleanup '''<br />
## Remove all unnecessary console.log and other tracing from your js code (Note: technically it is removed by minimizer, but not console.error)<br />
## Remove all unnecessary debug logging from your php code<br />
## Copyright headers in all source files have your name<br />
## Remove unncessery files from main folder (can move some to misc folder)<br />
## Remove all unused graphics from img/ folder<br />
# ''' Static Analysis '''<br />
## Some of the checks above are automated, to run them go to control panel, go to your project and select "Check project" button (it will open like a game table, and you click on Start button to run analysis)<br />
# ''' Finally move to Alpha status '''<br />
## If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it.<br />
## Create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").<br />
## Send an e-mail to studio@boardgamearena.com asking to move the project forward for Alpha/Review. You cannot deploy yourself from the "manage game" page until a first deploy has been done by the admins. If they don't reply in 3 days send email again, you can also nag on discord channel and forum until you get the attention. Note: you can also ask publish for private Alpha - in this case you will invite people manually. You nobody replied after 7 days you can start getting worried.<br />
<pre><br />
Subject: PUSH TO ALPHA: <gamename><br />
<br />
Hi studio admin, I went through https://en.doc.boardgamearena.com/Pre-release_checklist and I think my game is ready to be moved to public Alpha, please push it.<br />
<br />
Game page: https://studio.boardgamearena.com/studiogame?game=<gamename> <br />
My Studio account: xxx<br />
My BGA account: yyy<br />
Rename required: <originalgamename><br />
License status: <granted/pending/public domain><br />
Asset status: <no issues/hi-res graphics assets are missing><br />
</pre><br />
* ''' Wait '''<br />
** When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps.<br />
<br />
=== Move from Alpha to Beta ===<br />
# The implementation '''must be approved by the publisher''' (if not a public domain game)<br />
# Generally it is recommended (but not essential) to have at least 10 approvals from reviewer with rank > 3.5 and not too many bugs opened<br />
# If the game is well-received (preferably game rating ≥4.5) and there are no pending issues the game may pass as administrative discretion without 10+ approvals<br />
# Send an e-mail to studio@boardgamearena.com asking to move the project forward for Beta<br />
<br />
<pre><br />
Subject: PUSH TO BETA: <gamename><br />
<br />
Hi studio admin, I think my game is ready to be moved to Beta.<br />
<br />
Game page: https://studio.boardgamearena.com/studiogame?game=<gamename> <br />
My Studio account: xxx<br />
My BGA account: yyy<br />
Approved by publisher: <info of publisher approval><br />
Number of approvals: X<br />
Approval rating: Y<br />
Remaining bugs: X<br />
</pre><br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Pre-release_checklist&diff=13487
Pre-release checklist
2022-06-08T15:47:49Z
<p>Een: Addendum for client side</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
If you think your game is ready to be reviewed by by BGA admins and/or Publisher (aka go to Alpha stage) please consult this checklist first<br />
<br />
=== Move from Dev to Alpha ===<br />
# ''' License '''<br />
## BGA must have a license for the game for a project to be moved to production, even to alpha. If you don't have license yet you can continue checking other stuff from the list below, but at the end it cannot be moved until license situation is cleared.<br />
# ''' Metadata and graphics '''<br />
## [[Game_meta-information: gameinfos.inc.php]] has correct and up to date information about the game. That includes game tags. <b>Important!!!</b> tags are only read during the first deploy.<br />
## Game box graphics is 3D version of the game box (if available) and publisher icon is correct (see [[Game art: img directory]]). Space around the box has to be transparent, not white.<br />
## You have added a game_banner.jpg and some game_displayX.jpg images to make the game page pretty (NB: on the studio, you have to create a build for these images to appear on the studio game page)<br />
## There are no images in the img directory that are not needed anymore<br />
## Multiple images (i.e. cards) are compressed in "Sprite" (see [[Game art: img directory]])<br />
## Each image should not exceed 4Mb<br />
## Total size should not exceed 10Mb, image compression should be used otherwise (it also helps a lot to re-encode images as indexed palette vs RBG). If you have legitimate reason to have more than 10Mb (i.e. expansions), you have to make a note of that when requesting move to alpha<br />
## If you use extra fonts, they should be freeware (please include a .txt with the licence information)<br />
# ''' Server side '''<br />
## When giving their turn to a player, you give them some extra time with the giveExtraTime() function<br />
## Game progression is implemented (getGameProgression() in php)<br />
## Zombie turn is implemented (zombieTurn() in php). Note: it can only be tested if you explicitly click on the quit button to create a zombie. If you are expelled it does not generated a Zombie.<br />
## You have defined and implemented some meaningful statistics for your game (i.e. total points, point from source A, B, C...)<br />
## Game has meaningful notification messages (but don't overkill it, more user logs will slow down the loading)<br />
## You implemented tiebreaking (using aux score field) and updated tiebreaker description in meta-data<br />
## Database: make sure you do not programmatically manage transactions or call queries that change database schema or even TRUNCATE (queries that would cause implicit commit) during normal game opearations<br />
## Database: make sure you DB schema would be sufficient to complete the game and good enough for possible expantions, changing db schema schema after the release even in alpha is very challenging (it is possible but much better if you don't need to deal with it)<br />
# ''' Client side '''<br />
## Check that you use ajaxcall only on player actions and never initiated programmatically. Otherwise, your code will very likely create race conditions resulting in deadlocks or other errors. This can also break replays and tutorials. ''Exception: sometimes you can do no-op moves with timeouts (i.e. user has only one choice, but its unwise to reveal this information by skipping user turn), timeout has to be canceling itself if state transition happen automaticaly (i.e. during reply)''<br />
# ''' User Interface '''<br />
## Review BGA UI design Guidelines [[BGA_Studio_Guidelines]]<br />
## Check all your English messages for proper use of punctuation, capitalization, usage of present tense in notification (not past) and gender neutrality. See [[Translations]] for English rules.<br />
## If the elements in your game zone don't occupy all the available horizontal space, '''they should be centered'''.<br />
## If your game elements become blurry or pixellated when using the browser zoom, you may want to consider [[Game_art:_img_directory#Use_background-size | higher resolution images with background-size]]<br />
## Non-self explanatory graphic elements should have tooltips<br />
## Strings in your source code are ready for translation. See [[Translations]]. You can generate dummy translations for checking that everything is ready for translation from your "Manage game" page.<br />
## A prefix for example a trigram for your game that you prepend to all the css classes to avoid namespace conflicts, i.e. vla_selected vs selected<br />
## If you are looking for advice on design and some 3rd party testing you can post a message on the developers forum, and ask other developers, there are a lot of people who will gladly do it.<br />
# ''' Special testing '''<br />
## Game is tested with spectator (non player observer): change the testuser in the URL to see the game as another user (same URL as when clicking on red arrow). As a spectator, you should be able to see the game as if you were sitting beside of the players at a real table: all public information, no private information.<br />
## Game is tested with in-game replay from last move feature (by clicking on notification log items)<br />
## Game works in Chrome and Firefox browsers at least. Also very recommended to test in Edge and Safari.<br />
## Game works on mobile device (if you don't have mobile device to test at least test in Chrome with smaller screen, they have a mode for that)<br />
## Test your game in realtime mode. Usually people will run out of time if you use default times unless you add call giveExtraTime($active_player_id) before each turn<br />
## Test your game in 3D mode (if it makes sense; 3D mode can also be disabled through the 'enable_3d' parameter for gameinfos.inc.php, but if it "mostly works", it can be nice to keep it activated even if 2D is more appropriate for the game, just because it's fun to look at)<br />
## Check your game against the waiting screen, otherwise game start can fail. See [[Practical_debugging#Debugging_an_issue_with_the_waiting_screen]]<br />
# ''' Cleanup '''<br />
## Remove all unnecessary console.log and other tracing from your js code (Note: technically it is removed by minimizer, but not console.error)<br />
## Remove all unnecessary debug logging from your php code<br />
## Copyright headers in all source files have your name<br />
## Remove unncessery files from main folder (can move some to misc folder)<br />
## Remove all unused graphics from img/ folder<br />
# ''' Static Analysis '''<br />
## Some of the checks above are automated, to run them go to control panel, go to your project and select "Check project" button (it will open like a game table, and you click on Start button to run analysis)<br />
# ''' Finally move to Alpha status '''<br />
## If possible (meaning if there is not already a project with that name) copy your project to a new project '''matching exactly the name of the game''' (no prefix or suffix). If not possible move on to the next steps, admin will have to retrieve the other project and overwrite it.<br />
## Create a build for your game from the "manage game" page (using the '''Build a new release version''' section) and check the log to make sure that everything builds fine (after a successful build, you should see a new version in "Versions available for production").<br />
## Send an e-mail to studio@boardgamearena.com asking to move the project forward for Alpha/Review. You cannot deploy yourself from the "manage game" page until a first deploy has been done by the admins. If they don't reply in 3 days send email again, you can also nag on discord channel and forum until you get the attention. Note: you can also ask publish for private Alpha - in this case you will invite people manually. You nobody replied after 7 days you can start getting worried.<br />
<pre><br />
Subject: PUSH TO ALPHA: <gamename><br />
<br />
Hi studio admin, I went through https://en.doc.boardgamearena.com/Pre-release_checklist and I think my game is ready to be moved to public Alpha, please push it.<br />
<br />
Game page: https://studio.boardgamearena.com/studiogame?game=<gamename> <br />
My Studio account: xxx<br />
My BGA account: yyy<br />
Rename required: <originalgamename><br />
License status: <granted/pending/public domain><br />
Asset status: <no issues/hi-res graphics assets are missing><br />
</pre><br />
* ''' Wait '''<br />
** When admins publish (push to alpha) they will send an email to the developer with all relevant information about the next steps.<br />
<br />
=== Move from Alpha to Beta ===<br />
# The implementation '''must be approved by the publisher''' (if not a public domain game)<br />
# Generally it is recommended (but not essential) to have at least 10 approvals from reviewer with rank > 3.5 and not too many bugs opened<br />
# If the game is well-received (preferably game rating ≥4.5) and there are no pending issues the game may pass as administrative discretion without 10+ approvals<br />
# Send an e-mail to studio@boardgamearena.com asking to move the project forward for Beta<br />
<br />
<pre><br />
Subject: PUSH TO BETA: <gamename><br />
<br />
Hi studio admin, I think my game is ready to be moved to Beta.<br />
<br />
Game page: https://studio.boardgamearena.com/studiogame?game=<gamename> <br />
My Studio account: xxx<br />
My BGA account: yyy<br />
Approved by publisher: <info of publisher approval><br />
Number of approvals: X<br />
Approval rating: Y<br />
Remaining bugs: X<br />
</pre><br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Options_and_preferences:_gameoptions.json,_gamepreferences.json&diff=13485
Options and preferences: gameoptions.json, gamepreferences.json
2022-06-08T10:36:58Z
<p>Een: /* Game Options */ alpha attribute</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
In this file, you can define your game options (i.e. game variants) and user preferences.<br />
<br />
Note: If your game has no variants or preferences, you don't have to modify this file.<br />
<br />
'''IMPORTANT:''' after you edited this file and syncronized to ftp folder you have to go to the control panel and press "Reload game options configuration" for your changes '''to take effect'''.<br />
<br />
Make sure you understand difference bettween options and preferences:<br />
* Game options - something usually in the rule book defined as "variant" (except for 2,3,X people - that is automatically handled - you can query it)<br />
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, either or not to prompt for action, ether or not auto-opt in in some actions, etc<br />
<br />
__TOC__<br />
<br />
== Game Options ==<br />
<br />
Game options are selected by the table creator and usually correspond to game variants, for example if the game includes expansions or certain special rules.<br />
<br />
These variants are defined in gameoptions.inc.php as the $game_options variable: <br />
<br />
$game_options = [ // exactly named that<br />
// options start with 100<br />
100 => [ /*option description array for option 100*/ ], <br />
101 => [ /*option description array for option 101*/ ], <br />
// etc<br />
];<br />
<br />
<br />
All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)<br />
<br />
self::initGameStateLabels ([<br />
...<br />
"my_game_variant" => 100,<br />
]);<br />
<br />
Numbers have to be exactly from 100 to 199 (there can be gaps).<br />
<br />
That is how you access them during runtime:<br />
<br />
public function isSecondVariant() {<br />
return $this->getGameStateValue('my_game_variant') == 2;<br />
}<br />
<br />
Or this<br />
$this->gamestate->table_globals[100]<br />
<br />
The following are the parameters of option description array:<br />
* '''name''' - '''mandatory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.<br />
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.<br />
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.<br />
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected.<br />
** '''tmdisplay''' - String representation of the option visible in the table description in the lobby. Usually if a variant values are On and Off (default), the tmdisplay would be same as description name when On, and nothing (empty string) when Off. ('''Warning''': due to some caching, a change in tmdisplay may not be effective immediately in the studio, even after forcing a reload of gameoptions.inc.php.) '''Pro Tip:''' You can use this as a pre-game communication by adding fake options that just do nothing in the game but make it easier to find other player wanted the same game configuration (see the crew deep sea for example).<br />
** '''nobeginner''' - Set to true if not recommended for beginners<br />
** '''firstgameonly''' - Set to true if this option is recommended only for the first game (discovery option)<br />
** '''beta''' - Set to true to indicate that this option is in "beta" development stage (there will be a warning for players starting the game)<br />
** '''alpha''' - Set to true to indicate that this option is in "alpha" development stage (there will be a warning, and starting the game will be allowed only in training mode except for the developer)<br />
** '''premium''' - Option can be only used by premium members<br />
* '''default''' - indicates the default value to use for this option (optional, if not present the first value listed is the default)<br />
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:<br />
** ''minplayers'' condition ensures at least this many players<br />
** ''maxplayers'' conditions ensure at most this many players<br />
** ''otheroption'' condition ensures another option is set to this given values. <br />
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given values<br />
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.<br />
* '''startcondition''' - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:<br />
** ''minplayers'' condition ensures at least this many players<br />
** ''maxplayers'' conditions ensure at most this many players<br />
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.<br />
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.<br />
** ''gamestartonly'' if you have options that are exclusive, for example for a solo mode: you can have a maxplayer of 1 for one option and a minplayer of 2 for an other option and you will be stuck. See below for an example.<br />
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down<br />
<br />
Common options for all tables (reserved range 200-299):<br />
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode), <br />
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile, array(0,1,2) - realtime (technically <10 realtime but you cannot define range in php), values >=10 - turn based (currently 10..21)<br />
<br />
Example:<br />
<pre><br />
$game_options = array(<br />
100 => array(<br />
'name' => totranslate('my game option'),<br />
'values' => array(<br />
// A simple value for this option:<br />
1 => array(<br />
'name' => totranslate('option 1')<br />
),<br />
<br />
// A simple value for this option.<br />
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby<br />
2 => array(<br />
'name' => totranslate('option 2'),<br />
'tmdisplay' => totranslate('option 2')<br />
),<br />
<br />
// Another value, with other options:<br />
// beta=true => this option is in beta version right now.<br />
// nobeginner=true => this option is not recommended for beginners<br />
3 => array(<br />
'name' => totranslate('option 3'),<br />
'beta' => true,<br />
'nobeginner' => true<br />
),<br />
),<br />
'default' => 1<br />
),<br />
<br />
101 => array(<br />
'name' => totranslate('Draft variant'),<br />
'values' => array(<br />
1 => array(<br />
'name' => totranslate('No draft')<br />
),<br />
2 => array(<br />
'name' => totranslate('Draft'),<br />
'tmdisplay' => totranslate('Draft'),<br />
'premium' => true,<br />
'nobeginner' => true<br />
),<br />
),<br />
'displaycondition' => array( <br />
// Note: do not display this option unless these conditions are met<br />
array(<br />
'type' => 'otheroption',<br />
'id' => 100, // Game specific option defined in the same array above<br />
'value' => array(2, 3, 4)<br />
),<br />
// Note: do not display this option unless these conditions are met<br />
array( 'type' => 'otheroption', <br />
'id' => 201, // ELO OFF hardcoded framework option<br />
'value' => 1 // 1 if OFF<br />
)<br />
),<br />
<br />
'startcondition' => array(<br />
1 => array(),<br />
2 => array(<br />
array(<br />
'type' => 'maxplayers',<br />
'value' => 3,<br />
'message' => totranslate('Draft option is available for 3 players maximum.')<br />
)<br />
),<br />
),<br />
),<br />
<br />
102 => array(<br />
'name' => totranslate('Takeovers'),<br />
'values' => array(<br />
2 => array(<br />
'name' => totranslate('No takeover')<br />
),<br />
1 => array(<br />
'name' => totranslate('Allow takeovers'),<br />
'tmdisplay' => totranslate('Takeovers'),<br />
'premium' => true,<br />
'nobeginner' => true<br />
),<br />
),<br />
'displaycondition' => array( // Note: do not display this option unless these conditions are met<br />
array(<br />
'type' => 'otheroption',<br />
'id' => 100,<br />
'value' => array(3, 4)<br />
)<br />
),<br />
'startcondition' => array(<br />
2 => array(),<br />
1 => array(<br />
array(<br />
'type' => 'maxplayers',<br />
'value' => 2,<br />
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')<br />
)<br />
),<br />
),<br />
)<br />
);<br />
</pre><br />
<br />
Example of option that condition on ELO off<br />
<br />
<pre><br />
$game_options = array(<br />
<br />
100 => array(<br />
'name' => totranslate('Learning Game (No Research)'),<br />
'values' => array(<br />
<br />
1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),<br />
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),<br />
<br />
),<br />
'displaycondition' => array(<br />
// Note: do not display this option unless these conditions are met<br />
array( 'type' => 'otheroption',<br />
'id' => 201, // ELO OFF hardcoded framework option<br />
'value' => 1, // 1 if OFF<br />
<br />
)<br />
),<br />
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')<br />
),<br />
<br />
);<br />
</pre><br />
<br />
Example of condition that is only available for REALTIME game mode<br />
<pre><br />
'displaycondition' => array(<br />
// Note: do not display this option until these conditions are met - game speed is selected as realtime<br />
array( 'type' => 'otheroption', 'id' => GAMESTATE_CLOCK_MODE, 'value' => array(0,1,2) )<br />
),<br />
</pre><br />
<br />
Example of using condition on your own option<br />
<pre><br />
102 => array(<br />
'name' => totranslate('Scenarios'),<br />
'values' => array(<br />
1 => array( 'name' => totranslate('Off'),<br />
'nobeginner' => false ),<br />
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),<br />
'nobeginner' => true ),<br />
<br />
),<br />
'displaycondition' => array(<br />
// Note: do not display this option unless these conditions are met<br />
array( 'type' => 'otheroptionisnot',<br />
'id' => 100, // learning variant<br />
'value' => 2, // 1 if OFF,2 is ON<br />
<br />
)<br />
),<br />
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')<br />
),<br />
</pre><br />
<br />
Example of ''gamestartonly'':<br />
<pre><br />
102 => array(<br />
'name' => totranslate('Mode'),<br />
'values' => array(<br />
1 => array(<br />
'name' => totranslate('Normal')<br />
),<br />
2 => array(<br />
'name' => totranslate('Solo'),<br />
),<br />
),<br />
'startcondition' => array(<br />
1 => array(<br />
array(<br />
'type' => 'minplayers',<br />
'value' => 2,<br />
'message' => totranslate('Normal mode is 2 for players or more'),<br />
'gamestartonly' => true,<br />
)<br />
),<br />
2 => array(<br />
array(<br />
'type' => 'maxplayers',<br />
'value' => 1,<br />
'message' => totranslate('Solo mode is for 1 player'),<br />
'gamestartonly' => true,<br />
)<br />
),<br />
),<br />
)<br />
</pre><br />
<br />
== User Preferences ==<br />
<br />
User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users<br />
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.<br />
These preferences appear in the three-line hamburger menu in the top corner of the bga menu. "Display game logs" and Display tooltips" are baked-in by default, but you can extend this list as below. <br />
<br />
[[File:century_preferences_menu.PNG|400px|The user preferences menu for the game Century]]<br />
<br />
<br />
<br />
<blockquote><br />
''These preferences are a good place to put accessibility options - as Century did for its Colorblind Support.''<br />
</blockquote><br />
<br />
<pre><br />
$game_preferences = array(<br />
100 => array(<br />
'name' => totranslate('Colorblind Support'),<br />
'needReload' => true, // after user changes this preference game interface would auto-reload<br />
'values' => array(<br />
1 => array( 'name' => totranslate( 'None' ), 'cssPref' => 'colorblind_off' ),<br />
2 => array( 'name' => totranslate( 'Numbers' ), 'cssPref' => 'colorblind_on' ),<br />
3 => array( 'name' => totranslate( 'Shapes' ), 'cssPref' => 'colorblind_shapes' )<br />
),<br />
'default' => 1<br />
),<br />
);<br />
</pre><br />
<br />
There is two ways to check/apply this. In java Script<br />
<br />
if (this.prefs[100].value == 2) ...<br />
<br />
This checks if preferences 100 has selected value 2.<br />
<br />
Second, if cssPref specified it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: it seems needed to set needReload to true for that class change to be effective.<br />
<br />
As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).<br />
<br />
The following are the parameters of preferences description array:<br />
* '''name''' - '''mandatory'''. The name of the preference. Value will be automatically wrapped in totranslate if you don't.<br />
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.<br />
* '''values''' - '''mandatory'''. The array (map) of values with additional parameters per value.<br />
** '''name''' - '''mandatory'''. String representation of the numeric value. Value will be automatically wrapped in totranslate if you don't.<br />
** '''cssPref''' - CSS class to add to the '''<html>''' tag. Currently it is added or removed only after a reload (see needReload).<br />
* '''default''' - Indicates the default value to use for this preference (optional, if not present the first value listed is the default).<br />
<br />
=== Listening for preference changes ===<br />
<br />
The BGA framework lacks any callback to notify your game when a user preference is changed (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to run some UI code in response to a preference change.<br />
<br />
; In ggg.js<br />
<pre><br />
setup: function (gamedatas) {<br />
// your setup code here ...<br />
<br />
this.initPreferencesObserver();<br />
},<br />
<br />
<br />
initPreferencesObserver: function () { <br />
// Call onPreferenceChange() when any value changes<br />
dojo.query('.preference_control').on('change', (e) => {<br />
const match = e.target.id.match(/^preference_[cf]ontrol_(\d+)$/);<br />
if (!match) {<br />
return;<br />
}<br />
const pref = match[1];<br />
const newValue = e.target.value;<br />
this.prefs[pref].value = newValue;<br />
this.onPreferenceChange(pref, newValue);<br />
});<br />
},<br />
<br />
onPreferenceChange: function (prefId, prefValue) {<br />
console.log("Preference changed", prefId, prefValue);<br />
// your code here to handle the change<br />
},<br />
</pre><br />
<br />
=== Updating preference from code ===<br />
The BGA framework lacks any method to update a user preference from the code (see [https://studio.boardgamearena.com/bug?id=36 proposal #36]), but you can create your own if you need to.<br />
<br />
; In ggg.js<br />
<pre><br />
updatePreference: function(prefId, newValue) {<br />
// Select preference value in control:<br />
dojo.query('#preference_control_' + prefId + ' > option[value="' + newValue<br />
// Also select fontrol to fix a BGA framework bug:<br />
+ '"], #preference_fontrol_' + prefId + ' > option[value="' + newValue<br />
+ '"]').forEach((value) => dojo.attr(value, 'selected', true));<br />
// Generate change event on control to trigger callbacks:<br />
const newEvt = document.createEvent('HTMLEvents');<br />
newEvt.initEvent('change', false, true);<br />
$('preference_control_' + prefId).dispatchEvent(newEvt);<br />
},<br />
</pre><br />
<br />
=== Accessing User Preferences on the server ===<br />
Surprise, surprise - this is lacking too. Mostly.<br />
There is a variable you can acesses called $this->player_preferences.<br />
This contains table of user preferences, ONLY accessible in setupNewGame().<br />
You can use this to populate a table that you manage yourself.<br />
The table has to be updated when user changes preference (and you have to hook up a lister and initiate a special axac call out-of-turn).<br />
Check the code of Agricola for details but this should work:<br />
<br />
; In dbmodel.sql<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `user_preferences` (<br />
`player_id` int(10) NOT NULL,<br />
`pref_id` int(10) NOT NULL,<br />
`pref_value` int(10) NOT NULL,<br />
PRIMARY KEY (`player_id`, `pref_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
</pre><br />
<br />
; In ggg.game.php<br />
<pre><br />
protected function setupNewGame($players, $options = array())<br />
{<br />
// TODO: Save $this->player_preferences: key is player_id, value is array with pref_id as key and pref_value as value<br />
}<br />
</pre><br />
<br />
; In ggg.js<br />
<br />
<pre><br />
<br />
// use code for initPreferencesObserver from above example<br />
<br />
onPreferenceChange(prefId, prefValue) {<br />
prefId = parseInt(prefId);<br />
if (prefId === 101 /*TODO: You probably want to send only some preferences*/) {<br />
// TODO: Code your own action in ggg.action.php and send it prefId and prefValue<br />
// The on the server side you can save it all in the user_preferences<br />
// table you created above.<br />
}<br />
},<br />
</pre><br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_metadata_manager&diff=13415
Game metadata manager
2022-06-01T19:14:19Z
<p>Een: /* Media */ indication about the display images location</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
[[File:Game_Metadata_Manager_Icon.png|left|100px|link=|Game Metadata Manager Icon]]<br />
<br />
The <i>Game Metadata Manager</i> is the portal for managing tags and media for your games. This page exists both on Production and Studio:<br />
<br />
* [https://boardgamearena.com/controlpanelgames Game Metadata Manager (production)] - manage game tags and media once the game has reached private alpha and beyond<br />
* [https://studio.boardgamearena.com/controlpanelgames Game Metadata Manager (studio)] - manage game media before the game reaches private alpha<br />
<br />
Note: once your game is in private alpha, and you are using the production Game Metagata Manager, the metadata on studio is <i>never</i> updated.<br />
<br />
<br />
__TOC__<br />
<br />
== Media ==<br />
<br />
Game media consists of all the images which are used to represent your game on Board Game Arena, outside of the art of the actual game.<br />
<br />
Whilst working on your game on the studio initially, you can manage media from the studio: [https://studio.boardgamearena.com/controlpanelgames Game Metadata Manager (studio)].<br />
<br />
Once your game first hits private alpha, the media is copied over to the production site, and from this point on, all media changes must be effectuated over there: [https://boardgamearena.com/controlpanelgames Game Metadata Manager (production)].<br />
<br />
{| class="wikitable" style="margin:auto"<br />
|-<br />
! Name !! Example !! Description<br />
|-<br />
| Box || [[File:Carcassonne_Box.png|frameless|Box]] ||<br />
* PNG<br />
* It is displayed on the main site on the game description page and when creating a table (280x280 px).<br />
* It should be a 3D image of a physical copy of the game box as it appears in an online shop.<br />
* It is better to take the version of the game that is coherent with the game art used in the adaptation, and from the original publisher of the game.<br />
* The background of the image must be transparent.<br />
* If you don't have a 3D version of the game box, you can use the following website to create one: http://www.3d-pack.com/<br />
|-<br />
| Icon || [[File:Carcassonne_Icon.png|frameless|Icon]] ||<br />
* PNG<br />
* It is the icon displayed in the lists of games and tables (50x50 px).<br />
* The objective of this icon is to make the game recognizable among the other games. A good idea is to take a part of the game cover that is distinctive (ex: the game title).<br />
* This one does not have to be transparent. This image should not have a border <br />
|-<br />
| Title || [[File:Carcassonne_Title.png|frameless|Title]] ||<br />
* PNG<br />
* This is an image displayed instead of the name of the game as text<br />
* Must be 2000x2000px<br />
* Must look good when overlayed on top of the game box, and must be transparent<br />
* There should be a transparent margin of at least 500px at the top and bottom<br />
* You can have a different title image for each language, so you can show a localised image if you wish (for example, "Stone Age" vs "L'Âge de Pierre"). If you don't provide a localised image, users will see the en title as a fallback. In this case, if the localised name differs from en, there will also be a subtitle showing the game's name in the user's locale.<br />
<br />
⚠️ <b>Warning</b>: BGA are bit-by-bit adding titles to many games, and it's likely your released games are in the queue somewhere.<br />
So, don't feel you need to rush to make a title. And, if you do make one now -- don't be surprised if it ends up getting replaced a little down the line.<br />
|-<br />
| Publisher || - ||<br />
* PNG<br />
* It is the logo of the publisher of the game, displayed on the game description page.<br />
* The width must be 150 px. The height can be anything (reasonable). The image could be transparent.<br />
* You can have up to 2 publisher images<br />
|-<br />
| Banner || [[File:Carcassonne_Banner.jpg|frameless|Title]] ||<br />
* JPG<br />
* size 1386x400px<br />
* should not contain any text; representative of the atmosphere of the game such as a cover element or communication image; the box image covering the banner on the left should stand out<br />
|-<br />
| Display || - ||<br />
* JPG<br />
* height between 400px and 760px, width maximum 1.5 x height;<br />
* These images are displayed in a carousel on the game page<br />
* the idea is to make players want to play the game, so it could be a zoomed card, some detail of the board, an overview of an ongoing physical game... but NOT a screenshot of the BGA adaptation since there is already the "see game in action" replay for that<br />
* You can have up to 10 display images<br />
|}<br />
<br />
== Tags ==<br />
<br />
Whilst working on your game on the studio initially, you can manage tags from the [[Game meta-information: gameinfos.inc.php|gameinfos.inc.php]] file.<br />
<br />
Once your game first hits private alpha, the tags are copied over to the production site, and from this point on, all tag changes must be effectuated over there: [https://boardgamearena.com/controlpanelgames Game Metadata Manager (production)].<br />
<br />
Note: this will change in the future to be more consistent.<br />
<br />
== Migration ==<br />
<br />
Images used to be served from the[[Game art: img directory|/img]] folder of your game's repository. All of these files (those prefixed with <code>game_</code>) are now deprecated and can be deleted from the folder. Any changes to these images will not be picked up.<br />
<br />
Tags used to be managed by changing the tags in [[Game meta-information: gameinfos.inc.php|gameinfos.inc.php]]. These tags are read only on the first deploy to production, from which point onwards tags must be editted using the [https://boardgamearena.com/controlpanelgames Game Metadata Manager] on production.<br />
<br />
== Future ==<br />
<br />
The Game Metadata Manager will play an increasingly important role in managing a BGA implementation in the future.<br />
<br />
It is planned that:<br />
* more metadata (such as publisher and designer names, or presentation text) be managed here<br />
* tags be managed exclusively this way (removing the initial dependency on gameinfos.inc.php)<br />
<br />
<br />
[[Category:Studio]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Gamehelpemdomicrocosm&diff=13220
Gamehelpemdomicrocosm
2022-05-16T13:05:43Z
<p>Een: /* Player Area */</p>
<hr />
<div>[[Category:Card games]]<br />
== Overview ==<br />
<br />
Microcosm is a deck building game where the aim is to have more influence than your opponent at the end of the game.<br />
Influence can be earned by:<br />
* Owning colonies<br />
* Owning spoils<br />
* Owning capitals<br />
* Researching technologies<br />
* Collecting red, yellow, green or purple Domain cards, Colonies or Spoils<br />
You score influence at the end of the game, determined by the scoring conditions you have<br />
managed to add to your deck and from the Colonies and Spoils that you own.<br />
<br />
== Player Area ==<br />
<br />
As the game progresses, your player area in front of you, will comprise of:<br />
<br />
* Played Card: The current Domain card you have played and are resolving. Face up.<br />
* Colonies: Planets acquired by playing a Colonize action. Face down unless revealed. You can check all available colonies for reference on this image: https://boardgamegeek.com/image/2521243/eminent-domain-microcosm<br />
* Discards: Cards you have already played and resolved. Face up.<br />
* Spoils: Planets or Colonies won by successfully performing a Warfare action.<br />
* Technologies: Technologies that you have acquired. Face up<br />
<br />
== Game Play ==<br />
<br />
You start the game without any cards in your hand and will gradually build your own deck of cards as<br />
the game progresses.<br />
<br />
Each turn consists of 2 phases.<br />
Beginning with the starting player, take a turn to perform the following 2 phases:<br />
<br />
=== Phase 1 ===<br />
<br />
Either take one of the 3 face up cards in the supply, replacing the taken card with the top card from the draw deck.<br />
'''OR'''<br />
If you don’t like what is available from the supply, then you may take the top card from the draw deck instead.<br />
<br />
=== Phase 2 ===<br />
<br />
Play an action by placing a card from your hand in front of you and resolving the text on the card.<br />
Then place the card in your discard pile.<br />
'''OR'''<br />
Pick up some or all of the cards in your discard pile and put them into your hand.<br />
<br />
In Phase 2, when picking up discards you may pick up as many as you wish. You don't have to pick<br />
up the whole discard pile. There are some cards that are useful to leave in your discard pile.<br />
<br />
== Game End ==<br />
When the draw deck is exhausted, continue play without refilling the supply.<br />
After the last card is drawn from the supply, the active player finishes their turn and the game ends.<br />
<br />
=== Scoring ===<br />
Players collect all cards from their hands and discard piles (keep your colonies and spoils separate) and determine their Influence:<br />
* The Influence calculated from each scoring condition shown on your Domain cards<br />
* The Influence shown on any Colonies and Spoils owned<br />
<br />
The sum of these is your final Influence score.<br />
The player with the most influence wins. In the case of a tie, the player who played second wins.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Gamehelpemdomicrocosm&diff=13219
Gamehelpemdomicrocosm
2022-05-16T13:05:16Z
<p>Een: /* Player Area */</p>
<hr />
<div>[[Category:Card games]]<br />
== Overview ==<br />
<br />
Microcosm is a deck building game where the aim is to have more influence than your opponent at the end of the game.<br />
Influence can be earned by:<br />
* Owning colonies<br />
* Owning spoils<br />
* Owning capitals<br />
* Researching technologies<br />
* Collecting red, yellow, green or purple Domain cards, Colonies or Spoils<br />
You score influence at the end of the game, determined by the scoring conditions you have<br />
managed to add to your deck and from the Colonies and Spoils that you own.<br />
<br />
== Player Area ==<br />
<br />
As the game progresses, your player area in front of you, will comprise of:<br />
<br />
* Played Card: The current Domain card you have played and are resolving. Face up.<br />
* Colonies: Planets acquired by playing a Colonize action. Face down unless revealed. You can check all available colonies for reference on this image: https://fr.doc.boardgamearena.com/Gamehelpemdomicrocosm<br />
* Discards: Cards you have already played and resolved. Face up.<br />
* Spoils: Planets or Colonies won by successfully performing a Warfare action.<br />
* Technologies: Technologies that you have acquired. Face up<br />
<br />
== Game Play ==<br />
<br />
You start the game without any cards in your hand and will gradually build your own deck of cards as<br />
the game progresses.<br />
<br />
Each turn consists of 2 phases.<br />
Beginning with the starting player, take a turn to perform the following 2 phases:<br />
<br />
=== Phase 1 ===<br />
<br />
Either take one of the 3 face up cards in the supply, replacing the taken card with the top card from the draw deck.<br />
'''OR'''<br />
If you don’t like what is available from the supply, then you may take the top card from the draw deck instead.<br />
<br />
=== Phase 2 ===<br />
<br />
Play an action by placing a card from your hand in front of you and resolving the text on the card.<br />
Then place the card in your discard pile.<br />
'''OR'''<br />
Pick up some or all of the cards in your discard pile and put them into your hand.<br />
<br />
In Phase 2, when picking up discards you may pick up as many as you wish. You don't have to pick<br />
up the whole discard pile. There are some cards that are useful to leave in your discard pile.<br />
<br />
== Game End ==<br />
When the draw deck is exhausted, continue play without refilling the supply.<br />
After the last card is drawn from the supply, the active player finishes their turn and the game ends.<br />
<br />
=== Scoring ===<br />
Players collect all cards from their hands and discard piles (keep your colonies and spoils separate) and determine their Influence:<br />
* The Influence calculated from each scoring condition shown on your Domain cards<br />
* The Influence shown on any Colonies and Spoils owned<br />
<br />
The sum of these is your final Influence score.<br />
The player with the most influence wins. In the case of a tie, the player who played second wins.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Gamehelpelgrande&diff=12503
Gamehelpelgrande
2022-04-05T11:08:11Z
<p>Een: </p>
<hr />
<div><div style="background-color: rgba(255, 255, 159,0.7); border-radius: 10px; padding: 0.8em; border: 4px solid orange;"><br />
<b>Note about the Veto card</b>: this card was specifically challenging to implement. On Board Game Arena, Veto can be used to cancel any Action card before it is activated. Some Actions can also be cancelled partially, but <b>this is not possible for all Actions</b>.<br />
Please note that you can also <b>exclude Veto</b> through an option when starting a game.<br />
</div><br />
<br />
<br />
GOAL: Score the most points by having more caballeros in the regions than other players, but beware - the castillo holds a surprise!<br />
<br />
GAMEPLAY:<br />
<br />
Action cards are revealed at the start of each round. <br />
<br />
Going clockwise, each player bids a power card to determine: turn order AND the number of caballeros that can add from the provinces into the court. Only the caballeros in your court can be added to regions on the map during your turn.<br />
<br />
Turn order changes each round, with play going in order of highest card value to lowest: Highest valued card goes first, 2nd highest card goes 2nd, etc. <br />
<br />
ON YOUR TURN: <br />
<br />
1. Add caballeros from your provinces into your court.<br />
<br />
- The number of caballeros you may add = the number of cubes shown in the center of the power card you played. You can add up to that many caballeros to your court.<br />
<br />
- If there are not enough caballeros in your province to add into the court, you can take caballeros from any region on the map except the King's region and castillo.<br />
<br />
2. Select an action card.<br />
<br />
- You do not have to take the action, but you do have to take a card.<br />
<br />
- The action card shows how many caballeros you can place on the map FROM YOUR COURT. The number of cubes shown at the bottom of the card is the most you can place. You can place fewer, if you like.<br />
<br />
*** You can take the action, then place caballeros OR place caballeros, then take the action.<br />
<br />
PLACEMENT RULES:<br />
<br />
- You can only place caballeros in regions adjacent to the King's region - but never in the King's region.<br />
<br />
- You can distribute the caballeros among multiple regions.<br />
<br />
- You can place caballeros into the castillo.<br />
<br />
MOVEMENT RULES:<br />
<br />
- Some cards allow you to move caballeros that are already placed on the map. You may move these caballeros to ANY other region on the map, except the King's region. You can move even them into the castillo.<br />
<br />
After everyone has taken a turn, new action cards are revealed and bidding for start player occurs - THE PLAYER WHO PLAYED THE LOWEST CARD LAST ROUND STARTS THE BID<br />
<br />
SCORING ROUNDS (occur after rounds 3, 6 and 9)<br />
<br />
1. Before the regions are scored, each player secretly chooses where they want to place all of their caballeros that are in the castillo. They can go into any region on the map except for the King's region. Players reveal their chosen region at the same time.<br />
<br />
2. The castillo is scored. <br />
<br />
3. Caballeros that were in the castillo are now moved to the chosen region.<br />
<br />
4. Each region is scored.<br />
<br />
SCORING RULES:<br />
<br />
- The purpose of the Grande is to show who owns the region. Only the caballeros are counted when determining majority.<br />
<br />
- The scoreboard in each region shows the points awarded to the players having the most caballeros, 2nd most and 3rd mos caballeros in the region. The player with the most caballeros in a region receives the highest point value for the region shown in the region's scoreboard.<br />
<br />
** In a 2 player game, only the first place points are awarded. In a 3-player game, only the 1st and 2nd place are scored.<br />
<br />
** If TIED: all tied players receive the points in the next lowest position<br />
<br />
BONUS POINTS:<br />
<br />
- If you are the majority player in your home region (where your Grande is located), not tied with any other players, you earn 2 extra points<br />
<br />
- If you are the majority player in the King's region, not tied with any other players, you score 2 extra points.<br />
<br />
OTHER NOTES:<br />
<br />
- You can only use a power card once during the game.<br />
<br />
- When a card triggers special scoring during the game, all regions of the specified point-value must be scored, i.e. all 5-point regions, all 4-point regions, etc.<br />
<br />
- The King's Card is always one of the 5 cards revealed at the start of each round.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Gamehelpelgrande&diff=12477
Gamehelpelgrande
2022-03-31T08:04:41Z
<p>Een: More accurate</p>
<hr />
<div><div style="background-color: rgba(255, 255, 159,0.7); border-radius: 10px; padding: 0.8em; border: 4px solid orange;"><br />
<b>Preliminary note about the Veto card</b>: this card was specifically challenging to implement; some choices had to be made. On Board Game Arena, Veto can be used to cancel any Action card before it is activated. Some Actions can also be cancelled partially, but <b>this is not possible for all Actions</b>.<br />
Please note that you can also <b>exclude Veto</b> through an option when starting a game.<br />
</div><br />
<br />
<br />
GOAL: Score the most points by having more caballeros in the regions than other players, but beware - the castillo holds a surprise!<br />
<br />
GAMEPLAY:<br />
<br />
Action cards are revealed at the start of each round. <br />
<br />
Going clockwise, each player bids a power card to determine: turn order AND the number of caballeros that can add from the provinces into the court. Only the caballeros in your court can be added to regions on the map during your turn.<br />
<br />
Turn order changes each round, with play going in order of highest card value to lowest: Highest valued card goes first, 2nd highest card goes 2nd, etc. <br />
<br />
ON YOUR TURN: <br />
<br />
1. Add caballeros from your provinces into your court.<br />
<br />
- The number of caballeros you may add = the number of cubes shown in the center of the power card you played. You can add up to that many caballeros to your court.<br />
<br />
- If there are not enough caballeros in your province to add into the court, you can take caballeros from any region on the map except the King's region and castillo.<br />
<br />
2. Select an action card.<br />
<br />
- You do not have to take the action, but you do have to take a card.<br />
<br />
- The action card shows how many caballeros you can place on the map FROM YOUR COURT. The number of cubes shown at the bottom of the card is the most you can place. You can place fewer, if you like.<br />
<br />
*** You can take the action, then place caballeros OR place caballeros, then take the action.<br />
<br />
PLACEMENT RULES:<br />
<br />
- You can only place caballeros in regions adjacent to the King's region - but never in the King's region.<br />
<br />
- You can distribute the caballeros among multiple regions.<br />
<br />
- You can place caballeros into the castillo.<br />
<br />
MOVEMENT RULES:<br />
<br />
- Some cards allow you to move caballeros that are already placed on the map. You may move these caballeros to ANY other region on the map, except the King's region. You can move even them into the castillo.<br />
<br />
After everyone has taken a turn, new action cards are revealed and bidding for start player occurs - THE PLAYER WHO PLAYED THE LOWEST CARD LAST ROUND STARTS THE BID<br />
<br />
SCORING ROUNDS (occur after rounds 3, 6 and 9)<br />
<br />
1. Before the regions are scored, each player secretly chooses where they want to place all of their caballeros that are in the castillo. They can go into any region on the map except for the King's region. Players reveal their chosen region at the same time.<br />
<br />
2. The castillo is scored. <br />
<br />
3. Caballeros that were in the castillo are now moved to the chosen region.<br />
<br />
4. Each region is scored.<br />
<br />
SCORING RULES:<br />
<br />
- The purpose of the Grande is to show who owns the region. Only the caballeros are counted when determining majority.<br />
<br />
- The scoreboard in each region shows the points awarded to the players having the most caballeros, 2nd most and 3rd mos caballeros in the region. The player with the most caballeros in a region receives the highest point value for the region shown in the region's scoreboard.<br />
<br />
** In a 2 player game, only the first place points are awarded. In a 3-player game, only the 1st and 2nd place are scored.<br />
<br />
** If TIED: all tied players receive the points in the next lowest position<br />
<br />
BONUS POINTS:<br />
<br />
- If you are the majority player in your home region (where your Grande is located), not tied with any other players, you earn 2 extra points<br />
<br />
- If you are the majority player in the King's region, not tied with any other players, you score 2 extra points.<br />
<br />
OTHER NOTES:<br />
<br />
- You can only use a power card once during the game.<br />
<br />
- When a card triggers special scoring during the game, all regions of the specified point-value must be scored, i.e. all 5-point regions, all 4-point regions, etc.<br />
<br />
- The King's Card is always one of the 5 cards revealed at the start of each round.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Gamehelpelgrande&diff=12473
Gamehelpelgrande
2022-03-30T15:22:50Z
<p>Een: Note about veto</p>
<hr />
<div><div style="background-color: rgba(255, 255, 159,0.7); border-radius: 10px; padding: 0.8em; border: 4px solid orange;"><br />
<b>Preliminary note about the Veto card</b>: this card was specifically challenging to implement; some choices had to be made. On Board Game Arena, Veto can be used to cancel any Action card before it is activated. Some Actions can also be cancelled during their execution after each individual step, but <b>this is not possible for all Actions</b>.<br />
Please note that you can also <b>exclude Veto</b> through an option when starting a game.<br />
</div><br />
<br />
<br />
GOAL: Score the most points by having more caballeros in the regions than other players, but beware - the castillo holds a surprise!<br />
<br />
GAMEPLAY:<br />
<br />
Action cards are revealed at the start of each round. <br />
<br />
Going clockwise, each player bids a power card to determine: turn order AND the number of caballeros that can add from the provinces into the court. Only the caballeros in your court can be added to regions on the map during your turn.<br />
<br />
Turn order changes each round, with play going in order of highest card value to lowest: Highest valued card goes first, 2nd highest card goes 2nd, etc. <br />
<br />
ON YOUR TURN: <br />
<br />
1. Add caballeros from your provinces into your court.<br />
<br />
- The number of caballeros you may add = the number of cubes shown in the center of the power card you played. You can add up to that many caballeros to your court.<br />
<br />
- If there are not enough caballeros in your province to add into the court, you can take caballeros from any region on the map except the King's region and castillo.<br />
<br />
2. Select an action card.<br />
<br />
- You do not have to take the action, but you do have to take a card.<br />
<br />
- The action card shows how many caballeros you can place on the map FROM YOUR COURT. The number of cubes shown at the bottom of the card is the most you can place. You can place fewer, if you like.<br />
<br />
*** You can take the action, then place caballeros OR place caballeros, then take the action.<br />
<br />
PLACEMENT RULES:<br />
<br />
- You can only place caballeros in regions adjacent to the King's region - but never in the King's region.<br />
<br />
- You can distribute the caballeros among multiple regions.<br />
<br />
- You can place caballeros into the castillo.<br />
<br />
MOVEMENT RULES:<br />
<br />
- Some cards allow you to move caballeros that are already placed on the map. You may move these caballeros to ANY other region on the map, except the King's region. You can move even them into the castillo.<br />
<br />
After everyone has taken a turn, new action cards are revealed and bidding for start player occurs - THE PLAYER WHO PLAYED THE LOWEST CARD LAST ROUND STARTS THE BID<br />
<br />
SCORING ROUNDS (occur after rounds 3, 6 and 9)<br />
<br />
1. Before the regions are scored, each player secretly chooses where they want to place all of their caballeros that are in the castillo. They can go into any region on the map except for the King's region. Players reveal their chosen region at the same time.<br />
<br />
2. The castillo is scored. <br />
<br />
3. Caballeros that were in the castillo are now moved to the chosen region.<br />
<br />
4. Each region is scored.<br />
<br />
SCORING RULES:<br />
<br />
- The purpose of the Grande is to show who owns the region. Only the caballeros are counted when determining majority.<br />
<br />
- The scoreboard in each region shows the points awarded to the players having the most caballeros, 2nd most and 3rd mos caballeros in the region. The player with the most caballeros in a region receives the highest point value for the region shown in the region's scoreboard.<br />
<br />
** In a 2 player game, only the first place points are awarded. In a 3-player game, only the 1st and 2nd place are scored.<br />
<br />
** If TIED: all tied players receive the points in the next lowest position<br />
<br />
BONUS POINTS:<br />
<br />
- If you are the majority player in your home region (where your Grande is located), not tied with any other players, you earn 2 extra points<br />
<br />
- If you are the majority player in the King's region, not tied with any other players, you score 2 extra points.<br />
<br />
OTHER NOTES:<br />
<br />
- You can only use a power card once during the game.<br />
<br />
- When a card triggers special scoring during the game, all regions of the specified point-value must be scored, i.e. all 5-point regions, all 4-point regions, etc.<br />
<br />
- The King's Card is always one of the 5 cards revealed at the start of each round.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Gamehelpelgrande&diff=12472
Gamehelpelgrande
2022-03-30T15:22:32Z
<p>Een: Reverted edits by Ze Monstah (talk) to last revision by 4everblessed</p>
<hr />
<div>GOAL: Score the most points by having more caballeros in the regions than other players, but beware - the castillo holds a surprise!<br />
<br />
GAMEPLAY:<br />
<br />
Action cards are revealed at the start of each round. <br />
<br />
Going clockwise, each player bids a power card to determine: turn order AND the number of caballeros that can add from the provinces into the court. Only the caballeros in your court can be added to regions on the map during your turn.<br />
<br />
Turn order changes each round, with play going in order of highest card value to lowest: Highest valued card goes first, 2nd highest card goes 2nd, etc. <br />
<br />
ON YOUR TURN: <br />
<br />
1. Add caballeros from your provinces into your court.<br />
<br />
- The number of caballeros you may add = the number of cubes shown in the center of the power card you played. You can add up to that many caballeros to your court.<br />
<br />
- If there are not enough caballeros in your province to add into the court, you can take caballeros from any region on the map except the King's region and castillo.<br />
<br />
2. Select an action card.<br />
<br />
- You do not have to take the action, but you do have to take a card.<br />
<br />
- The action card shows how many caballeros you can place on the map FROM YOUR COURT. The number of cubes shown at the bottom of the card is the most you can place. You can place fewer, if you like.<br />
<br />
*** You can take the action, then place caballeros OR place caballeros, then take the action.<br />
<br />
PLACEMENT RULES:<br />
<br />
- You can only place caballeros in regions adjacent to the King's region - but never in the King's region.<br />
<br />
- You can distribute the caballeros among multiple regions.<br />
<br />
- You can place caballeros into the castillo.<br />
<br />
MOVEMENT RULES:<br />
<br />
- Some cards allow you to move caballeros that are already placed on the map. You may move these caballeros to ANY other region on the map, except the King's region. You can move even them into the castillo.<br />
<br />
After everyone has taken a turn, new action cards are revealed and bidding for start player occurs - THE PLAYER WHO PLAYED THE LOWEST CARD LAST ROUND STARTS THE BID<br />
<br />
SCORING ROUNDS (occur after rounds 3, 6 and 9)<br />
<br />
1. Before the regions are scored, each player secretly chooses where they want to place all of their caballeros that are in the castillo. They can go into any region on the map except for the King's region. Players reveal their chosen region at the same time.<br />
<br />
2. The castillo is scored. <br />
<br />
3. Caballeros that were in the castillo are now moved to the chosen region.<br />
<br />
4. Each region is scored.<br />
<br />
SCORING RULES:<br />
<br />
- The purpose of the Grande is to show who owns the region. Only the caballeros are counted when determining majority.<br />
<br />
- The scoreboard in each region shows the points awarded to the players having the most caballeros, 2nd most and 3rd mos caballeros in the region. The player with the most caballeros in a region receives the highest point value for the region shown in the region's scoreboard.<br />
<br />
** In a 2 player game, only the first place points are awarded. In a 3-player game, only the 1st and 2nd place are scored.<br />
<br />
** If TIED: all tied players receive the points in the next lowest position<br />
<br />
BONUS POINTS:<br />
<br />
- If you are the majority player in your home region (where your Grande is located), not tied with any other players, you earn 2 extra points<br />
<br />
- If you are the majority player in the King's region, not tied with any other players, you score 2 extra points.<br />
<br />
OTHER NOTES:<br />
<br />
- You can only use a power card once during the game.<br />
<br />
- When a card triggers special scoring during the game, all regions of the specified point-value must be scored, i.e. all 5-point regions, all 4-point regions, etc.<br />
<br />
- The King's Card is always one of the 5 cards revealed at the start of each round.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_art:_img_directory&diff=11682
Game art: img directory
2022-01-26T18:51:29Z
<p>Een: /* Shrink images */ Add pngquant</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Requested images ==<br />
<br />
The following images are requested by BGA:<br />
<br />
;game_box.png<br />
* It is displayed on the main site on the game description page and when creating a table (280x280 px).<br />
* It should be a 3D image of a physical copy of the game box as it appears in an online shop.<br />
* It is better to take the version of the game that is coherent with the game art used in the adaptation, and from the original publisher of the game.<br />
* The background of the image must be transparent.<br />
* If you don't have a 3D version of the game box, you can use the following website to create one: http://www.3d-pack.com/<br />
<br />
;game_box180.png<br />
;game_box75.png<br />
<br />
* Don't modify these images, they are auto generated by "Reload game box image" action. If you have another copy of your source make sure you update you copy of these files after they have been generated and not override with old copied.<br />
<br />
;game_icon.png<br />
<br />
* It is the icon displayed in the lists of games and tables (50x50 px).<br />
* The objective of this icon is to make the game recognizable among the other games. A good idea is to take a part of the game cover that is distinctive (ex: the game title).<br />
* This one does not have to be transparent. This image should not have a border <br />
<br />
;publisher.png<br />
* It is the logo of the publisher of the game, displayed on the game description page.<br />
* The width must be 150 px. The height can be anything (reasonable). The image could be transparent.<br />
<br />
;publisher2.png (optional)<br />
* If the game has been co-published by 2 publishers, you should upload a second image named "publisher2.png" (same characteristics as the first one).<br />
<br />
;game_banner.jpg<br />
* size 1386x400px<br />
* should not contain any text; representative of the atmosphere of the game such as a cover element or communication image; the box image covering the banner on the left should stand out<br />
<br />
;game_displayX.jpg (X an integer between 0 and 9)<br />
* height between 400px and 760px, width maximum 1.5 x height;<br />
* the idea is to make players want to play the game, so it could be a zoomed card, some detail of the board, an overview of an ongoing physical game... but NOT a screenshot of the BGA adaptation since there is already the "see game in action" replay for that<br />
<br />
'''Important''': when you modify these images, you MUST click on "Reload game box image" from the Control Panel in order your update can be taken into account.<br />
<br />
== Game art ==<br />
<br />
You must upload in img directory all images of your game interface.<br />
<br />
=== Images naming constraints ===<br />
<br />
To be correctly deployed your images file names should not contain spaces or parentheses.<br />
<br />
=== Images loading ===<br />
<br />
'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.<br />
<br />
Note that you can tune the way images are loaded with Javascript method "dontPreloadImage" (see [[Game_interface_logic:_yourgamename.js|Game Interface Logic]]).<br />
<br />
General recommendation it to have no more than dozen of image files, 2Mb max each. However if there is heavy game resources specific to a player (i.e. player board of specific color or set of cards) it is better to separate them and "don't pre-load" since in any given game only some of them will be used.<br />
<br />
=== Images format ===<br />
<br />
You can use these image formats while building your game interface:<br />
;jpg images<br />
<br />
should be used for non-transparent images. Jpg are usually lighter than Pngs, so please choose Jpg for big pictures (ex: game board, cards) when you don't need transparency to accelerate game load. You don't need transparency for rounded card corners, it can be done using css.<br />
<br />
;png images<br />
<br />
should be used for images with transparency, such as non-square tokens, meeples, etc (combined into sprite).<br />
<br />
;gif images<br />
<br />
can be used for animated images. This is not recommended to use gif animated images as they can upset players, but for some specific interface element this could be useful.<br />
<br />
;svg images<br />
<br />
svg images can be really efficient for icons or abstract images<br />
<br />
=== Use background-size ===<br />
<br />
In order to allow for players to use the browser zoom without your images becoming pixelated, it's recommended to use higher resolution images than needed for the normal display of your interface, and to use the css property '''background-size''' to fit the image to the size you need for your interface.<br />
<br />
=== Use CSS Sprites ===<br />
<br />
To limit the number of images load and make the game load faster, you must use CSS sprites, i.e. you must gather several images in a single one. However, there are limitations. Do not make any CSS image sprite with dimensions that exceed 4096x4096 pixels or it will not work on mobile devices (Android max texture size is 4096 pixels, test your own browser at [http://webglreport.com/ WebGL Report]).<br />
<br />
To learn more on CSS Sprites:<br />
* [http://www.w3schools.com/css/css_image_sprites.asp CSS sprites (W3C documentation)].<br />
* [[Game interface stylesheet: yourgamename.css]]<br />
<br />
'''Important:''' the maximum image size should be 4096x4096 (otherwise, some devices may not display parts of the image, see https://stackoverflow.com/questions/34682482/what-is-the-maximum-sprite-sheet-size-i-can-use-for-android-devices)<br />
<br />
Tools:<br />
* Sprite Generator https://www.toptal.com/developers/css/sprite-generator/<br />
<br />
=== Shrink images ===<br />
<br />
If you get high resolution images from publisher you need to shrink them since web display requires much lower resolution than printing.<br />
<br />
* Shrink images size without visible loss of quality <br />
** Offline tool for PNG: https://pngquant.org/ <br />
** Online tools for PNG/JPG: https://tinypng.com/ or http://www.iloveimg.com/ or https://squoosh.app/<br />
<br />
== Image Manipulation Tools ==<br />
<br />
You have no choice but to use one of the image manipulating tools to create a successful game adaptation, you would have to<br />
deal with<br />
* Converting to supported formats<br />
* Adding transparency <br />
* Stitching<br />
* Shrinking with no quality loss<br />
* Resizing<br />
<br />
For that you need a good tools, recommended tools (if you know more add them here)<br />
* Gimp (all platforms) - general GUI image editor<br />
* Paint.net (Windows) - general GUI image editor<br />
* ImageMagic (All platforms) - https://www.imagemagick.org/script/download.php - command line image editor, great for mass manipulations and scripting<br />
<br />
<br />
=== Examples ===<br />
<br />
<br />
PDF to png convertion (linux)<br />
gs -sDEVICE=pngalpha -o output.png -r600 -dDownScaleFactor=3 input.pdf <br />
<br />
PSD Extraction (image magic - CMYK to sRBG - one layer per file)<br />
for i in *.psd; do convert $i -profile /usr/share/color/icc/colord/sRGB.icc `basename $i .psd`.png; done;<br />
<br />
<br />
Tiling<br />
montage -colorspace sRGB -density 300 *.png -tile 6 -background transparent ../tokens.png<br />
<br />
PDF scrabber (linux) - extract all graphics file from pdf<br />
pdfimages my.pdf prefix-<br />
<br />
<br />
=== Online tools ===<br />
<br />
PSD extraction (adobe file format)<br />
<br />
https://www.photopea.com/<br />
<br />
<br />
Seamless background (for tiled background wallpaper)<br />
<br />
https://www.imgonline.com.ua/eng/make-seamless-texture-result.php</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Studio_FAQ&diff=11647
Studio FAQ
2022-01-24T08:37:30Z
<p>Een: php version + missing email should write to studio</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is a place where we will collect and answer frequently asked questions.<br />
<br />
== What is the PHP reference version? ==<br />
<br />
Your game module should be compatible with PHP 7.4.<br />
<br />
== What should I use to access the files through SFTP? ==<br />
<br />
There is a lot of tools to do that. Use the one you are the most comfortable with.<br />
<br />
On Linux Gnome, you can for example use the 'Connect to server' function of the Nautilus file management system, or use sshfs.<br />
<br />
On Windows, there is for example the [http://winscp.net/ WinSCP client].<br />
<br />
See [[Tools_and_tips_of_BGA_Studio#File_Sync]] for more details.<br />
<br />
== I can't edit the files in my game directory, it looks like they are readonly. What's happening? ==<br />
<br />
You can lose access sometimes if you add another developer as read/write or admin.<br />
<br />
Maybe there is a maintenance operation underway.<br />
<br />
If you don't get access back after some time (say one or two hours), please post on dev forum.<br />
<br />
If you are still an admin for your game, re-add yourself as admin - it restores your permissions.<br />
<br />
== What is the working language on BGA studio? ==<br />
<br />
Working language is '''English'''.<br />
<br />
Variables and functions must be named with English words.<br />
<br />
Comments must be written in English.<br />
<br />
Game interface strings and game logs must be written in English.<br />
<br />
== How can I provide translation in my language? == <br />
<br />
The community will translate the game in all language after the game release with the collaborative translation interface can be used to translate into other languages.<br />
<br />
Check [[Translations]] to see how to make your game translatable.<br />
<br />
== I updated the images in the 'img' folder of my game, but they don't show? ==<br />
<br />
'''Concerning game_box.png, game_icon.png and publisher.png''':<br />
You must use "Reload game box image" function from "Control Panel / Manage Games / Your game" to make your change visible.<br />
<br />
'''Concerning other images''':<br />
Other images used during the game are immediately available without any action.<br />
If the images still don't show after that, please try emptying your browser cache and reloading the page (i.e. press reload holding Ctrl button).<br />
<br />
== I added some game options / some game statistics / some game infos but they don't show? ==<br />
<br />
When you modify one of these 3 files, you need to use the corresponding update action from "Control Panel / Manage Games / Your Game" in order we can take this information into account.<br />
<br />
== Should I use images free from copyright? ==<br />
<br />
If you are developing a game in the public domain, yes (or you can make your own if you feel it's better). <br />
<br />
If you are developing a game for which we have a licence, we will usually provide art files from the publisher.<br />
<br />
You can also used shared images provided by boardgame arena - logos, some action buttons, card, meeples, decks.<br />
<br />
== I registered on Studio but did not receive email ==<br />
<br />
If you using standard email address (such as gmail, yahoo, outlook) its in junk folder, search for "bga".<br />
<br />
If you use some proprietary email address, it possible that your mail server denies emails from bga, in this case write to studio@boardgamearena.com to request an admin to resend the email (please specify the login name you have chosen). Don't attempt to register again with same email, it likely will fail again. But if you have alternative standard email account use it instead.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=First_steps_with_BGA_Studio&diff=11626
First steps with BGA Studio
2022-01-21T18:05:14Z
<p>Een: /* Connect to your SFTP folder */ Update example games list</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Connect to the BGA Studio website ==<br />
<br />
Go to BGA Studio website:<br />
http://studio.boardgamearena.com<br />
<br />
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.<br />
<br />
If you don't have account see [[How to join BGA developer team?]]<br />
<br />
== Create a new game project ==<br />
<br />
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.<br />
<br />
Your first "game" should be one of the tutorials, so your project name should be something like "tutorialbob".<br />
<br />
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]]<br />
section "Select a First Game"<br />
<br />
For reference top bar studio links<br />
* AVAILABLE LICENSES - list of all available licenses (not public domain) - http://en.studio.boardgamearena.com/#!licensing<br />
* STUDIO PROJECTS - list of all registered studio projects - http://en.studio.boardgamearena.com/#!projects <br />
* CONTROL PANEL - manage projects - http://en.studio.boardgamearena.com/#!controlpanel<br />
<br />
== Connect to your SFTP folder == <br />
<br />
From the initial email from the Studio you get:<br />
* the name of the SFTP server to connect to<br />
* your SFTP login and password<br />
<br />
Using this information:<br />
# 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]])<br />
# Check that your remote home folder contains one folder for two example games (reversi, hearts). If you have already created a new game project, one additional folder should be in your "home" folder.<br />
# 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...)<br />
<br />
== Let's code! ==<br />
<br />
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.<br />
<br />
# To launch your game from Studio go to Studio -> Control Panel -> Manage games -> <your_game> -> <your_game_page> -> Play now<br />
# Use the 'I want between X and X' players to tick down the maximum players number to the minimum<br />
# 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.<br />
# 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.<br />
# Go back to your browser and refresh, check that the game zone has updated.<br />
# 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]]<br />
# 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.<br />
# Switch to your game folder, go into the img folder and overwrite your game_box.png file with another image.<br />
# Go back to your browser, '''empty your browser cache''', then refresh the page, and check that the game box image has been updated.<br />
<br />
Then you can modify the provided skeleton and begin to develop your game :)<br />
<br />
== Commit your changes ==<br />
<br />
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.<br />
<br />
You can automatically commit your sources in the repository from "Control Panel / Manage Games / Your game / Commit my modifications now". Then:<br />
<br />
# Enter your commit comment (such as 'My first commit') then hit the 'Submit' button;<br />
# Check the log for errors, it should end with the following lines:<br />
<br />
Transmitting file data .<br />
Committed revision #revision number#.<br />
HAL says: done.<br />
<br />
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]]<br />
<br />
== That's all! ==<br />
<br />
Now you know about the basics of updating your game on BGA Studio and testing your changes.<br />
<br />
Now you can select one of the tutorials to play with and start coding.<br />
<br />
For links to tutorials and ALL studio documentation see [[Studio]].</div>
Een
http://en.doc.boardgamearena.com/index.php?title=BGA_Studio_Guidelines&diff=11461
BGA Studio Guidelines
2022-01-18T15:26:26Z
<p>Een: /* Game technical quality */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
= BGA Studio Guidelines = <br />
<br />
Originally From: https://www.slideshare.net/boardgamearena/bga-studio-guidelines<br />
<br />
<br />
<br />
== Why guidelines? ==<br />
More and more game publishers are choosing Board Game Arena for their game adaptations because the quality of these adaptations is high.<br />
If we want to continue to have nice games in the future, we have to make sure that every game published in the BGA platform is matching the quality standards of BGA.<br />
These guidelines are here to help you to make your game easy to use by BGA players, and to make sure its going to be validated by the game publisher.<br />
<br />
== General guidelines == <br />
The 3 main important guidelines <br />
* If a player knows the real board game, they should be able to play your adaptation with no learning.<br />
* Fidelity to the original game is an absolute requirement.<br />
* Don't try to create a video game: make your game interface as close as possible to how the original board game looks like.<br />
<br />
== Game layout ==<br />
=== I-1 Don't hide game elements ===<br />
<br />
Many board games have a lot of material to display, and computer screens are sometimes too small.<br />
But you are lucky: your game will be on a webpage with a scrolling functionality. <br />
Basically, you always have some more space available .<br />
Don't hide game elements behind menus, submenus, dialogs, etc, but display them directly on the main page.<br />
<br />
Tips: eventually, you can use HTML anchor link to jump between the different elements of the page if the page height is very big. <br />
<br />
Examples:<br />
<br />
In Amyitis, characters cards are elements you don't have to check all the time. Thus, we placed them at the bottom of the page and you have to scroll to see them.<br />
<br />
In Madeira, additional game board are shown at the bottom, but when player needs to use it it moved up.<br />
<br />
Rule: <br />
* If real game has visible elements on the table it should be visible on the main screen or user mini boards on the right<br />
<br />
Exceptions:<br />
* Showing counts of same elements is sufficient<br />
* For decks which can be inspected it permitted to show them on demand<br />
* If some games you can cut off score track and replace with BGA scoring (stars), but keeping it will look nicer (but you have to keep track of score on it as well)<br />
* Its not necessary to show helper cards such as turn overview or scoring overview. It is nice if you can incorporate that as well, but in most cases, '''such elements should not be displayed by default''' (as space should be given in priority to the game itself), and should be made available by '''a gray "Player aid" button (or help icon)''' displaying a popup when clicked, like for example in Marco Polo or Terra Mystica.<br />
<br />
=== I-2 Make it fluid ===<br />
<br />
BGA game interface is «fluid». It means the interface width can vary in order to use extra space on the screen when available.<br />
HTML and CSS give us a lot of possibilities to adapt a web content to a given browser width.<br />
You have to use HTML and CSS:<br />
* To allow players owning a big screen to enjoy the game comfortably without scrolling the page.<br />
* To allow players with a screen of just 1024px <br />
<br />
Tips: for each element of the game, answer this question « how many times during a game do I need to check/use this element? ».Less frequently used elements can be placed below.<br />
You can listen on display resize in JS to do more sophisticated layouts.<br />
<br />
Examples:<br />
<br />
Caylus: when we have a 1024px small width to play the game – even if they have to screen, available buildings are placed scroll on the the right and below the board.<br />
On larger screen, these tiles are placed on the right of the board. This is a very basic usage of the others. « float:left » CSS property.<br />
<br />
=== I-3 Use whiteblocks ===<br />
White blocks are '''div''' HTML element with the '''whiteblock''' class (white and transparent background). This is the recommended way to gather game elements together in your game interface when they are not directly on a board. Whiteblocks helps you to organize the space in order it can be easily understood by players.<br />
<br />
If game contains individual player boards with distinct colors or marking you don't need these boards inside the whiteblock.<br />
<br />
''Tips: you can use a '''h3''' title inside the whiteblock to help players to understand what is inside or to who it belongs.''<br />
<br />
In The Year of the Dragon game interface, with whiteblocks and h3 titles /picture here/<br />
<br />
=== I-4 Use player panels ===<br />
<br />
BGA players are used to look at player panels when they need an information about a player.<br />
Using player panels can allow you to save a lot of space on the main game space. In general, the following information is placed in the player panel:<br />
* Players resources (i.e. small game elements the player is keeping in front of him in the real game).<br />
* Summary information about player (i.e. number of cards in hand, number of cards played...).<br />
* « First player » token.<br />
* Score. <br />
<br />
Player panels in Seasons. /picture/ A lot of useful information can fit into these small spaces :)<br />
<br />
Note: for all games, you must always use the standard BGA score counter (with the star). Players are used to check this counter to see who is winning the game.<br />
<br />
=== I-5 Use status bar actions ===<br />
<br />
When some game action is particular to a specific game state, the good practice is to use a status bar action (HTML link).<br />
Don't try to place some icon in your main gameinterface that will be useless 95% of the time: it takes space and makes the interface more complex to understand. <br />
<br />
Status bar actions in Tobago /picture/<br />
<br />
== Game usability ==<br />
<br />
=== II-1 Use tooltips ===<br />
<br />
With BGA Studio its very easy to associate a tooltip on any element of the game. Each time this is possible: add a tooltip to explain to the players:<br />
* What is this game element?<br />
* What happens if I click on it?<br />
However, tooltips should NOT be used to display dynamic information about the current game to save space on the game interface. <br />
Typically, regular players should be able to play with no tooltips. <br />
However you can display some dynamic stuff if it's available otherwise but just annoying to calculate. For example in Lewis and Clark author asked to put<br />
tooltips of how many river space available ahead of explorer.<br />
If you need to show user why they cannot interact with element show errors instead (when clicking on it).<br />
<br />
Tips: you can place any HTML element in tooltips. So you can make them as rich and beautiful as you need :)<br />
<br />
=== II-2 Use left click only ===<br />
* The whole game should be playable with only simple left button mouse click.<br />
* Context menus should not be used.<br />
* Drag-n-drop should be avoided (if you want to use it anyway, you should make a click based alternative available).<br />
* Mouse icon must change on clickable elements (« cursor:pointer » CSS property). <br />
<br />
=== II-3 Make your interface intuitive ===<br />
If your testers have different opinions about « how to trigger some game action », maybe <br />
the best is to make several options possible for this game action. In the case there is a complex action to do by the player (ex: select some cards, then click on an action button), design your error messages in order they can guide the player(ex : « please select some cards first »).<br />
<br />
''Tips: For complex games, it is simple and useful to highlight the area of the interface where player should focus his attention (using onEnteringState/onLeavingState and CSS class, i.e. 'active_slot').'' <br />
<br />
The Boss: when a player clicks on a card with no selected cubes, the interface tells us to select some cube first.<br />
<br />
=== II-4 Use the gamelog ===<br />
With BGA Studio it is very easy to place sometext (or HTML code) in the gamelog.<br />
Don't hesitate to use the game log.<br />
Players are not always in front of the game page when their opponents are making their moves.<br />
In addition, the computer manipulates game elements faster than you usually do with the real board game and even regular players can get behind of what happened sometimes.<br />
You should be able to understand the « game story » by reading the game log. <br />
<br />
=== II-5 Tell players about automatic actions ===<br />
Very often, during a game you are in a situation where:<br />
* Only one action is possible for the activeplayer, or<br />
* A series of action has to be done (according to the rules) without any players actions.<br />
In these situation, you must or you may trigger these actions automatically.<br />
In any case, you must make sure that players understand what is happening, otherwise they will probably report a bug. <br />
<br />
Stone Age: people are fed automatically at the end of the turn, but players can always see what happened exactly in the gamelog.<br />
<br />
* Use the game log to trace all actions performed automatically. <br />
* Use synchronous notifications handlers to slow down the execution of automatic actions,so that players can understand what is happening.<br />
=== II-6 Avoid move confirmations ===<br />
As a rule of thumb, don't require move confirmation. Confirming a move slows down the user interface and thus, the game flow. You can allow a player to confirm a move if this is a very critical step in a game, and if it is possible to trigger an action by accident. If client interactions are very complex and allow cancellation, the final move can be confirmed with a "Done" button.<br />
<br />
''Hawaii'': Ending a turn is a critical action that happens only 5 times per player in a game. In this case, it is acceptable (and a good idea) to have a confirmation dialog.<br />
<br />
''Hive'': Each move has to be confirmed with click on the location because it is very easy to click by accident.<br />
<br />
''Russian Railroads'': Each move involves multiple interactions and can contains dozens of subactions. When the player is done "planning" they presses a "Done" button to submit the move to the server.<br />
<br />
''Race for the Galaxy'': There is a card that allows players to draw two cards and discard one card before the Development phase. This requires confirmation when the player selects a development card to discard, as they often means to build that development card instead.<br />
<br />
=== II-7 Translatable interface ===<br />
With BGA Studio its very easy to translate your game in any language, using BGA collaborative translation system. Check the FAQ and the example games to learn how to declare your strings so that every message in your code can be managed by the internationalization system. <br />
<br />
Diams 100 % translated in Polish<br />
<br />
=== II-8 Use interactive elements ===<br />
<br />
Interactive elements are tiles, cubes or board areas user can click on to perform an action. The following guidance apply:<br />
* If user click on interactive element either action happens or user get a error message. Try to process error message of client side and not send to server for simple errors, such as player is not active. Please be very specific why user cannot interact with element, i.e.<br />
** This is not your turn<br />
** You cannot build this building because you don't have enough resources<br />
** To select this card you have to select resource first<br />
If you cannot make errors for all elements at least tooltip should explaining when it interactive vs not<br />
<br />
Rule: Every game element should give an explicit error message if clicked at the wrong moment rather than staying silent<br />
<br />
Rule: When user can click on element during this turn it should be highlighted if possible (or non-active element de-highlighted in some way)<br />
<br />
Hightlighting guidelines:<br />
* Apply a class to all active/selectable element, i.e. class can be "selectable", "active_slot", "interactive"<br />
* An CSS element with this class can have special rules, i.e<br />
** outline (use outline, do not use "border" as this changes sizing)<br />
** OR shadow/glow - use box-shadow or filter: drop-shadow for non-standard tokens<br />
** recommended color - white, yellow or blue. Do not use red - this is indication of error rather than prompt for action<br />
** change mouse cursor to action cursor, i.e. cursor: pointer<br />
<br />
De-highlighting guidelines:<br />
* Only use this strategy when there are less inactive element than active<br />
* Apply a class to all non-interactive element, such as "non-interactive"<br />
* In css set special rules<br />
** opacity:0.7 <br />
** OR filter:contrast(0.6) or grayscale<br />
* change cursor, i.e. cursor: not-allowed<br />
<br />
Rule: If state prompt replaces the interaction with element but elements are visible its better to do both (i.e. can select a button OR they can move element on the board)<br />
** Example: In Lewis & Clark game offers gain resources via buttons on state prompt, but user can also click on cubes in supply to do the same action<br />
<br />
=== II-9 Animate moving elements ===<br />
If real game have some elements moving during the game it should also animate in your adaptation<br />
* User gets a resource - move a resource from main board to user mini board<br />
* User buys a card - move card from main display to user board<br />
* User draw a card which is revealed on the display - move card from deck to display, maybe add flippy animation to turn it face up (that requires 3d transformations - that is bonus)<br />
<br />
It is also nice to animation points or coin collection from specific region of the board (even points collection is not normally visible).<br />
<br />
Don't need to overdo animation - its not first player shooter<br />
<br />
=== II-10 Slow down the end of game scoring ===<br />
<br />
This is the climax of the game, building up suspense before revealing the winner... Don't make it too quick! :)<br />
<br />
It's also very helpful if some end of game scoring animations can show where the points are gained, to help players understand (and trust) the scoring.<br />
<br />
To achieve this, you can use synchronous notifications for each step of the scoring to slow down the process, and use this.displayScoring ([[Game_interface_logic:_yourgamename.js#Scoring_animated_display]]) to display a nice points animation in the color of the player over the element of the game granting points for this step of the scoring.<br />
<br />
For a practical example of a game adaptation where scoring has been done with this idea in mind, you can check a game replay of Terra Mystica for the final scoring (this link will fast forward you right there: [https://boardgamearena.com/archive/replay/200901-1002/?table=112192856&player=84819187&comments=426;&goto=341 replay scoring])<br />
<br />
== Original game representation ==<br />
=== III-1 Use the original art===<br />
The less you are modifying the original art of the game, the better.<br />
Its important for publishers that a board game adaptation looks like the real board game. Sometimes it can be useful to modify some elements of the game to save some space on the screen – but try to avoid it.<br />
Tips: if you have not enough space on the screen, reduce the size of the game elements. <br />
Try to make sure they are recognizable for players who played regularly, and add a tooltip to help beginners to figure out what they are. <br />
Gosu : the original cards are used, with tooltips.<br />
<br />
=== III-2 Be careful about player assistance ===<br />
As a rule of thumb, in order to respect the original board games, you should not introduce any player assistance feature.<br />
An assistance must not be introduced if it directly helps the player to figure out if his move is good or bad.<br />
An assistance may be introduced if it can help the payer to figure out what moves are available.<br />
<br />
Gygès: the assistance shows you available moves, but is not alerting you about stupid moves (like the upper left one).<br />
<br />
Note: you can however do a single choice move for a player, i.e passing on a turn if there is nothing user can do; it's quite annoying to wait on a player to pass, while it's the only action that they can do anyways.<br />
<br />
=== III-3 Cancel a move ===<br />
Most players want to have moved cancel or undo. User the following rules to implement it:<br />
* If any information is revealed which was not known before you cannot cancel it<br />
* If this is the end of active player action - you cannot cancel it<br />
* If during player turn multiple actions are required allow cancel or undo, for example - user pick cubes and drops on a building. Selecting cube and building - are two actions, so user should be able to cancel taking cube.<br />
This can be implement using client side states, so cancelling is easy as restoring last server state.<br />
<br />
=== III-4 Available information ===<br />
Every information visible by players in the real game should be accessible in the adaptation. Pay attention to some information like the number of cards in the opponents hand, or the number of remaining cards in the deck. <br />
If it is explicitly forbidden to count cards in the discard pile, this information is not available.<br />
<br />
== Game technical quality ==<br />
=== IV-1 Don't use exotic stuff ===<br />
BGA Studio provides a set of useful tools to build board games adaptations (i.e. card management, confirmation dialog, tooltips,…).<br />
Use them, and don't use exotic libraries, plugins or tricks.<br />
Why? Because BGA Framework will evolve in the future to provide new features to players, and it could make your game incompatible with the new version.<br />
On the contrary, if you are using standard Haggis using BGA standard card stuff, you will enjoy these enhancements without any effort.<br />
If you feel that you really need some exotic thing: don't hesitate to ask us.<br />
<br />
=== IV-2 Make sure you can use what you use ===<br />
<br />
In particular, do not build your game on top of a technical library without checking that licensing allows you (and BGA) to use it.<br />
If you use a library, make sure first that its license is really open (MIT style). Otherwise, we may have to ask you to rework your code to use another library.<br />
In general, please consider that it's always better to minimize dependencies, so if you can avoid using external libraries, all the better.<br />
<br />
=== IV-3 Write in (simple) English ===<br />
Some other person may have to look at your code, such as:<br />
* We (the BGA team), who are here to help you if you need us.<br />
* Some other BGA developer wanting to help you.<br />
For all these reasons, your code must be written in English (variables, methods, comments...).<br />
If English is not your mother tongue don't be afraid: the whole idea here is to be understood, not to write an essay :)<br />
<br />
=== IV-4 Page refresh ===<br />
A page refresh (F5) must allow players to reset the game interface to a stable state at any moment of the game.<br />
BGA Studio framework allows you to do this with the « getAllDatas » PHP method and the « setup » Javascript method.<br />
Note: this « refresh » feature is also quite useful during the development process:)<br />
<br />
=== IV-5 Private information ===<br />
A private game element must be visible only to the player owning it. It must not be visible by his opponents, by any means.<br />
In particular: <br />
* getAllDatas PHP method must not return any element that are hidden from current player, even if the Javascript « setup » method ignores them.<br />
* you must not send via the « notifyAllPlayers » function some information that is hidden from one player (use « notifyPlayer » instead). <br />
<br />
<br />
Hearts: each player is alerted about his new cards using notifyPlayer, and cards from the other players remains secret<br />
<br />
=== IV-6 Game progression ===<br />
Game progression should be as accurate as possible.<br />
Of course, its not always easy (or even possible) to compute game progression, but a vague approximation is better than nothing. <br />
Stone Age: there are 2 different end game conditions (building cards and civilization cards). <br />
Both are taken into account to increase the accuracy of the game progression.<br />
<br />
=== IV-7 Game statistics ===<br />
Using BGA Studio you can define a set of statistics for your game. Statistics will be displayed at the end of the game, and help players to figure out why they win/loose a game, <br />
and what they should improve. Try to choose interesting statistics that distinguish the different strategies for your game, in order it can help players to understand their game. <br />
<br />
Seasons : statistics<br />
<br />
=== IV-8 Namespace recommendations ===<br />
Your game is not working in complete isolation, it's included in a page with a lot of elements around (header, footer, logs, chat, player panels, rankings...)<br />
<br />
So you should pay attention to naming your DOM elements, CSS classes and PHP constants / classes in a way specific to your game in order to avoid namespace collisions (for example you use a selector for a "selected" class in your .js, and there is also an element of the framework outside of your game with a selected class).<br />
<br />
It's recommended to have:<br />
* a wrapper div around your game zone with an id specific to your game ('yourgamename_playzone' for example) and to use it in any xpath selector of your .js<br />
* a prefix for example a trigram for your game that you append to all the css classes of your game ('yrg_selected' for example).<br />
* a prefix or a namespace for your PHP constants or classes.<br />
<br />
Even if everything is working fine today, otherwise your game may break in the future when the framework is updated.<br />
<br />
== Summary ==<br />
These guidelines are here to help you to make sure that the players, the game publisher and the game author are going to enjoy your adaptation of the game. We created these guidelines based on our personal experience (which includes many mistakes along the way) implementing a lot of games on BGA platform. Don't hesitate to contact us if you feel uncomfortable with one of these guidelines in some particular context with your game: these guidelines are here to help and not to prevent you to do smart things, and have fun while programing your game ;)</div>
Een
http://en.doc.boardgamearena.com/index.php?title=BGA_Studio_Guidelines&diff=11460
BGA Studio Guidelines
2022-01-18T15:25:37Z
<p>Een: /* Game technical quality */ warning about libraries and licenses</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
= BGA Studio Guidelines = <br />
<br />
Originally From: https://www.slideshare.net/boardgamearena/bga-studio-guidelines<br />
<br />
<br />
<br />
== Why guidelines? ==<br />
More and more game publishers are choosing Board Game Arena for their game adaptations because the quality of these adaptations is high.<br />
If we want to continue to have nice games in the future, we have to make sure that every game published in the BGA platform is matching the quality standards of BGA.<br />
These guidelines are here to help you to make your game easy to use by BGA players, and to make sure its going to be validated by the game publisher.<br />
<br />
== General guidelines == <br />
The 3 main important guidelines <br />
* If a player knows the real board game, they should be able to play your adaptation with no learning.<br />
* Fidelity to the original game is an absolute requirement.<br />
* Don't try to create a video game: make your game interface as close as possible to how the original board game looks like.<br />
<br />
== Game layout ==<br />
=== I-1 Don't hide game elements ===<br />
<br />
Many board games have a lot of material to display, and computer screens are sometimes too small.<br />
But you are lucky: your game will be on a webpage with a scrolling functionality. <br />
Basically, you always have some more space available .<br />
Don't hide game elements behind menus, submenus, dialogs, etc, but display them directly on the main page.<br />
<br />
Tips: eventually, you can use HTML anchor link to jump between the different elements of the page if the page height is very big. <br />
<br />
Examples:<br />
<br />
In Amyitis, characters cards are elements you don't have to check all the time. Thus, we placed them at the bottom of the page and you have to scroll to see them.<br />
<br />
In Madeira, additional game board are shown at the bottom, but when player needs to use it it moved up.<br />
<br />
Rule: <br />
* If real game has visible elements on the table it should be visible on the main screen or user mini boards on the right<br />
<br />
Exceptions:<br />
* Showing counts of same elements is sufficient<br />
* For decks which can be inspected it permitted to show them on demand<br />
* If some games you can cut off score track and replace with BGA scoring (stars), but keeping it will look nicer (but you have to keep track of score on it as well)<br />
* Its not necessary to show helper cards such as turn overview or scoring overview. It is nice if you can incorporate that as well, but in most cases, '''such elements should not be displayed by default''' (as space should be given in priority to the game itself), and should be made available by '''a gray "Player aid" button (or help icon)''' displaying a popup when clicked, like for example in Marco Polo or Terra Mystica.<br />
<br />
=== I-2 Make it fluid ===<br />
<br />
BGA game interface is «fluid». It means the interface width can vary in order to use extra space on the screen when available.<br />
HTML and CSS give us a lot of possibilities to adapt a web content to a given browser width.<br />
You have to use HTML and CSS:<br />
* To allow players owning a big screen to enjoy the game comfortably without scrolling the page.<br />
* To allow players with a screen of just 1024px <br />
<br />
Tips: for each element of the game, answer this question « how many times during a game do I need to check/use this element? ».Less frequently used elements can be placed below.<br />
You can listen on display resize in JS to do more sophisticated layouts.<br />
<br />
Examples:<br />
<br />
Caylus: when we have a 1024px small width to play the game – even if they have to screen, available buildings are placed scroll on the the right and below the board.<br />
On larger screen, these tiles are placed on the right of the board. This is a very basic usage of the others. « float:left » CSS property.<br />
<br />
=== I-3 Use whiteblocks ===<br />
White blocks are '''div''' HTML element with the '''whiteblock''' class (white and transparent background). This is the recommended way to gather game elements together in your game interface when they are not directly on a board. Whiteblocks helps you to organize the space in order it can be easily understood by players.<br />
<br />
If game contains individual player boards with distinct colors or marking you don't need these boards inside the whiteblock.<br />
<br />
''Tips: you can use a '''h3''' title inside the whiteblock to help players to understand what is inside or to who it belongs.''<br />
<br />
In The Year of the Dragon game interface, with whiteblocks and h3 titles /picture here/<br />
<br />
=== I-4 Use player panels ===<br />
<br />
BGA players are used to look at player panels when they need an information about a player.<br />
Using player panels can allow you to save a lot of space on the main game space. In general, the following information is placed in the player panel:<br />
* Players resources (i.e. small game elements the player is keeping in front of him in the real game).<br />
* Summary information about player (i.e. number of cards in hand, number of cards played...).<br />
* « First player » token.<br />
* Score. <br />
<br />
Player panels in Seasons. /picture/ A lot of useful information can fit into these small spaces :)<br />
<br />
Note: for all games, you must always use the standard BGA score counter (with the star). Players are used to check this counter to see who is winning the game.<br />
<br />
=== I-5 Use status bar actions ===<br />
<br />
When some game action is particular to a specific game state, the good practice is to use a status bar action (HTML link).<br />
Don't try to place some icon in your main gameinterface that will be useless 95% of the time: it takes space and makes the interface more complex to understand. <br />
<br />
Status bar actions in Tobago /picture/<br />
<br />
== Game usability ==<br />
<br />
=== II-1 Use tooltips ===<br />
<br />
With BGA Studio its very easy to associate a tooltip on any element of the game. Each time this is possible: add a tooltip to explain to the players:<br />
* What is this game element?<br />
* What happens if I click on it?<br />
However, tooltips should NOT be used to display dynamic information about the current game to save space on the game interface. <br />
Typically, regular players should be able to play with no tooltips. <br />
However you can display some dynamic stuff if it's available otherwise but just annoying to calculate. For example in Lewis and Clark author asked to put<br />
tooltips of how many river space available ahead of explorer.<br />
If you need to show user why they cannot interact with element show errors instead (when clicking on it).<br />
<br />
Tips: you can place any HTML element in tooltips. So you can make them as rich and beautiful as you need :)<br />
<br />
=== II-2 Use left click only ===<br />
* The whole game should be playable with only simple left button mouse click.<br />
* Context menus should not be used.<br />
* Drag-n-drop should be avoided (if you want to use it anyway, you should make a click based alternative available).<br />
* Mouse icon must change on clickable elements (« cursor:pointer » CSS property). <br />
<br />
=== II-3 Make your interface intuitive ===<br />
If your testers have different opinions about « how to trigger some game action », maybe <br />
the best is to make several options possible for this game action. In the case there is a complex action to do by the player (ex: select some cards, then click on an action button), design your error messages in order they can guide the player(ex : « please select some cards first »).<br />
<br />
''Tips: For complex games, it is simple and useful to highlight the area of the interface where player should focus his attention (using onEnteringState/onLeavingState and CSS class, i.e. 'active_slot').'' <br />
<br />
The Boss: when a player clicks on a card with no selected cubes, the interface tells us to select some cube first.<br />
<br />
=== II-4 Use the gamelog ===<br />
With BGA Studio it is very easy to place sometext (or HTML code) in the gamelog.<br />
Don't hesitate to use the game log.<br />
Players are not always in front of the game page when their opponents are making their moves.<br />
In addition, the computer manipulates game elements faster than you usually do with the real board game and even regular players can get behind of what happened sometimes.<br />
You should be able to understand the « game story » by reading the game log. <br />
<br />
=== II-5 Tell players about automatic actions ===<br />
Very often, during a game you are in a situation where:<br />
* Only one action is possible for the activeplayer, or<br />
* A series of action has to be done (according to the rules) without any players actions.<br />
In these situation, you must or you may trigger these actions automatically.<br />
In any case, you must make sure that players understand what is happening, otherwise they will probably report a bug. <br />
<br />
Stone Age: people are fed automatically at the end of the turn, but players can always see what happened exactly in the gamelog.<br />
<br />
* Use the game log to trace all actions performed automatically. <br />
* Use synchronous notifications handlers to slow down the execution of automatic actions,so that players can understand what is happening.<br />
=== II-6 Avoid move confirmations ===<br />
As a rule of thumb, don't require move confirmation. Confirming a move slows down the user interface and thus, the game flow. You can allow a player to confirm a move if this is a very critical step in a game, and if it is possible to trigger an action by accident. If client interactions are very complex and allow cancellation, the final move can be confirmed with a "Done" button.<br />
<br />
''Hawaii'': Ending a turn is a critical action that happens only 5 times per player in a game. In this case, it is acceptable (and a good idea) to have a confirmation dialog.<br />
<br />
''Hive'': Each move has to be confirmed with click on the location because it is very easy to click by accident.<br />
<br />
''Russian Railroads'': Each move involves multiple interactions and can contains dozens of subactions. When the player is done "planning" they presses a "Done" button to submit the move to the server.<br />
<br />
''Race for the Galaxy'': There is a card that allows players to draw two cards and discard one card before the Development phase. This requires confirmation when the player selects a development card to discard, as they often means to build that development card instead.<br />
<br />
=== II-7 Translatable interface ===<br />
With BGA Studio its very easy to translate your game in any language, using BGA collaborative translation system. Check the FAQ and the example games to learn how to declare your strings so that every message in your code can be managed by the internationalization system. <br />
<br />
Diams 100 % translated in Polish<br />
<br />
=== II-8 Use interactive elements ===<br />
<br />
Interactive elements are tiles, cubes or board areas user can click on to perform an action. The following guidance apply:<br />
* If user click on interactive element either action happens or user get a error message. Try to process error message of client side and not send to server for simple errors, such as player is not active. Please be very specific why user cannot interact with element, i.e.<br />
** This is not your turn<br />
** You cannot build this building because you don't have enough resources<br />
** To select this card you have to select resource first<br />
If you cannot make errors for all elements at least tooltip should explaining when it interactive vs not<br />
<br />
Rule: Every game element should give an explicit error message if clicked at the wrong moment rather than staying silent<br />
<br />
Rule: When user can click on element during this turn it should be highlighted if possible (or non-active element de-highlighted in some way)<br />
<br />
Hightlighting guidelines:<br />
* Apply a class to all active/selectable element, i.e. class can be "selectable", "active_slot", "interactive"<br />
* An CSS element with this class can have special rules, i.e<br />
** outline (use outline, do not use "border" as this changes sizing)<br />
** OR shadow/glow - use box-shadow or filter: drop-shadow for non-standard tokens<br />
** recommended color - white, yellow or blue. Do not use red - this is indication of error rather than prompt for action<br />
** change mouse cursor to action cursor, i.e. cursor: pointer<br />
<br />
De-highlighting guidelines:<br />
* Only use this strategy when there are less inactive element than active<br />
* Apply a class to all non-interactive element, such as "non-interactive"<br />
* In css set special rules<br />
** opacity:0.7 <br />
** OR filter:contrast(0.6) or grayscale<br />
* change cursor, i.e. cursor: not-allowed<br />
<br />
Rule: If state prompt replaces the interaction with element but elements are visible its better to do both (i.e. can select a button OR they can move element on the board)<br />
** Example: In Lewis & Clark game offers gain resources via buttons on state prompt, but user can also click on cubes in supply to do the same action<br />
<br />
=== II-9 Animate moving elements ===<br />
If real game have some elements moving during the game it should also animate in your adaptation<br />
* User gets a resource - move a resource from main board to user mini board<br />
* User buys a card - move card from main display to user board<br />
* User draw a card which is revealed on the display - move card from deck to display, maybe add flippy animation to turn it face up (that requires 3d transformations - that is bonus)<br />
<br />
It is also nice to animation points or coin collection from specific region of the board (even points collection is not normally visible).<br />
<br />
Don't need to overdo animation - its not first player shooter<br />
<br />
=== II-10 Slow down the end of game scoring ===<br />
<br />
This is the climax of the game, building up suspense before revealing the winner... Don't make it too quick! :)<br />
<br />
It's also very helpful if some end of game scoring animations can show where the points are gained, to help players understand (and trust) the scoring.<br />
<br />
To achieve this, you can use synchronous notifications for each step of the scoring to slow down the process, and use this.displayScoring ([[Game_interface_logic:_yourgamename.js#Scoring_animated_display]]) to display a nice points animation in the color of the player over the element of the game granting points for this step of the scoring.<br />
<br />
For a practical example of a game adaptation where scoring has been done with this idea in mind, you can check a game replay of Terra Mystica for the final scoring (this link will fast forward you right there: [https://boardgamearena.com/archive/replay/200901-1002/?table=112192856&player=84819187&comments=426;&goto=341 replay scoring])<br />
<br />
== Original game representation ==<br />
=== III-1 Use the original art===<br />
The less you are modifying the original art of the game, the better.<br />
Its important for publishers that a board game adaptation looks like the real board game. Sometimes it can be useful to modify some elements of the game to save some space on the screen – but try to avoid it.<br />
Tips: if you have not enough space on the screen, reduce the size of the game elements. <br />
Try to make sure they are recognizable for players who played regularly, and add a tooltip to help beginners to figure out what they are. <br />
Gosu : the original cards are used, with tooltips.<br />
<br />
=== III-2 Be careful about player assistance ===<br />
As a rule of thumb, in order to respect the original board games, you should not introduce any player assistance feature.<br />
An assistance must not be introduced if it directly helps the player to figure out if his move is good or bad.<br />
An assistance may be introduced if it can help the payer to figure out what moves are available.<br />
<br />
Gygès: the assistance shows you available moves, but is not alerting you about stupid moves (like the upper left one).<br />
<br />
Note: you can however do a single choice move for a player, i.e passing on a turn if there is nothing user can do; it's quite annoying to wait on a player to pass, while it's the only action that they can do anyways.<br />
<br />
=== III-3 Cancel a move ===<br />
Most players want to have moved cancel or undo. User the following rules to implement it:<br />
* If any information is revealed which was not known before you cannot cancel it<br />
* If this is the end of active player action - you cannot cancel it<br />
* If during player turn multiple actions are required allow cancel or undo, for example - user pick cubes and drops on a building. Selecting cube and building - are two actions, so user should be able to cancel taking cube.<br />
This can be implement using client side states, so cancelling is easy as restoring last server state.<br />
<br />
=== III-4 Available information ===<br />
Every information visible by players in the real game should be accessible in the adaptation. Pay attention to some information like the number of cards in the opponents hand, or the number of remaining cards in the deck. <br />
If it is explicitly forbidden to count cards in the discard pile, this information is not available.<br />
<br />
== Game technical quality ==<br />
=== IV-1 Don't use exotic stuff ===<br />
BGA Studio provides a set of useful tools to build board games adaptations (i.e. card management, confirmation dialog, tooltips,…).<br />
Use them, and don't use exotic libraries, plugins or tricks.<br />
Why? Because BGA Framework will evolve in the future to provide new features to players, and it could make your game incompatible with the new version.<br />
On the contrary, if you are using standard Haggis using BGA standard card stuff, you will enjoy these enhancements without any effort.<br />
If you feel that you really need some exotic thing: don't hesitate to ask us.<br />
<br />
=== IV-2 Make sure you can use what you use ===<br />
<br />
In particular, do not build your game on top of a technical library without checking that licensing allows you (and BGA) to use it.<br />
If you use a library, make sure first that its license is really open (MIT style). Otherwise, we may have to ask you to rework your code to use another library.<br />
In general, please consider that it's always better to minimize dependencies, so if you can avoid using external libraries, all the better.<br />
<br />
=== IV-3 Write in (simple) English ===<br />
Some other person may have to look at your code, such as:<br />
* We (the BGA team), who are here to help you if you need us.<br />
* Some other BGA developer wanting to help you.<br />
For all these reasons, your code must be written in English (variables, methods, comments...).<br />
If English is not your mother tongue don't be afraid: the whole idea here is to be understood, not to write an essay :)<br />
<br />
=== IV-4 Page refresh ===<br />
A page refresh (F5) must allow players to reset the game interface to a stable state at any moment of the game.<br />
BGA Studio framework allows you to do this with the « getAllDatas » PHP method and the « setup » Javascript method.<br />
Note: this « refresh » feature is also quite useful during the development process:)<br />
<br />
=== IV-5 Private information ===<br />
A private game element must be visible only to the player owning it. It must not be visible by his opponents, by any means.<br />
In particular: <br />
* getAllDatas PHP method must not return any element that are hidden from current player, even if the Javascript « setup » method ignores them.<br />
* you must not send via the « notifyAllPlayers » function some information that is hidden from one player (use « notifyPlayer » instead). <br />
<br />
<br />
Hearts: each player is alerted about his new cards using notifyPlayer, and cards from the other players remains secret<br />
<br />
=== IV-5 Game progression ===<br />
Game progression should be as accurate as possible.<br />
Of course, its not always easy (or even possible) to compute game progression, but a vague approximation is better than nothing. <br />
Stone Age: there are 2 different end game conditions (building cards and civilization cards). <br />
Both are taken into account to increase the accuracy of the game progression.<br />
<br />
=== IV-6 Game statistics ===<br />
Using BGA Studio you can define a set of statistics for your game. Statistics will be displayed at the end of the game, and help players to figure out why they win/loose a game, <br />
and what they should improve. Try to choose interesting statistics that distinguish the different strategies for your game, in order it can help players to understand their game. <br />
<br />
Seasons : statistics<br />
<br />
=== IV-7 Namespace recommendations ===<br />
Your game is not working in complete isolation, it's included in a page with a lot of elements around (header, footer, logs, chat, player panels, rankings...)<br />
<br />
So you should pay attention to naming your DOM elements, CSS classes and PHP constants / classes in a way specific to your game in order to avoid namespace collisions (for example you use a selector for a "selected" class in your .js, and there is also an element of the framework outside of your game with a selected class).<br />
<br />
It's recommended to have:<br />
* a wrapper div around your game zone with an id specific to your game ('yourgamename_playzone' for example) and to use it in any xpath selector of your .js<br />
* a prefix for example a trigram for your game that you append to all the css classes of your game ('yrg_selected' for example).<br />
* a prefix or a namespace for your PHP constants or classes.<br />
<br />
Even if everything is working fine today, otherwise your game may break in the future when the framework is updated.<br />
<br />
== Summary ==<br />
These guidelines are here to help you to make sure that the players, the game publisher and the game author are going to enjoy your adaptation of the game. We created these guidelines based on our personal experience (which includes many mistakes along the way) implementing a lot of games on BGA platform. Don't hesitate to contact us if you feel uncomfortable with one of these guidelines in some particular context with your game: these guidelines are here to help and not to prevent you to do smart things, and have fun while programing your game ;)</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_database_model:_dbmodel.sql&diff=11422
Game database model: dbmodel.sql
2022-01-12T15:09:56Z
<p>Een: /* Default tables */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
In this file you specify the database schema of your game.<br />
<br />
This file contains SQL queries that will be executed during the creation of your game table.<br />
<br />
'''Note:''' you can't change the database schema during the game.<br />
<br />
== Create your schema ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
Example: Deck component, see [[Deck]]<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `card` (<br />
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`card_type` varchar(16) NOT NULL,<br />
`card_type_arg` int(11) NOT NULL,<br />
`card_location` varchar(16) NOT NULL,<br />
`card_location_arg` int(11) NOT NULL,<br />
PRIMARY KEY (`card_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `token` (<br />
`token_key` varchar(32) NOT NULL,<br />
`token_location` varchar(32) NOT NULL,<br />
`token_state` int(10),<br />
PRIMARY KEY (`token_key`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
</pre><br />
<br />
Rules you should follow:<br />
<br />
* Do not overcomplicate, you are dealing with games with 50-500 pieces!<br />
** If you have 5 tables for a card game with 30 cards - it is overkill<br />
* Database should only be storing dynamic data, all static data should be stored in material.php.inc<br />
** 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.<br />
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc<br />
** Example: do not create columns like Counry1, Country2, Country3, ...<br />
* Do not store translatable string in the database, use integer number of "ident" to access properties<br />
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"<br />
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections<br />
<br />
Example of method handling database query:<br />
<br />
<pre><br />
// Set token state<br />
function setTokenState($token_key, $state) {<br />
self::checkState($state); // ensure state is number<br />
self::checkKey($token_key); // ensure key is alphanum<br />
$sql = "UPDATE " . $this->table;<br />
$sql .= " SET token_state='$state'";<br />
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before<br />
self::DbQuery($sql);<br />
return $state;<br />
}<br />
</pre><br />
<br />
== Default tables ==<br />
<br />
By default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.<br />
<br />
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).<br />
<br />
=== The '''player''' table ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';<br />
</pre><br />
<br />
The commonly used columns of default "player" table are:<br />
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)<br />
* <strong>player_id</strong> (int)<br />
* <strong>player_name</strong>: (note: it is better to access this data with getActivePlayerName() or loadPlayersBasicInfos() methods)<br />
* <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.<br />
* <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]])<br />
<br />
* <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.<br />
<br />
<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>&nbsp;&#128521;<br />
<br />
See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.<br />
<br />
== CREATE TABLES ==<br />
you can create tables, using engine InnoDB<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `hands` <br />
(<br />
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT, <br />
`player_id` TINYINT(1) NOT NULL,<br />
`1` BOOL NOT NULL DEFAULT 1, <br />
`2` BOOL NOT NULL DEFAULT 1, <br />
`3` BOOL NOT NULL DEFAULT 1, <br />
`4` BOOL NOT NULL DEFAULT 1, <br />
`5` BOOL NOT NULL DEFAULT 1, <br />
`6` BOOL NOT NULL DEFAULT 1, <br />
`7` BOOL NOT NULL DEFAULT 1, <br />
PRIMARY KEY (`id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
'''Note''': if you put comments, you cannot do it in the same line as code.<br />
<br />
Example:<br />
<br />
<pre><br />
`3` BOOL NOT NULL DEFAULT 1, -- activated or not<br />
</pre><br />
<br />
will also comment out `3` BOOL, and that code will not be executed.<br />
<br />
== PHP ==<br />
Database initialization should be in function setupNewGame() in 'gamename.game.php'.<br />
<br />
Database schema migration should be in function upgradeTableDb(), see below.<br />
<br />
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<br />
which will cause issues. The only time you can do such queries from php is in the upgradeTableDb method<br />
<br />
<br />
== Errors Log ==<br />
To trace Database creation check the logs that you can access in /admin/studio.<br />
<br />
== Post-release database modification ==<br />
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]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_database_model:_dbmodel.sql&diff=11421
Game database model: dbmodel.sql
2022-01-12T15:09:22Z
<p>Een: /* Default tables */ emphasis on not modifying the framework table</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
In this file you specify the database schema of your game.<br />
<br />
This file contains SQL queries that will be executed during the creation of your game table.<br />
<br />
'''Note:''' you can't change the database schema during the game.<br />
<br />
== Create your schema ==<br />
<br />
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.<br />
<br />
'''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.<br />
<br />
Example: Deck component, see [[Deck]]<br />
<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `card` (<br />
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,<br />
`card_type` varchar(16) NOT NULL,<br />
`card_type_arg` int(11) NOT NULL,<br />
`card_location` varchar(16) NOT NULL,<br />
`card_location_arg` int(11) NOT NULL,<br />
PRIMARY KEY (`card_id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `token` (<br />
`token_key` varchar(32) NOT NULL,<br />
`token_location` varchar(32) NOT NULL,<br />
`token_state` int(10),<br />
PRIMARY KEY (`token_key`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8;<br />
</pre><br />
<br />
Rules you should follow:<br />
<br />
* Do not overcomplicate, you are dealing with games with 50-500 pieces!<br />
** If you have 5 tables for a card game with 30 cards - it is overkill<br />
* Database should only be storing dynamic data, all static data should be stored in material.php.inc<br />
** 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.<br />
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc<br />
** Example: do not create columns like Counry1, Country2, Country3, ...<br />
* Do not store translatable string in the database, use integer number of "ident" to access properties<br />
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"<br />
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections<br />
<br />
Example of method handling database query:<br />
<br />
<pre><br />
// Set token state<br />
function setTokenState($token_key, $state) {<br />
self::checkState($state); // ensure state is number<br />
self::checkKey($token_key); // ensure key is alphanum<br />
$sql = "UPDATE " . $this->table;<br />
$sql .= " SET token_state='$state'";<br />
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before<br />
self::DbQuery($sql);<br />
return $state;<br />
}<br />
</pre><br />
<br />
== Default tables ==<br />
<br />
'''IMPORTANT''': by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.<br />
<br />
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).<br />
<br />
=== The '''player''' table ===<br />
<br />
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.<br />
<br />
Example:<br />
<pre><br />
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';<br />
</pre><br />
<br />
The commonly used columns of default "player" table are:<br />
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)<br />
* <strong>player_id</strong> (int)<br />
* <strong>player_name</strong>: (note: it is better to access this data with getActivePlayerName() or loadPlayersBasicInfos() methods)<br />
* <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.<br />
* <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]])<br />
<br />
* <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.<br />
<br />
<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>&nbsp;&#128521;<br />
<br />
See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.<br />
<br />
== CREATE TABLES ==<br />
you can create tables, using engine InnoDB<br />
<pre><br />
CREATE TABLE IF NOT EXISTS `hands` <br />
(<br />
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT, <br />
`player_id` TINYINT(1) NOT NULL,<br />
`1` BOOL NOT NULL DEFAULT 1, <br />
`2` BOOL NOT NULL DEFAULT 1, <br />
`3` BOOL NOT NULL DEFAULT 1, <br />
`4` BOOL NOT NULL DEFAULT 1, <br />
`5` BOOL NOT NULL DEFAULT 1, <br />
`6` BOOL NOT NULL DEFAULT 1, <br />
`7` BOOL NOT NULL DEFAULT 1, <br />
PRIMARY KEY (`id`)<br />
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;<br />
</pre><br />
<br />
'''Note''': if you put comments, you cannot do it in the same line as code.<br />
<br />
Example:<br />
<br />
<pre><br />
`3` BOOL NOT NULL DEFAULT 1, -- activated or not<br />
</pre><br />
<br />
will also comment out `3` BOOL, and that code will not be executed.<br />
<br />
== PHP ==<br />
Database initialization should be in function setupNewGame() in 'gamename.game.php'.<br />
<br />
Database schema migration should be in function upgradeTableDb(), see below.<br />
<br />
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<br />
which will cause issues. The only time you can do such queries from php is in the upgradeTableDb method<br />
<br />
<br />
== Errors Log ==<br />
To trace Database creation check the logs that you can access in /admin/studio.<br />
<br />
== Post-release database modification ==<br />
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]]</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_yourgamename.game.php&diff=10195
Main game logic: yourgamename.game.php
2021-11-17T16:38:24Z
<p>Een: /* Undo moves */ document reloadState()</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.<br />
<br />
== File Structure ==<br />
<br />
The details of how the file is structured are described directly with comments in the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* Constructor: where you define global variables.<br />
* setupNewGame: initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.<br />
* getAllDatas: where you retrieve all game data during a complete reload of the game. Returned value must include ['players'][playerId]['score'] for scores to populate when F5 is pressed.<br />
* getGameProgression: where you compute the game progression indicator. Returns a number indicating percent of progression (0-100)<br />
* Utility functions: your utility functions.<br />
* Player actions: the entry points for players actions ([https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php more info here]). <br />
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).<br />
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).<br />
* zombieTurn: what to do it's the turn of a zombie player.<br />
* upgradeTableDb: function to migrate database if you change it after release on production.<br />
<br />
== Accessing player information ==<br />
<br />
'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!<br />
<br />
<br />
; getPlayersNumber()<br />
: Returns the number of players playing at the table<br />
: Note: doesn't work in setupNewGame (use count($players) instead).<br />
<br />
; getActivePlayerId()<br />
: Get the "active_player", whatever what is the current state type.<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getActivePlayerName()<br />
: Get the "active_player" name<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getPlayerNameById($player_id)<br />
: Get the name by id<br />
<br />
; getPlayerColorById($player_id)<br />
: Get the color by id<br />
<br />
; getPlayerNoById($player_id)<br />
: Get 'player_no' (number) by id<br />
<br />
<br />
; loadPlayersBasicInfos()<br />
: Get an associative array with generic data about players (ie: not game specific data).<br />
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.<br />
: <code>array_keys($this->loadPlayersBasicInfos())</code> will therefore returns an array containing players id<br />
: The content of each value is:<br />
: * player_name - the name of the player<br />
: * player_color (ex: ff0000) - the color code of the player<br />
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3<br />
<br />
<pre><br />
$players = $this->loadPlayersBasicInfos();<br />
foreach ($players as $player_id => $info) {<br />
$player_color = $info['player_color'];<br />
...<br />
}<br />
</pre><br />
Note: if you want array of player ids only you can do this:<br />
$player_ids = array_keys($this->loadPlayersBasicInfos()); <br />
<br />
; getCurrentPlayerId()<br />
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).<br />
: '''Be careful''': This is not necessarily the active player!<br />
: In general, you shouldn't use this method, unless you are in "multiplayer" state.<br />
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).<br />
<br />
; getCurrentPlayerName()<br />
: Get the "current_player" name<br />
: Be careful using this method (see above).<br />
<br />
; getCurrentPlayerColor()<br />
: Get the "current_player" color<br />
: Be careful using this method (see above).<br />
<br />
; isCurrentPlayerZombie()<br />
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.<br />
<br />
; isSpectator()<br />
: Check the "current_player" spectator status. If true, the user accessing the game is a spectator (not part of the game). For this user, the interface should display all public information, and no private information (like a friend sitting at the same table as players and just spectating the game).<br />
<br />
; getActivePlayerColor()<br />
: This function does not seems to exist in API, if you need it here is implementation<br />
function getActivePlayerColor() {<br />
$player_id = self::getActivePlayerId();<br />
$players = self::loadPlayersBasicInfos();<br />
if (isset($players[$player_id]))<br />
return $players[$player_id]['player_color'];<br />
else<br />
return null;<br />
}<br />
; isPlayerZombie($player_id)<br />
: This method does not exists, but if you need it it looks like this<br />
protected function isPlayerZombie($player_id) {<br />
$players = self::loadPlayersBasicInfos();<br />
if (! isset($players[$player_id]))<br />
throw new feException("Player $player_id is not playing here");<br />
<br />
return ($players[$player_id]['player_zombie'] == 1);<br />
}<br />
<br />
== Accessing the database ==<br />
<br />
The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.<br />
<br />
'''IMPORTANT'''<br />
<br />
BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.<br />
<br />
However there are sets of database operation that initite implicit commit (most common mistake is to use "TRUNCATE"), you cannot use these operations during the game, it breaks the unrolling of transactions and will lead to nasty issues<br />
(https://mariadb.com/kb/en/sql-statements-that-cause-an-implicit-commit).<br />
<br />
<br />
; DbQuery( $sql )<br />
: This is the generic method to access the database.<br />
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database.<br />
: You should use it for UPDATE/DELETE/REPLACE/INSERT queries. For SELECT queries, the specialized methods below are much better.<br />
<br />
; getUniqueValueFromDB( $sql )<br />
: Returns a unique value from DB or null if no value is found.<br />
: $sql must be a SELECT query.<br />
: Raise an exception if more than 1 row is returned.<br />
<br />
; getCollectionFromDB( $sql, $bSingleValue=false )<br />
: Returns an associative array of rows for a sql SELECT query.<br />
: The key of the resulting associative array is the first field specified in the SELECT query.<br />
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.<br />
: First column must be a primary or alternate key.<br />
: The resulting collection can be empty.<br />
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"<br />
<br />
Example 1:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
1234 => 'myuser0',<br />
1235 => 'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getNonEmptyCollectionFromDB( $sql )<br />
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.<br />
<br />
; getObjectFromDB( $sql )<br />
: Returns one row for the sql SELECT query as an associative array or null if there is no result<br />
: Raise an exception if the query return more than one row<br />
<br />
Example:<br />
<pre><br />
self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );<br />
<br />
Result:<br />
array(<br />
'id'=>1234, 'name'=>'myuser0', 'score'=>1 <br />
)<br />
</pre><br />
<br />
; getNonEmptyObjectFromDB( $sql )<br />
: Similar to previous one, but raise an exception if no row is found<br />
<br />
; getObjectListFromDB( $sql, $bUniqueValue=false )<br />
: Return an array of rows for a sql SELECT query.<br />
: The result is the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).<br />
: The result can be empty.<br />
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.<br />
<br />
Example 1:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
'myuser0',<br />
'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )<br />
: Return an associative array of associative array, from a SQL SELECT query.<br />
: First array level correspond to first column specified in SQL query.<br />
: Second array level correspond to second column specified in SQL query.<br />
: If bSingleValue = true, keep only third column on result<br />
<br />
<br />
; DbGetLastId()<br />
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).<br />
<br />
; DbAffectedRow()<br />
: Return the number of row affected by the last operation<br />
<br />
; escapeStringForDB( $string )<br />
: You must use this function on every string type data in your database that contains unsafe data.<br />
: (unsafe = can be modified by a player).<br />
: This method makes sure that no SQL injection will be done through the string used.<br />
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,<br />
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.<br />
<br />
<pre><br />
<br />
<br />
</pre><br />
<br />
Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.<br />
<br />
== Use globals ==<br />
<br />
Sometimes, you want a single global integer value for your game, and you don't want to create a DB table specifically for it.<br />
<br />
You can do this with the BGA framework "global." Your value will be stored in the "global" table in the database, and you can access it with simple methods.<br />
<br />
'''initGameStateLabels'''<br />
<br />
This method should be located at the beginning of __construct() method of ''yourgamename.game.php''. This is where you define the globals used in your game logic, by assigning them IDs.<br />
<br />
You can define up to 80 globals, with IDs from 10 to 89 (inclusive, there can be gaps). You must '''not''' use globals outside this range, as those values are used by other components of the framework.<br />
<br />
<pre><br />
self::initGameStateLabels( array( <br />
"my_first_global_variable" => 10,<br />
"my_second_global_variable" => 11<br />
) );<br />
</pre><br />
<br />
or<br />
<br />
<pre><br />
$this->GAMESTATELABELS = ["my_first_global_variable" => 10, "my_second_global_variable" => 11];<br />
self::initGameStateLabels($this->GAMESTATELABELS);<br />
</pre><br />
<br />
<br />
This is also in this method that you will define your game options. In that case, IDs need to be between 100 and 199 (inclusive, there can be gaps) Check this for more details [[Game_options_and_preferences:_gameoptions.inc.php]]<br />
<br />
With option set, the method will look like<br />
<br />
<pre><br />
self::initGameStateLabels( array( <br />
"my_first_global_variable" => 10,<br />
"my_second_global_variable" => 11,<br />
"my_game_variant" => 100<br />
) );<br />
</pre><br />
<br />
'''setGameStateInitialValue( $value_label, $value_value )'''<br />
<br />
Initialize your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method. $value_value must be an integer.<br />
<br />
It seems that a non initialized value will not be restored with undo system, so it is therefore advisable to initialize them all in your "setupNewGame" method.<br />
<br />
<pre>foreach ($this->GAMESTATELABELS as $value_label=> $ID) if ($ID >= 10 && $ID < 90) self::setGameStateInitialValue($value_label, 0);</pre><br />
<br />
'''getGameStateValue( $value_label )'''<br />
<br />
Retrieve the current value of a global.<br />
<br />
For debugging purposes, you can have labels and value pairs send to client side by inserting that line of code in your "getAllDatas":<br />
<br />
<pre>$result['labels'] = array_combine(array_keys($this->GAMESTATELABELS), array_map('self::getGameStateValue', array_keys($this->GAMESTATELABELS)));</pre><br />
<br />
'''setGameStateValue( $value_label, $value_value )'''<br />
<br />
Set the current value of a global. $value_value must be an integer.<br />
<br />
'''incGameStateValue( $value_label, $increment )'''<br />
<br />
Increment the current value of a global. If increment is negative, decrement the value of the global.<br />
<br />
Return the final value of the global.<br />
<br />
== Game states and active players ==<br />
<br />
<br />
=== Activate player handling ===<br />
<br />
; $this->activeNextPlayer()<br />
: Make the next player active in the natural player order.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->activePrevPlayer()<br />
: Make the previous player active (in the natural player order).<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->gamestate->changeActivePlayer( $player_id )<br />
: You can call this method to make any player active.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->getActivePlayerId()<br />
: Return the "active_player" id<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"<br />
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.<br />
<br />
=== Multiple activate player handling ===<br />
<br />
; $this->gamestate->setAllPlayersMultiactive()<br />
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').<br />
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)<br />
<br />
Example of usage:<br />
<pre><br />
function st_MultiPlayerInit() {<br />
$this->gamestate->setAllPlayersMultiactive();<br />
}<br />
</pre><br />
<br />
; $this->stMakeEveryoneActive()<br />
:this method can be used in state machine to make everybody active as "st" method of multiplayeractive state, it just calls $this->gamestate->setAllPlayersMultiactive()<br />
<br />
This is to be used in state declaration:<br />
<pre><br />
2 => array(<br />
"name" => "playerTurnPlace",<br />
"description" => clienttranslate('Other player must place ships'),<br />
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),<br />
"type" => "multipleactiveplayer",<br />
'action' => 'stMakeEveryoneActive',<br />
'args' => 'arg_playerTurnPlace',<br />
"possibleactions" => array( "actionBla" ),<br />
"transitions" => array( "next" => 4, "last" => 99)<br />
),<br />
</pre><br />
<br />
; $this->gamestate->setAllPlayersNonMultiactive( $next_state )<br />
: All playing players are made inactive. Transition to next state<br />
<br />
; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )<br />
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.<br />
: "players" is the array of player id that should be made active.<br />
: If "exclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array<br />
<br />
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
<br />
; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )<br />
: During a multiactive game state, make the specified player inactive.<br />
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.<br />
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
Example of usage (see state declaration of playerTurnPlace above):<br />
<pre><br />
function actionBla($args) {<br />
self::checkAction('actionBla');<br />
// handle the action using $this->getCurrentPlayerId()<br />
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');<br />
}<br />
</pre><br />
<br />
; $this->gamestate->getActivePlayerList()<br />
: With this method you can retrieve the list of the active player at any time.<br />
: During a "game" type gamestate, it will return a void array.<br />
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).<br />
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.<br />
: Note: you should only use this method in the latter case.<br />
<br />
<br />
<br />
; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )<br />
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.<br />
Example: you have player teams and you want to activate all players in one team<br />
<pre><br />
$sql = "UPDATE player SET player_is_multiactive='0'";<br />
self::DbQuery( $sql );<br />
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";<br />
self::DbQuery( $sql );<br />
<br />
$this->gamestate->updateMultiactiveOrNextState( 'error' );<br />
</pre><br />
<br />
; updating database manually<br />
: Use this helper function to change multiactive state without sending notification<br />
<pre><br />
/**<br />
* Changes values of multiactivity in db, does not sent notifications.<br />
* To send notifications after use updateMultiactiveOrNextState<br />
* @param number $player_id, player id <=0 or null - means ALL<br />
* @param number $value - 1 multiactive, 0 non multiactive<br />
*/<br />
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {<br />
if (! $value)<br />
$value = 0;<br />
else<br />
$value = 1;<br />
$sql = "UPDATE player SET player_is_multiactive = '$value' WHERE player_zombie = 0 and player_eliminated = 0";<br />
if ($player_id > 0) {<br />
$sql .= " AND player_id = $player_id";<br />
}<br />
self::DbQuery($sql);<br />
}<br />
</pre><br />
<br />
;$this->gamestate->isPlayerActive($player_id)<br />
:Return true if specified player is active right now.<br />
:This method take into account game state type, ie nobody is active if game state is "game" and several players can be active if game state is "multiplayer"<br />
<br />
=== States functions ===<br />
; $this->gamestate->nextState( $transition )<br />
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.<br />
<br />
; $this->checkAction( $actionName, $bThrowException=true )<br />
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.<br />
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).<br />
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.<br />
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.<br />
<br />
; $this->gamestate->checkPossibleAction( $action )<br />
: (rarely used)<br />
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.<br />
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.<br />
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.<br />
<br />
This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute on js side do not checkAction on js side for this specific one.<br />
<br />
function actionUnpass() {<br />
$this->gamestate->checkPossibleAction('actionUnpass'); // player changed mind about passing while others were thinking<br />
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);<br />
}<br />
<br />
; $this->gamestate->state()<br />
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.<br />
<br />
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}<br />
<br />
I suggest to define and use this function in your php class to access state name:<br />
<br />
public function getStateName() {<br />
$state = $this->gamestate->state();<br />
return $state['name'];<br />
}<br />
<br />
; $this->gamestate->state_id()<br />
: Get the id of the current game state (rarely useful, its best to use name, unless you use constants for state ids)<br />
<br />
; $this->gamestate->isMutiactiveState()<br />
: Return true if we are in multipleactiveplayer state, false otherwise<br />
<br />
== Players turn order ==<br />
<br />
When table is created the "natural" player order is assigned to player at random, and stored in "read-only" field "player_no".<br />
If you need to create a custom order you should never change natural order but have a separate data structure. <br />
For example you can alter the players table to add another "custom_order" field, you can use state globals or you can use your natural board database, <br />
to store meeple_color/position_location pair.<br />
BGA currently does not provide any API to create/store custom player order.<br />
<br />
'''getNextPlayerTable()'''<br />
<br />
Return an associative array which associate each player with the next player around the table.<br />
<br />
In addition, key 0 is associated to the first player to play.<br />
<br />
Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:<br />
<pre><br />
array( <br />
1 => 2, <br />
2 => 3, <br />
3 => 1, <br />
0 => 1 <br />
);<br />
</pre><br />
<br />
'''getPrevPlayerTable()'''<br />
<br />
Same as above, but the associative array associate the previous player around the table. However there no 0 index here.<br />
<br />
'''getPlayerAfter( $player_id )'''<br />
<br />
Get player playing after given player in natural playing order.<br />
<br />
'''getPlayerBefore( $player_id )'''<br />
<br />
Get player playing before given player in natural playing order.<br />
<br />
Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database<br />
and have custom function to access it.<br />
<br />
'''createNextPlayerTable( $players, $bLoop=true )'''<br />
<br />
Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here. <br />
If parmeter $bLoop is set to true then last player will points to first (creaing a loop), false otherwise.<br />
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.<br />
<br />
Note: This function '''DOES NOT''' change the order in database, it only creates a map using key/values as descibed.<br />
<br />
Example of usage:<br />
<pre><br />
function getNextPlayerTableCustom() {<br />
$starting = $this->getStartingPlayer(); // custom function to get starting player<br />
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player<br />
return $this->createNextPlayerTable($player_ids, false); // create next player table in custom order<br />
}<br />
</pre><br />
<br />
<br />
<pre><br />
$table = $this->createNextPlayerTable([3,2,1], false);<br />
<br />
will return:<br />
[ <br />
3 => 2, <br />
2 => 1, <br />
1 => null,<br />
0 => 3 <br />
]<br />
</pre><br />
<br />
== Notify players ==<br />
<br />
To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.<br />
<br />
'''IMPORTANT'''<br />
<br />
Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.<br />
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.<br />
<br />
=== NotifyAllPlayers ===<br />
<br />
'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''<br />
<br />
Send a notification to all players of the game.<br />
<br />
* notification_type:<br />
A string that defines the type of your notification.<br />
<br />
Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).<br />
<br />
* notification_log:<br />
A string that defines what is to be displayed in the game log.<br />
<br />
You can use an empty string here (""). In this case, nothing is displayed in the game log.<br />
<br />
If you define a real string here, you should use "clienttranslate" method to make sure it can be translated.<br />
<br />
You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below). <br />
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.<br />
<br />
* notification_args:<br />
The arguments of your notifications, as an associative array.<br />
<br />
This array will be transmitted to the game interface logic, in order the game interface can be updated.<br />
<br />
Complete notifyAllPlayers example (from "Reversi"):<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
</pre><br />
<br />
You can see in the example above the use of the "clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.<br />
<br />
'''Important''': NO private data must be sent with this method, as a cheater could see it even if it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.<br />
<br />
'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.<br />
<br />
'''Important''': When the game page is reloaded (i.e. F5 or when loading turn based game) all previous notifications are replayed as history notifications. These notifications do not trigger notification handlers and are used basically to build the game log. Because of that most of the notification arguments, except i18n, player_id and all arguments used in the message, are removed from these history notifications. If you need additional arguments in history notifications you can add special field <b>preserve</b> to notification arguments, like this:<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y,<br />
'preserve' => [ 'x', 'y' ]<br />
) );<br />
</pre><br />
In this example, fields x and y will be preserved when replaying history notification at the game load.<br />
<br />
==== HTML in Notifications ====<br />
<br />
You CAN use some HTML inside your notification log, however it not recommended for many reasons:<br />
* Its bad architecture, ui elements leak into server now you have to manage ui in many places<br />
* If you decided to change something in ui in future version, old games replay and tutorials may not work, since they use stored notifications<br />
* When you read log preview for old games its unreadable (this is log before you enter the game replay, useful for troubleshooting or game analysis)<br />
* Its more data to transfer and store in db<br />
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.<br />
<br />
If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].<br />
<br />
==== Recursive Notifications ====<br />
<br />
If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but<br />
an array itself, which contains 'log' and 'args', i.e.<br />
<br />
$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),<br />
['token_name_rec'=>['log'=>'${token_name} #${token_number}',<br />
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]<br />
]<br />
]);<br />
<br />
Special handling of arguments:<br />
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.<br />
* ${player_name2} - same <br />
<br />
<br />
==== Excluding some players ====<br />
<br />
Sometimes you want to notify all players of a message but not have it appear in the log of specific players (for example, have every player see "Player X draws a card" but have Player X see "You draw the Ace of Spades").<br />
<br />
To send a notification to all players but have some clients ignore it, send it as normal from the server, but implement '''setIgnoreNotificationCheck''' on the client to ignore the message under given conditions. See the X.js documentation for more details.<br />
<br />
=== NotifyPlayer ===<br />
<br />
'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''<br />
<br />
Same as above, except that the notification is sent to one player only.<br />
<br />
This method must be used each time some private information must be transmitted to a player.<br />
<br />
Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. If you want a second player name in the log, name the variable ${player_name2}, etc.<br />
<br />
Note that spectators cannot be notified using this method, because their player ID is not available via loadPlayersBasicInfos() or otherwise. You must use notifyAllPlayers() for any notification that spectators should get.<br />
<br />
== About random and randomness ==<br />
<br />
A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.<br />
<br />
Here's are a list of techniques you should use in these situations, from the best to the worst.<br />
<br />
=== Dice and bga_rand ===<br />
<br />
'''bga_rand( min, max )''' <br />
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.<br />
<br />
This is the preferred function you should use, because we are updating it when a better method is introduced.<br />
<br />
As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.<br />
<br />
In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).<br />
<br />
Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".<br />
<br />
=== shuffle and cards shuffling ===<br />
<br />
To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.<br />
<br />
As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even it is not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").<br />
<br />
=== Other methods ===<br />
<br />
Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.<br />
<br />
== Game statistics ==<br />
<br />
There are 2 types of statistics:<br />
* a "player" statistic is a statistic associated to a player<br />
* a "table" statistic is a statistic not associated to a player (global statistic for this game).<br />
<br />
See [[Game statistics: stats.inc.php]] to see how you define statistics for your game.<br />
<br />
<br />
'''initStat( $table_or_player, $name, $value, $player_id = null )'''<br />
<br />
Create a statistic entry with a default value.<br />
<br />
This method must be called for each statistic of your game, in your setupNewGame method.<br />
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.<br />
<br />
<br />
'$table_or_player' must be set to "table" if this is a table statistic, or "player" if this is a player statistic.<br />
<br />
'$name' is the name of your statistic, as it has been defined in your stats.inc.php file.<br />
<br />
'$value' is the initial value of the statistic. If this is a player statistic and if the player is not specified by "$player_id" argument, the value is set for ALL players.<br />
<br />
<br />
'''setStat( $value, $name, $player_id = null )'''<br />
<br />
Set a statistic $name to $value.<br />
<br />
If "$player_id" is not specified, setStat consider it is a TABLE statistic.<br />
<br />
If "$player_id" is specified, setStat consider it is a PLAYER statistic.<br />
<br />
<br />
'''incStat( $delta, $name, $player_id = null )'''<br />
<br />
Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.<br />
<br />
<br />
'''getStat( $name, $player_id = null )'''<br />
<br />
Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Manage player scores and Tie breaker ==<br />
<br />
=== Normal scoring ===<br />
<br />
At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...<br />
<br />
During the game, you update player's score directly by updating "player_score" field of "player" table in database.<br />
<br />
Examples:<br />
<pre><br />
<br />
// +2 points to active player<br />
self::DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
// Set score of active player to 5<br />
self::DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
</pre><br />
<br />
Note: don't forget to notify the client side in order the score control can be updated accordingly.<br />
<br />
=== Tie breaker ===<br />
<br />
Tie breaker is used when two players get the same score at the end of a game.<br />
<br />
Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.<br />
<br />
Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.<br />
<br />
When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:<br />
<br />
<pre><br />
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),<br />
</pre><br />
<br />
This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.<br />
<br />
=== Co-operative game ===<br />
<br />
To make everyone win/lose together in a full-coop game:<br />
<br />
Add the following in gameinfos.inc.php :<br />
'is_coop' => 1, // full cooperative<br />
<br />
Assign a score of zero to everyone if it's a loss.<br />
Assign the same score > 0 to everyone if it's a win.<br />
<br />
=== Semi-coop ===<br />
<br />
If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.<br />
<br />
=== Only "winners" and "losers" ===<br />
<br />
For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).<br />
<br />
Examples:<br />
* Coup<br />
* Not Alone<br />
* Werewolves<br />
* Quantum<br />
<br />
In this case:<br />
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.<br />
* Add the following lines to gameinfos.inc.php:<br />
<br />
<pre><br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => true,<br />
</pre><br />
<br />
Werewolves and Coup are implemented like this, as you can see here:<br />
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults<br />
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults<br />
<br />
Adding this has the following effects:<br />
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".<br />
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").<br />
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.<br />
<br />
Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).<br />
<br />
=== Solo ===<br />
<br />
If game supports solo variant, a negative or zero score means defeat, a positive score means victory.<br />
<br />
=== Player elimination ===<br />
<br />
In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.<br />
<br />
This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").<br />
<br />
Usage:<br />
<br />
* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).<br />
* In your PHP code:<br />
self::eliminatePlayer( <player_to_eliminate_id> );<br />
* the player is informed in a dialog box that he no longer have to play and can start another game if he/she wants too (with buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.<br />
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.<br />
<br />
'''Important: this should not be used on a player who has already left the game ("zombie") as leaving/being kicked of the game (outside of the scope of the rules) is not the same as being eliminated from the game (according to the rules), except if in the course of the game, the zombie player is eliminated according to the rules.'''<br />
<br />
=== Scoring Helper functions ===<br />
<br />
These functions should have been API but they are not, just add them to your php game and use for every game.<br />
<br />
// get score<br />
function dbGetScore($player_id) {<br />
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");<br />
}<br />
<br />
// set score<br />
function dbSetScore($player_id, $count) {<br />
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");<br />
}<br />
<br />
// set aux score (tie breaker)<br />
function dbSetAuxScore($player_id, $score) {<br />
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");<br />
}<br />
<br />
// increment score (can be negative too)<br />
function dbIncScore($player_id, $inc) {<br />
$count = $this->dbGetScore($player_id);<br />
if ($inc != 0) {<br />
$count += $inc;<br />
$this->dbSetScore($player_id, $count);<br />
}<br />
return $count;<br />
}<br />
<br />
== Reflexion time ==<br />
<br />
; function giveExtraTime( $player_id, $specific_time=null )<br />
: Give standard extra time to this player.<br />
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).<br />
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).<br />
<br />
; function isAsync()<br />
: Returns true if game is turn based, false if it is realtime<br />
<br />
== Undo moves ==<br />
<br />
Please read our [[BGA Undo policy]] before.<br />
<br />
<br />
'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:<br />
'db_undo_support' => true<br />
<br />
Note: if you deploy undo support after game is in production this will take into effect for new games only, old games will give user an error if user choses Undo action, but otherwise it should not affect them.<br />
<br />
<br />
; function undoSavepoint( )<br />
: Save the whole game situation inside an "Undo save point".<br />
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.<br />
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matters if you transition to game state not to user state after), this may affect what you end up saving.<br />
<br />
<br />
; function undoRestorePoint()<br />
: Restore the situation previously saved as an "Undo save point".<br />
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).<br />
<br />
function actionUndo() {<br />
self::checkAction('actionUndo');<br />
$this->undoRestorePoint();<br />
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)<br />
}<br />
<br />
'''Important note''': if you are reading game state variable right after restore (without changing state first) it won't work properly as the global table cache is not automatically refreshed after undoRestorePoint(). So you should either change state immediately to refresh game state values, or use $this->gamestate->reloadState() to refresh the state. If you choose to do the latest, be aware that this will bring the state machine back to the state during which the save point snapshot has been taken using undoSavepoint().<br />
<br />
== Managing errors and exceptions ==<br />
<br />
Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.<br />
<br />
; throw new BgaUserException ( $error_message)<br />
: Base class to notify a user error<br />
: You must throw this exception when a player wants to do something that they are not allowed to do.<br />
: The error message will be shown to the player as a "red message".<br />
: The error message must be translated, make sure you use self::_() or $this->_() here and NOT clientranslate()<br />
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.<br />
<br />
Example from Gomoku:<br />
<pre><br />
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );<br />
</pre><br />
<br />
<br />
<br />
; throw new BgaVisibleSystemException ( $error_message)<br />
: You must throw this exception when you detect something that is not supposed to happened in your code.<br />
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.<br />
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.<br />
<br />
; throw new BgaSystemException ( $error_message)<br />
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.<br />
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.<br />
<br />
== Zombie mode ==<br />
<br />
When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.<br />
<br />
While developing your zombie mode, keep in mind that:<br />
* Do not refer to the rules, because this situation is not planned by the rules.<br />
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?<br />
* The idea is NOT to develop an artificial intelligence for the game.<br />
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.<br />
<br />
Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.<br />
<br />
Each time a zombie player must play, your "zombieTurn" method is called.<br />
<br />
Parameters:<br />
* $state: the name of the current game state.<br />
* $active_player: the id of the active player.<br />
<br />
Most of the time, your zombieTurn method looks like this:<br />
<br />
<pre><br />
function zombieTurn( $state, $active_player )<br />
{<br />
$statename = $state['name'];<br />
<br />
if( $statename == 'myFirstGameState'<br />
|| $statename == 'my2ndGameState'<br />
|| $statename == 'my3rdGameState'<br />
....<br />
)<br />
{<br />
$this->gamestate->nextState( "zombiePass" );<br />
}<br />
else<br />
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );<br />
}<br />
</pre><br />
<br />
Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.<br />
<br />
'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.<br />
<br />
== Player color preferences ==<br />
<br />
<br />
BGA players (Club members) may now choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.<br />
<br />
Making your game compatible with colors preferences is very easy and requires only 1 line of configuration change:<br />
<br />
On your gameinfos.inc.php file, add the following lines :<br />
<br />
// Favorite colors support: if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)<br />
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.<br />
'favorite_colors_support' => true,<br />
<br />
Then, on your main <your_game>.game.php file check the code of "setupNewGame". New template already have correct code, but if you editing very old game and it may be absent.<br />
<br />
$gameinfos = $this->getGameinfos();<br />
...<br />
if ($gameinfos['favorite_colors_support'])<br />
$this->reattributeColorsBasedOnPreferences($players, $gameinfos['player_colors']); // this should be above reloadPlayersBasicInfos()<br />
self::reloadPlayersBasicInfos();<br />
<br />
<br />
The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.<br />
<br />
Note that you must update the colors to indicate the colors available for your game.<br />
<br />
Some important remarks:<br />
* for some games (i.e. Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (i.e. Starting the game). Color preference mechanism must NOT be used in such a case.<br />
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.<br />
<br />
Colours currently listed as a choice in preferences (Note - you don't have to pick these, the "closest" color will be found):<br />
<br />
* #ff0000 Red<br />
* #008000 Green<br />
* #0000ff Blue<br />
* #ffa500 Yellow<br />
* #000000 Black<br />
* #ffffff White<br />
* #e94190 Pink<br />
* #982fff Purple<br />
* #72c3b1 Cyan<br />
* #f07f16 Orange<br />
* #bdd002 Khaki green<br />
* #7b7b7b Gray<br />
<br />
== Legacy games API ==<br />
<br />
For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.<br />
<br />
This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:<br />
* keeping a player preference/settings (=> player preferences and game options should be used instead)<br />
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.<br />
<br />
You should use it for:<br />
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.<br />
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.<br />
<br />
Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:<br />
<br />
try <br />
{<br />
$this->storeLegacyTeamData( 'my_variable', $my_data );<br />
}<br />
catch( feException $e )<br />
{<br />
if( $e->getCode() == FEX_legacy_size_exceeded )<br />
{<br />
// Do something here to free some space in Legacy data (ex: by removing some variables)<br />
}<br />
else<br />
throw $e;<br />
}<br />
<br />
The keys may only contain letters and numbers, underscore seems not to be allowed.<br />
<br />
; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )<br />
: Store some data associated with $key for the given user / current game<br />
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used<br />
: in a future table with the same game.<br />
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games. <br />
: TTL is a time-to-live: the maximum, and default, is 365 days.<br />
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)<br />
<br />
; function retrieveLegacyData( $player_id, $key )<br />
: Get data associated with $key for the current game<br />
: This data is common to ALL tables from the same game for this player, and persist from one table to another.<br />
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible<br />
: Note: you can use '%' in $key to retrieve all keys matching the given patterns<br />
<br />
; function removeLegacyData( $player_id, $key )<br />
: Remove some legacy data with the given key<br />
: (useful to free some data to avoid going over 64k)<br />
<br />
<br />
<br />
; function storeLegacyTeamData( $key, $data, $ttl = 365 )<br />
: Same as storeLegacyData, except that it stores some data for the whole team within the current table<br />
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.<br />
: This is useful for games which are intended to be played several time by the same team.<br />
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens<br />
<br />
; function retrieveLegacyTeamData($key)<br />
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
; function removeLegacyTeamData()<br />
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
== Language dependent games API ==<br />
<br />
This API is used for games that are heavily language dependent. Two most common use cases are:<br />
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)<br />
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)<br />
<br />
If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages he speaks.<br />
<br />
There is a new property language_dependency in gameinfos.inc.php which can be set like this:<br />
'language_dependency' => false, //or if the property is missing, the game is not language dependent<br />
'language_dependency' => true, //all players at the table must speak the same language<br />
'language_dependency' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages<br />
<br />
In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.<br />
; function getGameLanguage()<br />
: Returns an index of the selected language as defined in gameinfos.inc.php.<br />
<br />
Languages currently available on BGA are:<br />
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic<br />
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian<br />
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali<br />
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian<br />
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan<br />
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech<br />
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish<br />
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German<br />
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek<br />
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English<br />
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish<br />
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian <br />
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish<br />
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French<br />
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew <br />
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi<br />
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian<br />
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian<br />
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian<br />
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian<br />
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian<br />
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese<br />
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese <br />
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean<br />
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian<br />
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian<br />
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch<br />
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian<br />
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan<br />
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish<br />
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese<br />
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian<br />
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian<br />
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak<br />
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian <br />
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian <br />
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish<br />
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish <br />
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian<br />
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)<br />
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)<br />
<br />
== Debugging and Tracing ==<br />
<br />
To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.<br />
<br />
self::debug("Ahh!");<br />
self::dump('my_var',$my_var);<br />
<br />
See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Practical_debugging&diff=10024
Practical debugging
2021-11-02T16:26:55Z
<p>Een: Studio environment</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This page gives you practical tips to debug your game during development. Don't hesitate to share your difficulties with us so that we can improve this section.<br />
<br />
__TOC__<br />
<br />
== Tools ==<br />
<br />
To work on BGA Studio, we recommend that you use [http://www.google.com/chrome Google Chrome] as it's currently the fastest browser for the BGA platform, and it's available for all OSes.<br />
<br />
Another reason to use Chrome is that it embeds all the tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").<br />
<br />
A good practice is to use a second browser to develop the game, in order to verify that your game is working fine on this browser too.<br />
<br />
To debug with Firefox browser, we advise you to use these 2 extensions:<br />
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]<br />
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developer]<br />
<br />
To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...<br />
<br />
== General tip for debugging ==<br />
<br />
=== Save & Restore ===<br />
<br />
In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.<br />
<br />
You can save up to 3 different states.<br />
<br />
=== Refresh ===<br />
<br />
If something does not seems to work properly even you "fixed it", it may be refresh issue. Not all files born equal. Some require a lot more steps to get into the game.<br />
<br />
See https://en.doc.boardgamearena.com/Studio_file_reference for information on how to "refresh" each files.<br />
<br />
== Debugging my game when it cannot start ==<br />
<br />
If your game won't start because of an error, you are probably in one of these situations:<br />
* There is a SQL error in your dbmodel.sql file.<br />
* You have a syntax error in your PHP file.<br />
* Your PHP "setup" - or any method used during the game initial states - generates an exception.<br />
<br />
If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].<br />
However errors and logs generated by setupNewGame not always (almost never) there, so see Debug setupNewGame session.<br />
More cases of why game can't start are described on the [[Troubleshooting]] page.<br />
<br />
== Debugging an issue with the waiting screen ==<br />
<br />
BGA displays a waiting screen during a few seconds inviting free players to become premium when they are playing a lot.<br />
<br />
This waiting screen should not in principle impact your game, but in some cases it might.<br />
<br />
To test the waiting screen on the studio, you can set the desired duration by adding the get parameter studioLockingDuration with the number of seconds for the lock screen to be displayed. For example to have a 10 seconds waiting screen when you launch a game on the studio:<br />
https://studio.boardgamearena.com?studioLockingDuration=10<br />
<br />
Then you can just set it back to zero in the same way with https://studio.boardgamearena.com?studioLockingDuration=0 (or restart your browser to clear the session value).<br />
<br />
== Debugging my PHP game logic (or my view) ==<br />
<br />
<br />
=== Add traces to your code ===<br />
<br />
You can use the following functions in your game to add server side logging:<br />
<br />
'''self::dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]<br />
<br />
'''self::error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]<br />
<br />
Check [[Studio logs]] for more details on how to access your logs.<br />
<br />
This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.<br />
<br />
Only the error log level will appear in production. This level should be used only for critical problems. <br />
Other levels will show only in the development environment and can be used as you see fit.<br />
<br />
'''WARNING''': tracing does not work in constructor, setupNewGame and game states immediately following starting state (not sure why). Use other method described below in this case (seciton "Debugging setupNewGame").<br />
<br />
=== Call php functions from chat ===<br />
<br />
This is best feature ever, you can call individual function in your game.php from chat window, see details<br />
at https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Run_PHP_functions_from_the_chat<br />
<br />
<br />
=== Dump data and die ===<br />
<br />
Most of the time, debugging PHP is quite easy. Here's what I do when I want to develop/debug some game logic that is triggered by some game action:<br />
<br />
* At first, I make sure that I can reproduce the needed game situation with one click. To do this, I use the "[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]" function.<br />
* Another possibility for this is to place a '''die('ok');''' PHP statement right after the PHP I am developing/debugging. This way, I make sure that every request will fail and then nothing will be committed to the database.<br />
* Then, I use the '''var_dump''' function to dump PHP variables and check what's wrong, until it works.<br />
<br />
Example:<br />
<pre><br />
<br />
// (...my code to debug)<br />
<br />
var_dump( $my_variable );<br />
die('ok');<br />
<br />
// (...my code to debug)<br />
<br />
</pre><br />
<br />
Now since this text will be returned back to client it will usually choke on this, but you can actually see it better if you wrap it some html, i.e.<br />
<pre><br />
echo "<pre>";<br />
var_dump( $my_variable );<br />
echo "&lt;/pre>";<br />
</pre><br />
<br />
=== Debug at home ===<br />
<br />
If you develop some complex logic it is better sometimes to stub all external calls and debug it locally using command line or IDE debugger for php.<br />
You can get some basic stubs here https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php<br />
<br />
To run php locally you need to wrap it into test or something, see example https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally<br />
<br />
=== Debugging setupNewGame ===<br />
<br />
This is separate section because tracing method do not work in this function.<br />
Recommended way to debug it <br />
* leave setupNewGame exactly as in template (inlcuding setting up player table and activating first player), and add a single call at the end<br />
$this->initTables();<br />
This will be your own function which you will be changing, so you don't touch setupNewGame anymore.<br />
<br />
Remember that this function cannot send notification or query active or current player. If you need to get player data use $this->loadPlayersBasicInfos().<br />
<br />
function initTables() {<br />
try {<br />
$players = $this->loadPlayersBasicInfos();<br />
// ... code the function<br />
} catch ( Exception $e ) {<br />
// logging does not actually work in game init :(<br />
// but if you calling from php chat it will work<br />
$this->error("Fatal error while creating game");<br />
$this->dump('err', $e);<br />
}<br />
}<br />
<br />
Create a code for this function, and if it does not work run it from the chat window of the just created game (i.e. 'initTables()' without quotes). That way you can see debug output!<br />
The only trick is you have to clear all your tables in the begging so when you run it multiple times your db does not puke.<br />
If your game does not start at all - do not even call it from setupNewGame, comment it out and only call from chat window until it works.<br />
Don't forget you can also look at tables in db using php-admin tool (link at the bottom of the game table in studio).<br />
<br />
The same problem exists if you game state immediately follow starting state (problem of debugging it without the logs), in this case create a dummy player state in which player just press OK that will transition<br />
to you game state, after you done debugging it remove the state and shortcut the transition to your game state.<br />
<br />
Instead of calling initTables directly you can call helper function instead from chat window which will also reset the client, i.e.<br />
function debug_initTables() {<br />
$this->deleteAllTables(); // this suppose to delete/reset all data - you have to implement this function<br />
$this->initTables();<br />
$newGameDatas = $this->getAllTableDatas(); // this is framework function<br />
$this->notifyPlayer($this->getActivePlayerId(), 'resetInterfaceWithAllDatas', '', $newGameDatas); // this is notification to reset all data <br />
$this->notifyAllPlayers("message",'setup called',[]);<br />
}<br />
<br />
== Debugging my HTML/CSS layout ==<br />
<br />
Example situations<br />
<br />
* Why doesn't my game element show up in the interface?<br />
* Why hasn't my CSS property been applied to this element?<br />
* Why is this game element displayed at this position?<br />
<br />
A useful tip when an element does not show up in the interface is to give it a red background:<br />
<pre><br />
#my_element {<br />
... some CSS definitions ...<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
This way, you know if the element is not visible because of some CSS property or because of something else.<br />
<br />
Another tip: sometimes, changing a CSS property has no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.<br />
<br />
Using Chrome "Elements" tab (the first one), you can:<br />
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.<br />
* Using the "magnifying glass", you can click on any part of your game interface and check its HTML code and associated CSS styles.<br />
* You can even modify directly some CSS properties and see how it looks immediately in the game interface.<br />
<br />
When changing css you have to force reload (Ctrl+R). But it also reloads all images which is long, if you want it faster you can define this function in js file, and call it from Browser js console<br />
<pre><br />
// this goes outside dojo class - before or after<br />
function reloadCss() {<br />
var links = document.getElementsByTagName("link");<br />
for (var cl in links) {<br />
var link = links[cl];<br />
if (link.rel === "stylesheet" && link.href.includes("99999")) {<br />
var index = link.href.indexOf("?timestamp=");<br />
var href = link.href;<br />
if (index >= 0) {<br />
href = href.substring(0, index);<br />
}<br />
<br />
link.href = href + "?timestamp=" + Date.now();<br />
<br />
console.log("reloading " + link.href);<br />
}<br />
}<br />
}<br />
<br />
</pre><br />
<br />
For mobile its also handy to have this as button (studio only), this goes to setup() function in js:<br />
<pre><br />
// add reload Css debug button<br />
var parent = document.querySelector('.debug_section');<br />
if (parent) {<br />
var butt = dojo.create('a', { class: 'bgabutton bgabutton_gray', innerHTML: "Reload CSS" }, parent);<br />
dojo.connect(butt, 'onclick', () => reloadCss());<br />
}<br />
</pre><br />
=== Debugging Toolips CSS/Layout ===<br />
<br />
To inspect tooltip you need to pin it so it does not disappear.<br />
* Chrome tools:<br />
** Open dev tools and switch to Source tab to engage with debugger<br />
** Hover over you element until tooltip showing<br />
** Press F8 - that stops the JS, so tooltip should freeze<br />
** Now you can go to Elements tab and find your tooltip at the botton in dijitTooltip div<br />
** Don't forget to resume it again to continue (F8 again or resume button)<br />
* Other method: Open the console (dev tools) large enough window, hover to make the tooltip appear and alt + tab to focus the console that will cover the tooltip. That way the onmouseout will never be triggered.<br />
<br />
=== Debugging my Javascript game interface logic ===<br />
<br />
To debug javascript you just use embedded browser debugger, usually found in Source tab of dev tools (F12)<br />
<br />
Modern browsers also allow you to put breakpoints in your js code. It is in source tab, but its a bit difficult to find (your code that is), see picture below on how to insert breakpoints.<br />
<br />
[[File:Bga-debug.jpg]]<br />
<br />
The easier method is to add breakpoint directly into your code and reload.<br />
<br />
In Chrome, to add a breakpoint: add a line to your .js file<br />
<br />
<pre>debugger; </pre><br />
<br />
Refresh the page F5, and make sure you have the Developer tools window open, press F12. <br />
When the break-point is hit you can then step through your code and visualise variables, etc.<br />
<br />
=== Do complex things on the PHP side ===<br />
<br />
The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Do it in PHP, and transfer the results to your client interface using the "args" game state property.<br />
<br />
Note: See the Reversi tutorial for an example.<br />
<br />
=== Add traces in your code ===<br />
<br />
You can use the following:<br />
<br />
'''console.log( variable_to_inspect )'''<br />
<br />
It will give you the object structure of the variable in the Javascript console, without blocking the execution.<br />
<br />
It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.<br />
<br />
'''alert( variable_to_inspect )'''<br />
<br />
It will popup what you wish and pause the execution until you click ok.<br />
<br />
This won't be useful for complex structures; only native types will be plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.<br />
<br />
== Online format checkers ==<br />
Copy and paste code for a quick code sanity check like the right number of brackets.<br />
<br />
PHP: [https://phpcodechecker.com/ https://phpcodechecker.com/]<br />
<br />
JS: [http://esprima.org/demo/validate.html http://esprima.org/demo/validate.html]<br />
<br />
Checks for proper attributes values and browser's compatibility<br />
<br />
CSS: http://jigsaw.w3.org/css-validator/<br />
<br />
== Some frequent errors ==<br />
<br />
See [[Troubleshooting]].<br />
<br />
== Get the database matching a bug report ==<br />
<br />
When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:<br />
* Create a table in the studio with the same game and number of players as the table for which the report has been written. Launch this table.<br />
* Open another tab on the studio and go to "Manage game" page for your project (you have to be admin for this project)<br />
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.<br />
* If the snapshot is correctly retrieved, you see a "Done!" message.<br />
* Go back to the tab with your studio table and click "Load 1".<br />
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.<br />
** '''Important note:''' if you see a "Done!" message but clicking "Load 1" doesn't bring any change, it's that the snapshot is unfortunately not available (most likely because the bug report was declared too long after the game ended and the database had already been garbage collected to reclaim space).<br />
* Click on the "Go to game database" button<br />
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.<br />
* Tables to update:<br />
** player<br />
** global (value with ID 2 is the active player)<br />
** stats<br />
** tables specific to your schema that use player_ids<br />
* If your changes to player_ids are not taken into account, it may be a cache problem: use the "Clear PHP cache" button on your "Manage game" page.<br />
* Then you should be able to play with the same state of the game as when the report was created in production.<br />
* If the game has ended, you can place it again in the game state you want to debug by setting the value with ID 1 in the global table to the appropriate state value, and the value with ID 2 to the player you want active).<br />
*<br />
* Below is an example php function you may want to make. You can call this function from the chat window: LoadDebug() <br />
* change instances of 2308257, and 2308258 to you own BGA Studio logins YourLogin0 and YourLogin1<br />
* change $id0 and $id1 to the player_ids from the table you want to debug, and have recently imported.<br />
* Before you load Slot1, open a second tab with the table, because after loading the slot, that tab will be unusable. In the second tab you can call LoadDebug() in the chat window<br />
<br />
<pre><br />
public function LoadDebug()<br />
{<br />
// These are the id's from the BGAtable I need to debug.<br />
$ids = [<br />
86107517,<br />
86872172,<br />
85086097,<br />
84380410,<br />
11000525<br />
];<br />
<br />
// Id of the first player in BGA Studio<br />
$sid = 2296755;<br />
<br />
foreach ($ids as $id) {<br />
// basic tables<br />
self::DbQuery("UPDATE player SET player_id=$sid WHERE player_id = $id" );<br />
self::DbQuery("UPDATE global SET global_value=$sid WHERE global_value = $id" );<br />
self::DbQuery("UPDATE stats SET stats_player_id=$sid WHERE stats_player_id = $id" );<br />
<br />
// 'other' game specific tables. example:<br />
// tables specific to your schema that use player_ids<br />
self::DbQuery("UPDATE card SET card_location_arg=$sid WHERE card_location_arg = $id" );<br />
<br />
++$sid;<br />
}<br />
}<br />
</pre><br />
<br />
=== Fully automated version ===<br />
Thanks to quietmint for [https://boardgamearena.com/forum/viewtopic.php?f=12&t=16454#p63167 coming up] with that!<br />
<br />
; In ggg.php<br />
<pre><br />
/*<br />
* loadBug: in studio, type loadBug(20762) into the table chat to load a bug report from production<br />
* client side JavaScript will fetch each URL below in sequence, then refresh the page<br />
*/<br />
public function loadBug($reportId)<br />
{<br />
$db = explode('_', self::getUniqueValueFromDB("SELECT SUBSTRING_INDEX(DATABASE(), '_', -2)"));<br />
$game = $db[0];<br />
$tableId = $db[1];<br />
self::notifyAllPlayers('loadBug', "Trying to load <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a>", [<br />
'urls' => [<br />
// Emulates "load bug report" in control panel<br />
"https://studio.boardgamearena.com/admin/studio/getSavedGameStateFromProduction.html?game=$game&report_id=$reportId&table_id=$tableId",<br />
<br />
// Emulates "load 1" at this table<br />
"https://studio.boardgamearena.com/table/table/loadSaveState.html?table=$tableId&state=1",<br />
<br />
// Calls the function below to update SQL<br />
"https://studio.boardgamearena.com/1/$game/$game/loadBugSQL.html?table=$tableId&report_id=$reportId",<br />
<br />
// Emulates "clear PHP cache" in control panel<br />
// Needed at the end because BGA is caching player info<br />
"https://studio.boardgamearena.com/admin/studio/clearGameserverPhpCache.html?game=$game",<br />
]<br />
]);<br />
}<br />
<br />
/*<br />
* loadBugSQL: in studio, this is one of the URLs triggered by loadBug() above<br />
*/<br />
public function loadBugSQL($reportId)<br />
{<br />
$studioPlayer = self::getCurrentPlayerId();<br />
$players = self::getObjectListFromDb("SELECT player_id FROM player", true);<br />
<br />
// Change for your game<br />
// We are setting the current state to match the start of a player's turn if it's already game over<br />
$sql = [<br />
"UPDATE global SET global_value=2 WHERE global_id=1 AND global_value=99"<br />
];<br />
foreach ($players as $pId) {<br />
// All games can keep this SQL<br />
$sql[] = "UPDATE player SET player_id=$studioPlayer WHERE player_id=$pId";<br />
$sql[] = "UPDATE global SET global_value=$studioPlayer WHERE global_value=$pId";<br />
$sql[] = "UPDATE stats SET stats_player_id=$studioPlayer WHERE stats_player_id=$pId";<br />
<br />
// Add game-specific SQL update the tables for your game<br />
$sql[] = "UPDATE card SET card_location_arg=$studioPlayer WHERE card_location_arg=$pId";<br />
$sql[] = "UPDATE piece SET player_id=$studioPlayer WHERE player_id=$pId";<br />
$sql[] = "UPDATE log SET player_id=$studioPlayer WHERE player_id=$pId";<br />
$sql[] = "UPDATE log SET action_arg=REPLACE(action_arg, $pId, $studioPlayer)";<br />
<br />
// This could be improved, it assumes you had sequential studio accounts before loading<br />
// e.g., quietmint0, quietmint1, quietmint2, etc. are at the table<br />
$studioPlayer++;<br />
}<br />
$msg = <nowiki>"<b>Loaded <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a></b><hr><ul><li>" . implode(';</li><li>', $sql) . ';</li></ul>';</nowiki><br />
self::warn($msg);<br />
self::notifyAllPlayers('message', $msg, []);<br />
<br />
foreach ($sql as $q) {<br />
self::DbQuery($q);<br />
}<br />
self::reloadPlayersBasicInfos();<br />
}<br />
</pre><br />
<br />
; In ggg.action.php<br />
<pre><br />
public function loadBugSQL() {<br />
self::setAjaxMode();<br />
$reportId = (int) self::getArg('report_id', AT_int, true);<br />
$this->game->loadBugSQL($reportId);<br />
self::ajaxResponse();<br />
}<br />
</pre><br />
<br />
; In ggg.js<br />
<pre><br />
// Load production bug report handler<br />
dojo.subscribe("loadBug", this, function loadBug(n) {<br />
function fetchNextUrl() {<br />
var url = n.args.urls.shift();<br />
console.log("Fetching URL", url);<br />
dojo.xhrGet({<br />
url: url,<br />
load: function (success) {<br />
console.log("Success for URL", url, success);<br />
if (n.args.urls.length > 0) {<br />
fetchNextUrl();<br />
} else {<br />
console.log("Done, reloading page");<br />
window.location.reload();<br />
}<br />
},<br />
});<br />
}<br />
console.log("Notif: load bug", n.args);<br />
fetchNextUrl();<br />
});<br />
</pre><br />
<br />
== Studio environment ==<br />
<br />
Some developers have requested a method allowing to know which environment the module is running on. While in general, your code should be the same on all environments so that the validation process makes sense, this may allow for example to display some helpers for testing during development while being sure that they'll never show up outside of the studio.<br />
<br />
From your <gamename>.game.php file you can use:<br />
<br />
<pre>if ($this->getBgaEnvironment() == 'studio') { ... }</pre><br />
<br />
Or if needed from your <gamename>.view.php file:<br />
<br />
<pre>if ($this->game->getBgaEnvironment() == 'studio') { ... }</pre></div>
Een
http://en.doc.boardgamearena.com/index.php?title=BGA_Studio_Guidelines&diff=8998
BGA Studio Guidelines
2021-08-02T12:55:51Z
<p>Een: /* IV-7 Namespace recommendations */ mention constants too</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
= BGA Studio Guidelines = <br />
<br />
Originally From: https://www.slideshare.net/boardgamearena/bga-studio-guidelines<br />
<br />
<br />
<br />
== Why guidelines? ==<br />
More and more game publishers are choosing Board Game Arena for their game adaptations because the quality of these adaptations is high.<br />
If we want to continue to have nice games in the future, we have to make sure that every game published in the BGA platform is matching the quality standards of BGA.<br />
These guidelines are here to help you to make your game easy to use by BGA players, and to make sure its going to be validated by the game publisher.<br />
<br />
== General guidelines == <br />
The 3 main important guidelines <br />
* If a player knows the real board game, they should be able to play your adaptation with no learning.<br />
* Fidelity to the original game is an absolute requirement.<br />
* Don't try to create a video game: make your game interface as close as possible to how the original board game looks like.<br />
<br />
== Game layout ==<br />
=== I-1 Don't hide game elements ===<br />
<br />
Many board games have a lot of material to display, and computer screens are sometimes too small.<br />
But you are lucky: your game will be on a webpage with a scrolling functionality. <br />
Basically, you always have some more space available .<br />
Don't hide game elements behind menus, submenus, dialogs, etc, but display them directly on the main page.<br />
<br />
Tips: eventually, you can use HTML anchor link to jump between the different elements of the page if the page height is very big. <br />
<br />
Examples:<br />
<br />
In Amyitis, characters cards are elements you don't have to check all the time. Thus, we placed them at the bottom of the page and you have to scroll to see them.<br />
<br />
In Madeira, additional game board are shown at the bottom, but when player needs to use it it moved up.<br />
<br />
Rule: <br />
* If real game has visible elements on the table it should be visible on the main screen or user mini boards on the right<br />
<br />
Exceptions:<br />
* Showing counts of same elements is sufficient<br />
* For decks which can be inspected it permitted to show them on demand<br />
* If some games you can cut off score track and replace with BGA scoring (stars), but keeping it will look nicer (but you have to keep track of score on it as well)<br />
* Its not necessary to show helper cards such as turn overview or scoring overview. It is nice if you can incorporate that as well, but in most cases, '''such elements should not be displayed by default''' (as space should be given in priority to the game itself), and should be made available by '''a gray "Player aid" button (or help icon)''' displaying a popup when clicked, like for example in Marco Polo or Terra Mystica.<br />
<br />
=== I-2 Make it fluid ===<br />
<br />
BGA game interface is «fluid». It means the interface width can vary in order to use extra space on the screen when available.<br />
HTML and CSS give us a lot of possibilities to adapt a web content to a given browser width.<br />
You have to use HTML and CSS:<br />
* To allow players owning a big screen to enjoy the game comfortably without scrolling the page.<br />
* To allow players with a screen of just 1024px <br />
<br />
Tips: for each element of the game, answer this question « how many times during a game do I need to check/use this element? ».Less frequently used elements can be placed below.<br />
You can listen on display resize in JS to do more sophisticated layouts.<br />
<br />
Examples:<br />
<br />
Caylus: when we have a 1024px small width to play the game – even if they have to screen, available buildings are placed scroll on the the right and below the board.<br />
On larger screen, these tiles are placed on the right of the board. This is a very basic usage of the others. « float:left » CSS property.<br />
<br />
=== I-3 Use whiteblocks ===<br />
White blocks are '''div''' HTML element with the '''whiteblock''' class (white and transparent background). This is the recommended way to gather game elements together in your game interface when they are not directly on a board. Whiteblocks helps you to organize the space in order it can be easily understood by players.<br />
<br />
If game contains individual player boards with distinct colors or marking you don't need these boards inside the whiteblock.<br />
<br />
''Tips: you can use a '''h3''' title inside the whiteblock to help players to understand what is inside or to who it belongs.''<br />
<br />
In The Year of the Dragon game interface, with whiteblocks and h3 titles /picture here/<br />
<br />
=== I-4 Use player panels ===<br />
<br />
BGA players are used to look at player panels when they need an information about a player.<br />
Using player panels can allow you to save a lot of space on the main game space. In general, the following information is placed in the player panel:<br />
* Players resources (i.e. small game elements the player is keeping in front of him in the real game).<br />
* Summary information about player (i.e. number of cards in hand, number of cards played...).<br />
* « First player » token.<br />
* Score. <br />
<br />
Player panels in Seasons. /picture/ A lot of useful information can fit into these small spaces :)<br />
<br />
Note: for all games, you must always use the standard BGA score counter (with the star). Players are used to check this counter to see who is winning the game.<br />
<br />
=== I-5 Use status bar actions ===<br />
<br />
When some game action is particular to a specific game state, the good practice is to use a status bar action (HTML link).<br />
Don't try to place some icon in your main gameinterface that will be useless 95% of the time: it takes space and makes the interface more complex to understand. <br />
<br />
Status bar actions in Tobago /picture/<br />
<br />
== Game usability ==<br />
<br />
=== II-1 Use tooltips ===<br />
<br />
With BGA Studio its very easy to associate a tooltip on any element of the game. Each time this is possible: add a tooltip to explain to the players:<br />
* What is this game element?<br />
* What happens if I click on it?<br />
However, tooltips should NOT be used to display dynamic information about the current game to save space on the game interface. <br />
Typically, regular players should be able to play with no tooltips. <br />
However you can display some dynamic stuff if it's available otherwise but just annoying to calculate. For example in Lewis and Clark author asked to put<br />
tooltips of how many river space available ahead of explorer.<br />
If you need to show user why they cannot interact with element show errors instead (when clicking on it).<br />
<br />
Tips: you can place any HTML element in tooltips. So you can make them as rich and beautiful as you need :)<br />
<br />
=== II-2 Use left click only ===<br />
* The whole game should be playable with only simple left button mouse click.<br />
* Context menus should not be used.<br />
* Drag-n-drop should be avoided (if you want to use it anyway, you should make a click based alternative available).<br />
* Mouse icon must change on clickable elements (« cursor:pointer » CSS property). <br />
<br />
=== II-3 Make your interface intuitive ===<br />
If your testers have different opinions about « how to trigger some game action », maybe <br />
the best is to make several options possible for this game action. In the case there is a complex action to do by the player (ex: select some cards, then click on an action button), design your error messages in order they can guide the player(ex : « please select some cards first »).<br />
<br />
''Tips: For complex games, it is simple and useful to highlight the area of the interface where player should focus his attention (using onEnteringState/onLeavingState and CSS class, i.e. 'active_slot').'' <br />
<br />
The Boss: when a player clicks on a card with no selected cubes, the interface tells us to select some cube first.<br />
<br />
=== II-4 Use the gamelog ===<br />
With BGA Studio it is very easy to place sometext (or HTML code) in the gamelog.<br />
Don't hesitate to use the game log.<br />
Players are not always in front of the game page when their opponents are making their moves.<br />
In addition, the computer manipulates game elements faster than you usually do with the real board game and even regular players can get behind of what happened sometimes.<br />
You should be able to understand the « game story » by reading the game log. <br />
<br />
=== II-5 Tell players about automatic actions ===<br />
Very often, during a game you are in a situation where:<br />
* Only one action is possible for the activeplayer, or<br />
* A series of action has to be done (according to the rules) without any players actions.<br />
In these situation, you must or you may trigger these actions automatically.<br />
In any case, you must make sure that players understand what is happening, otherwise they will probably report a bug. <br />
<br />
Stone Age: people are fed automatically at the end of the turn, but players can always see what happened exactly in the gamelog.<br />
<br />
* Use the game log to trace all actions performed automatically. <br />
* Use synchronous notifications handlers to slow down the execution of automatic actions,so that players can understand what is happening.<br />
=== II-6 Avoid move confirmations ===<br />
As a rule of thumb, don't require move confirmation. Confirming a move slows down the user interface and thus, the game flow. You can allow a player to confirm a move if this is a very critical step in a game, and if it is possible to trigger an action by accident. If client interactions are very complex and allow cancellation, the final move can be confirmed with a "Done" button.<br />
<br />
''Hawaii'': Ending a turn is a critical action that happens only 5 times per player in a game. In this case, it is acceptable (and a good idea) to have a confirmation dialog.<br />
<br />
''Hive'': Each move has to be confirmed with click on the location because it is very easy to click by accident.<br />
<br />
''Russian Railroads'': Each move involves multiple interactions and can contains dozens of subactions. When the player is done "planning" they presses a "Done" button to submit the move to the server.<br />
<br />
''Race for the Galaxy'': There is a card that allows players to draw two cards and discard one card before the Development phase. This requires confirmation when the player selects a development card to discard, as they often means to build that development card instead.<br />
<br />
=== II-7 Translatable interface ===<br />
With BGA Studio its very easy to translate your game in any language, using BGA collaborative translation system. Check the FAQ and the example games to learn how to declare your strings so that every message in your code can be managed by the internationalization system. <br />
<br />
Diams 100 % translated in Polish<br />
<br />
=== II-8 Use interactive elements ===<br />
<br />
Interactive elements are tiles, cubes or board areas user can click on to perform an action. The following guidance apply:<br />
* If user click on interactive element either action happens or user get a error message. Try to process error message of client side and not send to server for simple errors, such as player is not active. Please be very specific why user cannot interact with element, i.e.<br />
** This is not your turn<br />
** You cannot build this building because you don't have enough resources<br />
** To select this card you have to select resource first<br />
If you cannot make errors for all elements at least tooltip should explaining when it interactive vs not<br />
<br />
Rule: Every game element should give an explicit error message if clicked at the wrong moment rather than staying silent<br />
<br />
Rule: When user can click on element during this turn it should be highlighted if possible (or non-active element de-highlighted in some way)<br />
<br />
Hightlighting guidelines:<br />
* Apply a class to all active/selectable element, i.e. class can be "selectable", "active_slot", "interactive"<br />
* An CSS element with this class can have special rules, i.e<br />
** outline (use outline, do not use "border" as this changes sizing)<br />
** OR shadow/glow - use box-shadow or filter: drop-shadow for non-standard tokens<br />
** recommended color - white, yellow or blue. Do not use red - this is indication of error rather than prompt for action<br />
** change mouse cursor to action cursor, i.e. cursor: pointer<br />
<br />
De-highlighting guidelines:<br />
* Only use this strategy when there are less inactive element than active<br />
* Apply a class to all non-interactive element, such as "non-interactive"<br />
* In css set special rules<br />
** opacity:0.7 <br />
** OR filter:contrast(0.6) or grayscale<br />
* change cursor, i.e. cursor: not-allowed<br />
<br />
Rule: If state prompt replaces the interaction with element but elements are visible its better to do both (i.e. can select a button OR they can move element on the board)<br />
** Example: In Lewis & Clark game offers gain resources via buttons on state prompt, but user can also click on cubes in supply to do the same action<br />
<br />
=== II-9 Animate moving elements ===<br />
If real game have some elements moving during the game it should also animate in your adaptation<br />
* User gets a resource - move a resource from main board to user mini board<br />
* User buys a card - move card from main display to user board<br />
* User draw a card which is revealed on the display - move card from deck to display, maybe add flippy animation to turn it face up (that requires 3d transformations - that is bonus)<br />
<br />
It is also nice to animation points or coin collection from specific region of the board (even points collection is not normally visible).<br />
<br />
Don't need to overdo animation - its not first player shooter<br />
<br />
=== II-10 Slow down the end of game scoring ===<br />
<br />
This is the climax of the game, building up suspense before revealing the winner... Don't make it too quick! :)<br />
<br />
It's also very helpful if some end of game scoring animations can show where the points are gained, to help players understand (and trust) the scoring.<br />
<br />
To achieve this, you can use synchronous notifications for each step of the scoring to slow down the process, and use this.displayScoring ([[Game_interface_logic:_yourgamename.js#Scoring_animated_display]]) to display a nice points animation in the color of the player over the element of the game granting points for this step of the scoring.<br />
<br />
For a practical example of a game adaptation where scoring has been done with this idea in mind, you can check a game replay of Terra Mystica for the final scoring (this link will fast forward you right there: [https://boardgamearena.com/archive/replay/200901-1002/?table=112192856&player=84819187&comments=426;&goto=341 replay scoring])<br />
<br />
== Original game representation ==<br />
=== III-1 Use the original art===<br />
The less you are modifying the original art of the game, the better.<br />
Its important for publishers that a board game adaptation looks like the real board game. Sometimes it can be useful to modify some elements of the game to save some space on the screen – but try to avoid it.<br />
Tips: if you have not enough space on the screen, reduce the size of the game elements. <br />
Try to make sure they are recognizable for players who played regularly, and add a tooltip to help beginners to figure out what they are. <br />
Gosu : the original cards are used, with tooltips.<br />
<br />
=== III-2 Be careful about player assistance ===<br />
As a rule of thumb, in order to respect the original board games, you should not introduce any player assistance feature.<br />
An assistance must not be introduced if it directly helps the player to figure out if his move is good or bad.<br />
An assistance may be introduced if it can help the payer to figure out what moves are available.<br />
<br />
Gygès: the assistance shows you available moves, but is not alerting you about stupid moves (like the upper left one).<br />
<br />
Note: you can however do a single choice move for a player, i.e passing on a turn if there is nothing user can do; it's quite annoying to wait on a player to pass, while it's the only action that they can do anyways.<br />
<br />
=== III-3 Cancel a move ===<br />
Most players want to have moved cancel or undo. User the following rules to implement it:<br />
* If any information is revealed which was not known before you cannot cancel it<br />
* If this is the end of active player action - you cannot cancel it<br />
* If during player turn multiple actions are required allow cancel or undo, for example - user pick cubes and drops on a building. Selecting cube and building - are two actions, so user should be able to cancel taking cube.<br />
This can be implement using client side states, so cancelling is easy as restoring last server state.<br />
<br />
=== III-4 Available information ===<br />
Every information visible by players in the real game should be accessible in the adaptation. Pay attention to some information like the number of cards in the opponents hand, or the number of remaining cards in the deck. <br />
If it is explicitly forbidden to count cards in the discard pile, this information is not available.<br />
<br />
== Game technical quality ==<br />
=== IV-1 Don't use exotic stuff ===<br />
BGA Studio provides a set of useful tools to build board games adaptations (i.e. card management, confirmation dialog, tooltips,…).<br />
Use them, and don't use exotic libraries, plugins or tricks.<br />
Why? Because BGA Framework will evolve in the future to provide new features to players, and it could make your game incompatible with the new version.<br />
On the contrary, if you are using standard Haggis using BGA standard card stuff, you will enjoy these enhancements without any effort.<br />
If you feel that you really need some exotic thing: don't hesitate to ask us.<br />
<br />
=== IV-2 Write in (simple) English ===<br />
Some other person may have to look at your code, such as:<br />
* We (the BGA team), who are here to help you if you need us.<br />
* Some other BGA developer wanting to help you.<br />
For all these reasons, your code must be written in English (variables, methods, comments...).<br />
If English is not your mother tongue don't be afraid: the whole idea here is to be understood, not to write an essay :)<br />
<br />
=== IV-3 Page refresh ===<br />
A page refresh (F5) must allow players to reset the game interface to a stable state at any moment of the game.<br />
BGA Studio framework allows you to do this with the « getAllDatas » PHP method and the « setup » Javascript method.<br />
Note: this « refresh » feature is also quite useful during the development process:)<br />
<br />
=== IV-4 Private information ===<br />
A private game element must be visible only to the player owning it. It must not be visible by his opponents, by any means.<br />
In particular: <br />
* getAllDatas PHP method must not return any element that are hidden from current player, even if the Javascript « setup » method ignores them.<br />
* you must not send via the « notifyAllPlayers » function some information that is hidden from one player (use « notifyPlayer » instead). <br />
<br />
<br />
Hearts: each player is alerted about his new cards using notifyPlayer, and cards from the other players remains secret<br />
<br />
=== IV-5 Game progression ===<br />
Game progression should be as accurate as possible.<br />
Of course, its not always easy (or even possible) to compute game progression, but a vague approximation is better than nothing. <br />
Stone Age: there are 2 different end game conditions (building cards and civilization cards). <br />
Both are taken into account to increase the accuracy of the game progression.<br />
<br />
=== IV-6 Game statistics ===<br />
Using BGA Studio you can define a set of statistics for your game. Statistics will be displayed at the end of the game, and help players to figure out why they win/loose a game, <br />
and what they should improve. Try to choose interesting statistics that distinguish the different strategies for your game, in order it can help players to understand their game. <br />
<br />
Seasons : statistics<br />
<br />
=== IV-7 Namespace recommendations ===<br />
Your game is not working in complete isolation, it's included in a page with a lot of elements around (header, footer, logs, chat, player panels, rankings...)<br />
<br />
So you should pay attention to naming your DOM elements, CSS classes and PHP constants / classes in a way specific to your game in order to avoid namespace collisions (for example you use a selector for a "selected" class in your .js, and there is also an element of the framework outside of your game with a selected class).<br />
<br />
It's recommended to have:<br />
* a wrapper div around your game zone with an id specific to your game ('yourgamename_playzone' for example) and to use it in any xpath selector of your .js<br />
* a prefix for example a trigram for your game that you append to all the css classes of your game ('yrg_selected' for example).<br />
* a prefix or a namespace for your PHP constants or classes.<br />
<br />
Even if everything is working fine today, otherwise your game may break in the future when the framework is updated.<br />
<br />
== Summary ==<br />
These guidelines are here to help you to make sure that the players, the game publisher and the game author are going to enjoy your adaptation of the game. We created these guidelines based on our personal experience (which includes many mistakes along the way) implementing a lot of games on BGA platform. Don't hesitate to contact us if you feel uncomfortable with one of these guidelines in some particular context with your game: these guidelines are here to help and not to prevent you to do smart things, and have fun while programing your game ;)</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_yourgamename.game.php&diff=8953
Main game logic: yourgamename.game.php
2021-07-28T18:12:02Z
<p>Een: /* Player elimination */ Better indication</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.<br />
<br />
== File Structure ==<br />
<br />
The details of how the file is structured are described directly with comments in the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* Constructor: where you define global variables.<br />
* setupNewGame: initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.<br />
* getAllDatas: where you retrieve all game data during a complete reload of the game. Returned value must include ['players'][playerId]['score'] for scores to populate when F5 is pressed.<br />
* getGameProgression: where you compute the game progression indicator. Returns a number indicating percent of progression (0-100)<br />
* Utility functions: your utility functions.<br />
* Player actions: the entry points for players actions ([https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php more info here]). <br />
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).<br />
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).<br />
* zombieTurn: what to do it's the turn of a zombie player.<br />
* upgradeTableDb: function to migrate database if you change it after release on production.<br />
<br />
== Accessing player information ==<br />
<br />
'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!<br />
<br />
<br />
; getPlayersNumber()<br />
: Returns the number of players playing at the table<br />
: Note: doesn't work in setupNewGame (use count($players) instead).<br />
<br />
; getActivePlayerId()<br />
: Get the "active_player", whatever what is the current state type.<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getActivePlayerName()<br />
: Get the "active_player" name<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getPlayerNameById($player_id)<br />
: Get the name by id<br />
<br />
; getPlayerColorById($player_id)<br />
: Get the color by id<br />
<br />
; getPlayerNoById($player_id)<br />
: Get 'player_no' (number) by id<br />
<br />
<br />
; loadPlayersBasicInfos()<br />
: Get an associative array with generic data about players (ie: not game specific data).<br />
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.<br />
: The content of each value is:<br />
: * player_name - the name of the player<br />
: * player_color (ex: ff0000) - the color code of the player<br />
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3<br />
<br />
; getCurrentPlayerId()<br />
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).<br />
: '''Be careful''': This is not necessarily the active player!<br />
: In general, you shouldn't use this method, unless you are in "multiplayer" state.<br />
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).<br />
<br />
; getCurrentPlayerName()<br />
: Get the "current_player" name<br />
: Be careful using this method (see above).<br />
<br />
; getCurrentPlayerColor()<br />
: Get the "current_player" color<br />
: Be careful using this method (see above).<br />
<br />
; isCurrentPlayerZombie()<br />
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.<br />
<br />
; isSpectator()<br />
: Check the "current_player" spectator status. If true, the user accessing the game is a spectator (not part of the game). For this user, the interface should display all public information, and no private information (like a friend sitting at the same table as players and just spectating the game).<br />
<br />
; getActivePlayerColor()<br />
: This function does not seems to exist in API, if you need it here is implementation<br />
function getActivePlayerColor() {<br />
$player_id = self::getActivePlayerId();<br />
$players = self::loadPlayersBasicInfos();<br />
if (isset($players[$player_id]))<br />
return $players[$player_id]['player_color'];<br />
else<br />
return null;<br />
}<br />
; isPlayerZombie($player_id)<br />
: This method does not exists, but if you need it it looks like this<br />
protected function isPlayerZombie($player_id) {<br />
$players = self::loadPlayersBasicInfos();<br />
if (! isset($players[$player_id]))<br />
throw new feException("Player $player_id is not playing here');<br />
<br />
return ($players[$player_id]['player_zombie'] == 1);<br />
}<br />
<br />
== Accessing the database ==<br />
<br />
The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.<br />
<br />
'''IMPORTANT'''<br />
<br />
BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.<br />
<br />
However there sets of database operation that initite implicit commit (most common mistake is to use "TRUNCATE"), you cannot use these operations during the game, it breaks the unrolling of transactions and will lead to nasty issues<br />
(https://mariadb.com/kb/en/sql-statements-that-cause-an-implicit-commit).<br />
<br />
<br />
; DbQuery( $sql )<br />
: This is the generic method to access the database.<br />
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database.<br />
: You should use it for UPDATE/DELETE/REPLACE/INSERT queries. For SELECT queries, the specialized methods below are much better.<br />
<br />
; getUniqueValueFromDB( $sql )<br />
: Returns a unique value from DB or null if no value is found.<br />
: $sql must be a SELECT query.<br />
: Raise an exception if more than 1 row is returned.<br />
<br />
; getCollectionFromDB( $sql, $bSingleValue=false )<br />
: Returns an associative array of rows for a sql SELECT query.<br />
: The key of the resulting associative array is the first field specified in the SELECT query.<br />
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.<br />
: First column must be a primary or alternate key.<br />
: The resulting collection can be empty.<br />
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"<br />
<br />
Example 1:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
1234 => 'myuser0',<br />
1235 => 'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getNonEmptyCollectionFromDB( $sql )<br />
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.<br />
<br />
; getObjectFromDB( $sql )<br />
: Returns one row for the sql SELECT query as an associative array or null if there is no result<br />
: Raise an exception if the query return more than one row<br />
<br />
Example:<br />
<pre><br />
self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );<br />
<br />
Result:<br />
array(<br />
'id'=>1234, 'name'=>'myuser0', 'score'=>1 <br />
)<br />
</pre><br />
<br />
; getNonEmptyObjectFromDB( $sql )<br />
: Similar to previous one, but raise an exception if no row is found<br />
<br />
; getObjectListFromDB( $sql, $bUniqueValue=false )<br />
: Return an array of rows for a sql SELECT query.<br />
: The result is the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).<br />
: The result can be empty.<br />
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.<br />
<br />
Example 1:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
'myuser0',<br />
'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )<br />
: Return an associative array of associative array, from a SQL SELECT query.<br />
: First array level correspond to first column specified in SQL query.<br />
: Second array level correspond to second column specified in SQL query.<br />
: If bSingleValue = true, keep only third column on result<br />
<br />
<br />
; DbGetLastId()<br />
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).<br />
<br />
; DbAffectedRow()<br />
: Return the number of row affected by the last operation<br />
<br />
; escapeStringForDB( $string )<br />
: You must use this function on every string type data in your database that contains unsafe data.<br />
: (unsafe = can be modified by a player).<br />
: This method makes sure that no SQL injection will be done through the string used.<br />
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,<br />
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.<br />
<br />
<pre><br />
<br />
<br />
</pre><br />
<br />
Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.<br />
<br />
== Use globals ==<br />
<br />
Sometimes, you want a single global integer value for your game, and you don't want to create a DB table specifically for it.<br />
<br />
You can do this with the BGA framework "global." Your value will be stored in the "global" table in the database, and you can access it with simple methods.<br />
<br />
'''initGameStateLabels'''<br />
<br />
This method should be located at the beginning of __construct() method of ''yourgamename.game.php''. This is where you define the globals used in your game logic, by assigning them IDs.<br />
<br />
You can define up to 80 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.<br />
<br />
<pre><br />
self::initGameStateLabels( array( <br />
"my_first_global_variable" => 10,<br />
"my_second_global_variable" => 11<br />
) );<br />
</pre><br />
<br />
or<br />
<br />
<pre><br />
$this->GAMESTATELABELS = ["my_first_global_variable" => 10, "my_second_global_variable" => 11];<br />
self::initGameStateLabels($this->GAMESTATELABELS);<br />
</pre><br />
<br />
<br />
'''setGameStateInitialValue( $value_label, $value_value )'''<br />
<br />
Initialize your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method. $value_value must be an integer.<br />
<br />
It seems that a non initialized value will not be restored with undo system, so it is therefore advisable to initialize them all in your "setupNewGame" method.<br />
<br />
<pre>foreach ($this->GAMESTATELABELS as $value_label=> $ID) if ($ID >= 10 && $ID < 90) self::setGameStateInitialValue($value_label, 0);</pre><br />
<br />
'''getGameStateValue( $value_label )'''<br />
<br />
Retrieve the current value of a global.<br />
<br />
For debugging purposes, you can have labels and value pairs send to client side by inserting that line of code in your "getAllDatas":<br />
<br />
<pre>$result['labels'] = array_combine(array_keys($this->GAMESTATELABELS), array_map('self::getGameStateValue', array_keys($this->GAMESTATELABELS)));</pre><br />
<br />
'''setGameStateValue( $value_label, $value_value )'''<br />
<br />
Set the current value of a global. $value_value must be an integer.<br />
<br />
'''incGameStateValue( $value_label, $increment )'''<br />
<br />
Increment the current value of a global. If increment is negative, decrement the value of the global.<br />
<br />
Return the final value of the global.<br />
<br />
== Game states and active players ==<br />
<br />
<br />
=== Activate player handling ===<br />
<br />
; $this->activeNextPlayer()<br />
: Make the next player active in the natural player order.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->activePrevPlayer()<br />
: Make the previous player active (in the natural player order).<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->gamestate->changeActivePlayer( $player_id )<br />
: You can call this method to make any player active.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->getActivePlayerId()<br />
: Return the "active_player" id<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"<br />
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.<br />
<br />
=== Multiple activate player handling ===<br />
<br />
; $this->gamestate->setAllPlayersMultiactive()<br />
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').<br />
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)<br />
<br />
Example of usage:<br />
<pre><br />
function st_MultiPlayerInit() {<br />
$this->gamestate->setAllPlayersMultiactive();<br />
}<br />
</pre><br />
<br />
And this is the state declaration:<br />
<pre><br />
2 => array(<br />
"name" => "playerTurnPlace",<br />
"description" => clienttranslate('Other player must place ships'),<br />
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),<br />
"type" => "multipleactiveplayer",<br />
'action' => 'multiPlayerDoSomething',<br />
'args' => 'arg_playerTurnPlace',<br />
"possibleactions" => array( "actionBla" ),<br />
"transitions" => array( "next" => 4, "last" => 99)<br />
),<br />
</pre><br />
<br />
; $this->gamestate->setAllPlayersNonMultiactive( $next_state )<br />
: All playing players are made inactive. Transition to next state<br />
<br />
; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )<br />
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.<br />
: "players" is the array of player id that should be made active.<br />
: If "exclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array<br />
<br />
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
<br />
; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )<br />
: During a multiactive game state, make the specified player inactive.<br />
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.<br />
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
Example of usage (see state declaration of playerTurnPlace above):<br />
<pre><br />
function actionBla($args) {<br />
self::checkAction('actionBla');<br />
// handle the action using $this->getCurrentPlayerId()<br />
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');<br />
}<br />
</pre><br />
<br />
; $this->gamestate->getActivePlayerList()<br />
: With this method you can retrieve the list of the active player at any time.<br />
: During a "game" type gamestate, it will return a void array.<br />
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).<br />
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.<br />
: Note: you should only use this method in the latter case.<br />
<br />
<br />
<br />
; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )<br />
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.<br />
Example: you have player teams and you want to activate all players in one team<br />
<pre><br />
$sql = "UPDATE player SET player_is_multiactive='0'";<br />
self::DbQuery( $sql );<br />
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";<br />
self::DbQuery( $sql );<br />
<br />
$this->gamestate->updateMultiactiveOrNextState( 'error' );<br />
</pre><br />
<br />
; updating database manually<br />
: Use this helper function to change multiactive state without sending notification<br />
<pre><br />
/**<br />
* Changes values of multiactivity in db, does not sent notifications.<br />
* To send notifications after use updateMultiactiveOrNextState<br />
* @param number $player_id, player id <=0 or null - means ALL<br />
* @param number $value - 1 multiactive, 0 non multiactive<br />
*/<br />
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {<br />
if (! $value)<br />
$value = 0;<br />
else<br />
$value = 1;<br />
$sql = "UPDATE player SET player_is_multiactive = '$value' WHERE player_zombie = 0 and player_eliminated = 0";<br />
if ($player_id > 0) {<br />
$sql .= " AND player_id = $player_id";<br />
}<br />
self::DbQuery($sql);<br />
}<br />
</pre><br />
<br />
=== States functions ===<br />
; $this->gamestate->nextState( $transition )<br />
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.<br />
<br />
; $this->checkAction( $actionName, $bThrowException=true )<br />
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.<br />
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).<br />
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.<br />
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.<br />
<br />
; $this->gamestate->checkPossibleAction( $action )<br />
: (rarely used)<br />
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.<br />
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.<br />
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.<br />
<br />
This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute on js side do not checkAction on js side for this specific one.<br />
<br />
function actionUnpass() {<br />
$this->gamestate->checkPossibleAction('actionUnpass'); // player chane mind about passing while others were thinking<br />
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);<br />
}<br />
<br />
; $this->gamestate->state()<br />
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.<br />
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}<br />
<br />
== Players turn order ==<br />
<br />
'''getNextPlayerTable()'''<br />
<br />
Return an associative array which associate each player with the next player around the table.<br />
<br />
In addition, key 0 is associated to the first player to play.<br />
<br />
Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:<br />
<pre><br />
array( <br />
1 => 2, <br />
2 => 3, <br />
3 => 1, <br />
0 => 1 <br />
);<br />
</pre><br />
<br />
'''getPrevPlayerTable()'''<br />
<br />
Same as above, but the associative array associate the previous player around the table. However there no 0 index here.<br />
<br />
'''getPlayerAfter( $player_id )'''<br />
<br />
Get player playing after given player in natural playing order.<br />
<br />
'''getPlayerBefore( $player_id )'''<br />
<br />
Get player playing before given player in natural playing order.<br />
<br />
Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database<br />
and have custom function to access it.<br />
<br />
'''createNextPlayerTable( $players, $bLoop=true )'''<br />
<br />
Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here. <br />
Parmeter $bLoop is true if last player points to first, false otherwise.<br />
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.<br />
<br />
N.B: This function '''DOES NOT''' allow to change players turn order!<br />
<br />
Example of usage:<br />
<pre><br />
function getNextPlayerTableCustom() {<br />
$starting = $this->getStartingPlayer(); // custom function to get starting player<br />
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player<br />
return self::createNextPlayerTable($player_ids, false); // create next player table in custom order<br />
}<br />
</pre><br />
<br />
== Notify players ==<br />
<br />
To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.<br />
<br />
'''IMPORTANT'''<br />
<br />
Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.<br />
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.<br />
<br />
=== NotifyAllPlayers ===<br />
<br />
'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''<br />
<br />
Send a notification to all players of the game.<br />
<br />
* notification_type:<br />
A string that defines the type of your notification.<br />
<br />
Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).<br />
<br />
* notification_log:<br />
A string that defines what is to be displayed in the game log.<br />
<br />
You can use an empty string here (""). In this case, nothing is displayed in the game log.<br />
<br />
If you define a real string here, you should use "clienttranslate" method to make sure it can be translated.<br />
<br />
You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below). <br />
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.<br />
<br />
* notification_args:<br />
The arguments of your notifications, as an associative array.<br />
<br />
This array will be transmitted to the game interface logic, in order the game interface can be updated.<br />
<br />
Complete notifyAllPlayers example (from "Reversi"):<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
</pre><br />
<br />
You can see in the example above the use of the "clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.<br />
<br />
'''Important''': NO private data must be sent with this method, as a cheater could see it even if it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.<br />
<br />
'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.<br />
<br />
'''Important''': When the game page is reloaded (i.e. F5 or when loading turn based game) all previous notifications are replayed as history notifications. These notifications do not trigger notification handlers and are used basically to build the game log. Because of that most of the notification arguments, except i18n, player_id and all arguments used in the message, are removed from these history notifications. If you need additional arguments in history notifications you can add special field <b>preserve</b> to notification arguments, like this:<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y,<br />
'preserve' => [ 'x', 'y' ]<br />
) );<br />
</pre><br />
In this example, fields x and y will be preserved when replaying history notification at the game load.<br />
<br />
==== HTML in Notifications ====<br />
<br />
You CAN use some HTML inside your notification log, however it not recommended for many reasons:<br />
* Its bad architecture, ui elements leak into server now you have to manage ui in many places<br />
* If you decided to change something in ui in future version, old games replay and tutorials may not work, since they use stored notifications<br />
* When you read log preview for old games its unreadable (this is log before you enter the game replay, useful for troubleshooting or game analysis)<br />
* Its more data to transfer and store in db<br />
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.<br />
<br />
If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].<br />
<br />
==== Recursive Notifications ====<br />
<br />
If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but<br />
an array itself, which contains 'log' and 'args', i.e.<br />
<br />
$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),<br />
['token_name_rec'=>['log'=>'${token_name} #${token_number}',<br />
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]<br />
]<br />
]);<br />
<br />
Special handling of arguments:<br />
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.<br />
* ${player_name2} - same <br />
<br />
<br />
==== Excluding some players ====<br />
<br />
Sometimes you want to notify all players of a message but not have it appear in the log of specific players (for example, have every player see "Player X draws a card" but have Player X see "You draw the Ace of Spades").<br />
<br />
To send a notification to all players but have some clients ignore it, send it as normal from the server, but implement '''setIgnoreNotificationCheck''' on the client to ignore the message under given conditions. See the X.js documentation for more details.<br />
<br />
=== NotifyPlayer ===<br />
<br />
'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''<br />
<br />
Same as above, except that the notification is sent to one player only.<br />
<br />
This method must be used each time some private information must be transmitted to a player.<br />
<br />
Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. If you want a second player name in the log, name the variable ${player_name2}, etc.<br />
<br />
Note that spectators cannot be notified using this method, because their player ID is not available via loadPlayersBasicInfos() or otherwise. You must use notifyAllPlayers() for any notification that spectators should get.<br />
<br />
== About random and randomness ==<br />
<br />
A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.<br />
<br />
Here's are a list of techniques you should use in these situations, from the best to the worst.<br />
<br />
=== Dice and bga_rand ===<br />
<br />
'''bga_rand( min, max )''' <br />
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.<br />
<br />
This is the preferred function you should use, because we are updating it when a better method is introduced.<br />
<br />
As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.<br />
<br />
In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).<br />
<br />
Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".<br />
<br />
=== shuffle and cards shuffling ===<br />
<br />
To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.<br />
<br />
As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even it is not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").<br />
<br />
=== Other methods ===<br />
<br />
Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.<br />
<br />
== Game statistics ==<br />
<br />
There are 2 types of statistics:<br />
* a "player" statistic is a statistic associated to a player<br />
* a "table" statistic is a statistic not associated to a player (global statistic for this game).<br />
<br />
See [[Game statistics: stats.inc.php]] to see how you define statistics for your game.<br />
<br />
<br />
'''initStat( $table_or_player, $name, $value, $player_id = null )'''<br />
<br />
Create a statistic entry with a default value.<br />
<br />
This method must be called for each statistic of your game, in your setupNewGame method.<br />
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.<br />
<br />
<br />
'$table_or_player' must be set to "table" if this is a table statistic, or "player" if this is a player statistic.<br />
<br />
'$name' is the name of your statistic, as it has been defined in your stats.inc.php file.<br />
<br />
'$value' is the initial value of the statistic. If this is a player statistic and if the player is not specified by "$player_id" argument, the value is set for ALL players.<br />
<br />
<br />
'''setStat( $value, $name, $player_id = null )'''<br />
<br />
Set a statistic $name to $value.<br />
<br />
If "$player_id" is not specified, setStat consider it is a TABLE statistic.<br />
<br />
If "$player_id" is specified, setStat consider it is a PLAYER statistic.<br />
<br />
<br />
'''incStat( $delta, $name, $player_id = null )'''<br />
<br />
Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.<br />
<br />
<br />
'''getStat( $name, $player_id = null )'''<br />
<br />
Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Manage player scores and Tie breaker ==<br />
<br />
=== Normal scoring ===<br />
<br />
At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...<br />
<br />
During the game, you update player's score directly by updating "player_score" field of "player" table in database.<br />
<br />
Examples:<br />
<pre><br />
<br />
// +2 points to active player<br />
self::DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
// Set score of active player to 5<br />
self::DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
</pre><br />
<br />
Note: don't forget to notify the client side in order the score control can be updated accordingly.<br />
<br />
=== Tie breaker ===<br />
<br />
Tie breaker is used when two players get the same score at the end of a game.<br />
<br />
Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.<br />
<br />
Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.<br />
<br />
When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:<br />
<br />
<pre><br />
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),<br />
</pre><br />
<br />
This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.<br />
<br />
=== Co-operative game ===<br />
<br />
To make everyone win/lose together in a full-coop game:<br />
<br />
Add the following in gameinfos.inc.php :<br />
'is_coop' => 1, // full cooperative<br />
<br />
Assign a score of zero to everyone if it's a loss.<br />
Assign the same score > 0 to everyone if it's a win.<br />
<br />
=== Semi-coop ===<br />
<br />
If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.<br />
<br />
=== Only "winners" and "losers" ===<br />
<br />
For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).<br />
<br />
Examples:<br />
* Coup<br />
* Not Alone<br />
* Werewolves<br />
* Quantum<br />
<br />
In this case:<br />
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.<br />
* Add the following lines to gameinfos.inc.php:<br />
<br />
<pre><br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => true,<br />
</pre><br />
<br />
Werewolves and Coup are implemented like this, as you can see here:<br />
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults<br />
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults<br />
<br />
Adding this has the following effects:<br />
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".<br />
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").<br />
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.<br />
<br />
Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).<br />
<br />
=== Solo ===<br />
<br />
If game supports solo variant, a negative or zero score means defeat, a positive score means victory.<br />
<br />
=== Player elimination ===<br />
<br />
In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.<br />
<br />
This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").<br />
<br />
Usage:<br />
<br />
* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).<br />
* In your PHP code:<br />
self::eliminatePlayer( <player_to_eliminate_id> );<br />
* the player is informed in a dialog box that he no longer have to play and can start another game if he/she wants too (with buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.<br />
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.<br />
<br />
'''Important: this should not be used on a player who has already left the game ("zombie") as leaving/being kicked of the game (outside of the scope of the rules) is not the same as being eliminated from the game (according to the rules), except if in the course of the game, the zombie player is eliminated according to the rules.'''<br />
<br />
=== Scoring Helper functions ===<br />
<br />
These functions should have been API but they are not, just add them to your php game and use for every game.<br />
<br />
// get score<br />
function dbGetScore($player_id) {<br />
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");<br />
}<br />
<br />
// set score<br />
function dbSetScore($player_id, $count) {<br />
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");<br />
}<br />
<br />
// set aux score (tie breaker)<br />
function dbSetAuxScore($player_id, $score) {<br />
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");<br />
}<br />
<br />
// increment score (can be negative too)<br />
function dbIncScore($player_id, $inc) {<br />
$count = $this->dbGetScore($player_id);<br />
if ($inc != 0) {<br />
$count += $inc;<br />
$this->dbSetScore($player_id, $count);<br />
}<br />
return $count;<br />
}<br />
<br />
== Reflexion time ==<br />
<br />
; function giveExtraTime( $player_id, $specific_time=null )<br />
: Give standard extra time to this player.<br />
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).<br />
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).<br />
<br />
<br />
== Undo moves ==<br />
<br />
Please read our [[BGA Undo policy]] before.<br />
<br />
<br />
'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:<br />
'db_undo_support' => true<br />
<br />
<br />
; function undoSavepoint( )<br />
: Save the whole game situation inside an "Undo save point".<br />
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.<br />
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matter if you transition to game state not to user state after), which may affect what you end up saved.<br />
<br />
<br />
; function undoRestorePoint()<br />
: Restore the situation previously saved as an "Undo save point".<br />
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).<br />
<br />
function actionUndo() {<br />
self::checkAction('actionUndo');<br />
$this->undoRestorePoint();<br />
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)<br />
}<br />
<br />
== Managing errors and exceptions ==<br />
<br />
Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.<br />
<br />
; throw new BgaUserException ( $error_message)<br />
: Base class to notify a user error<br />
: You must throw this exception when a player wants to do something that they are not allowed to do.<br />
: The error message will be shown to the player as a "red message".<br />
: The error message must be translated, make sure you use self::_() or $this->_() here and NOT clientranslate()<br />
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.<br />
<br />
Example from Gomoku:<br />
<pre><br />
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );<br />
</pre><br />
<br />
<br />
<br />
; throw new BgaVisibleSystemException ( $error_message)<br />
: You must throw this exception when you detect something that is not supposed to happened in your code.<br />
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.<br />
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.<br />
<br />
; throw new BgaSystemException ( $error_message)<br />
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.<br />
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.<br />
<br />
== Zombie mode ==<br />
<br />
When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.<br />
<br />
While developing your zombie mode, keep in mind that:<br />
* Do not refer to the rules, because this situation is not planned by the rules.<br />
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?<br />
* The idea is NOT to develop an artificial intelligence for the game.<br />
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.<br />
<br />
Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.<br />
<br />
Each time a zombie player must play, your "zombieTurn" method is called.<br />
<br />
Parameters:<br />
* $state: the name of the current game state.<br />
* $active_player: the id of the active player.<br />
<br />
Most of the time, your zombieTurn method looks like this:<br />
<br />
<pre><br />
function zombieTurn( $state, $active_player )<br />
{<br />
$statename = $state['name'];<br />
<br />
if( $statename == 'myFirstGameState'<br />
|| $statename == 'my2ndGameState'<br />
|| $statename == 'my3rdGameState'<br />
....<br />
)<br />
{<br />
$this->gamestate->nextState( "zombiePass" );<br />
}<br />
else<br />
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );<br />
}<br />
</pre><br />
<br />
Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.<br />
<br />
'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.<br />
<br />
== Player color preferences ==<br />
<br />
<br />
BGA players (Club members) may now choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.<br />
<br />
Making your game compatible with colors preferences is very easy and requires only 1 line of configuration change:<br />
<br />
On your gameinfos.inc.php file, add the following lines :<br />
<br />
// Favorite colors support: if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)<br />
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.<br />
'favorite_colors_support' => true,<br />
<br />
Then, on your main <your_game>.game.php file check the code of "setupNewGame". New template already have correct code, but if you editing very old game and it may be absent.<br />
<br />
$gameinfos = $this->getGameinfos();<br />
...<br />
if ($gameinfos['favorite_colors_support'])<br />
$this->reattributeColorsBasedOnPreferences($players, $gameinfos['player_colors']); // this should be above reloadPlayersBasicInfos()<br />
self::reloadPlayersBasicInfos();<br />
<br />
<br />
The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.<br />
<br />
Note that you must update the colors to indicate the colors available for your game.<br />
<br />
Some important remarks:<br />
* for some games (i.e. Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (i.e. Starting the game). Color preference mechanism must NOT be used in such a case.<br />
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.<br />
<br />
Colours currently listed as a choice in preferences (Note - you don't have to pick these, the "closest" color will be found):<br />
<br />
* #ff0000 Red<br />
* #008000 Green<br />
* #0000ff Blue<br />
* #ffa500 Yellow<br />
* #000000 Black<br />
* #ffffff White<br />
* #e94190 Pink<br />
* #982fff Purple<br />
* #72c3b1 Cyan<br />
* #f07f16 Orange<br />
* #bdd002 Khaki green<br />
* #7b7b7b Gray<br />
<br />
== Legacy games API ==<br />
<br />
For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.<br />
<br />
This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:<br />
* keeping a player preference/settings (=> player preferences and game options should be used instead)<br />
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.<br />
<br />
You should use it for:<br />
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.<br />
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.<br />
<br />
Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:<br />
<br />
try <br />
{<br />
$this->storeLegacyTeamData( 'my_variable', $my_data );<br />
}<br />
catch( feException $e )<br />
{<br />
if( $e->getCode() == FEX_legacy_size_exceeded )<br />
{<br />
// Do something here to free some space in Legacy data (ex: by removing some variables)<br />
}<br />
else<br />
throw $e;<br />
}<br />
<br />
The keys may only contain letters and numbers, underscore seems not to be allowed.<br />
<br />
; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )<br />
: Store some data associated with $key for the given user / current game<br />
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used<br />
: in a future table with the same game.<br />
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games. <br />
: TTL is a time-to-live: the maximum, and default, is 365 days.<br />
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)<br />
<br />
; function retrieveLegacyData( $player_id, $key )<br />
: Get data associated with $key for the current game<br />
: This data is common to ALL tables from the same game for this player, and persist from one table to another.<br />
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible<br />
: Note: you can use '%' in $key to retrieve all keys matching the given patterns<br />
<br />
; function removeLegacyData( $player_id, $key )<br />
: Remove some legacy data with the given key<br />
: (useful to free some data to avoid going over 64k)<br />
<br />
<br />
<br />
; function storeLegacyTeamData( $key, $data, $ttl = 365 )<br />
: Same as storeLegacyData, except that it stores some data for the whole team within the current table<br />
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.<br />
: This is useful for games which are intended to be played several time by the same team.<br />
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens<br />
<br />
; function retrieveLegacyTeamData($key)<br />
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
; function removeLegacyTeamData()<br />
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
== Language dependent games API ==<br />
<br />
This API is used for games that are heavily language dependent. Two most common use cases are:<br />
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)<br />
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)<br />
<br />
If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages he speaks.<br />
<br />
There is a new property language_dependency in gameinfos.inc.php which can be set like this:<br />
'language_dependecy' => false, //or if the property is missing, the game is not language dependent<br />
'language_dependecy' => true, //all players at the table must speak the same language<br />
'language_dependecy' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages<br />
<br />
In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.<br />
; function getGameLanguage()<br />
: Returns an index of the selected language as defined in gameinfos.inc.php.<br />
<br />
Languages currently available on BGA are:<br />
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic<br />
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian<br />
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali<br />
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian<br />
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan<br />
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech<br />
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish<br />
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German<br />
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek<br />
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English<br />
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish<br />
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian <br />
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish<br />
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French<br />
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew <br />
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi<br />
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian<br />
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian<br />
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian<br />
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian<br />
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian<br />
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese<br />
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese <br />
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean<br />
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian<br />
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian<br />
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch<br />
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian<br />
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan<br />
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish<br />
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese<br />
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian<br />
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian<br />
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak<br />
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian <br />
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian <br />
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish<br />
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish <br />
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian<br />
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)<br />
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)<br />
<br />
== Debugging and Tracing ==<br />
<br />
To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.<br />
<br />
self::debug("Ahh!");<br />
self::dump('my_var',$my_var);<br />
<br />
See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_yourgamename.game.php&diff=8943
Main game logic: yourgamename.game.php
2021-07-27T16:00:24Z
<p>Een: /* Player elimination */ More details</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.<br />
<br />
== File Structure ==<br />
<br />
The details of how the file is structured are described directly with comments in the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* Constructor: where you define global variables.<br />
* setupNewGame: initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.<br />
* getAllDatas: where you retrieve all game data during a complete reload of the game. Returned value must include ['players'][playerId]['score'] for scores to populate when F5 is pressed.<br />
* getGameProgression: where you compute the game progression indicator. Returns a number indicating percent of progression (0-100)<br />
* Utility functions: your utility functions.<br />
* Player actions: the entry points for players actions ([https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php more info here]). <br />
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).<br />
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).<br />
* zombieTurn: what to do it's the turn of a zombie player.<br />
* upgradeTableDb: function to migrate database if you change it after release on production.<br />
<br />
== Accessing player information ==<br />
<br />
'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!<br />
<br />
<br />
; getPlayersNumber()<br />
: Returns the number of players playing at the table<br />
: Note: doesn't work in setupNewGame (use count($players) instead).<br />
<br />
; getActivePlayerId()<br />
: Get the "active_player", whatever what is the current state type.<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getActivePlayerName()<br />
: Get the "active_player" name<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getPlayerNameById($player_id)<br />
: Get the name by id<br />
<br />
; getPlayerColorById($player_id)<br />
: Get the color by id<br />
<br />
; getPlayerNoById($player_id)<br />
: Get 'player_no' (number) by id<br />
<br />
<br />
; loadPlayersBasicInfos()<br />
: Get an associative array with generic data about players (ie: not game specific data).<br />
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.<br />
: The content of each value is:<br />
: * player_name - the name of the player<br />
: * player_color (ex: ff0000) - the color code of the player<br />
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3<br />
<br />
; getCurrentPlayerId()<br />
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).<br />
: '''Be careful''': This is not necessarily the active player!<br />
: In general, you shouldn't use this method, unless you are in "multiplayer" state.<br />
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).<br />
<br />
; getCurrentPlayerName()<br />
: Get the "current_player" name<br />
: Be careful using this method (see above).<br />
<br />
; getCurrentPlayerColor()<br />
: Get the "current_player" color<br />
: Be careful using this method (see above).<br />
<br />
; isCurrentPlayerZombie()<br />
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.<br />
<br />
; isSpectator()<br />
: Check the "current_player" spectator status. If true, the user accessing the game is a spectator (not part of the game). For this user, the interface should display all public information, and no private information (like a friend sitting at the same table as players and just spectating the game).<br />
<br />
; getActivePlayerColor()<br />
: This function does not seems to exist in API, if you need it here is implementation<br />
function getActivePlayerColor() {<br />
$player_id = self::getActivePlayerId();<br />
$players = self::loadPlayersBasicInfos();<br />
if (isset($players[$player_id]))<br />
return $players[$player_id]['player_color'];<br />
else<br />
return null;<br />
}<br />
; isPlayerZombie($player_id)<br />
: This method does not exists, but if you need it it looks like this<br />
protected function isPlayerZombie($player_id) {<br />
$players = self::loadPlayersBasicInfos();<br />
if (! isset($players[$player_id]))<br />
throw new feException("Player $player_id is not playing here');<br />
<br />
return ($players[$player_id]['player_zombie'] == 1);<br />
}<br />
<br />
== Accessing the database ==<br />
<br />
The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.<br />
<br />
'''IMPORTANT'''<br />
<br />
BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.<br />
<br />
However there sets of database operation that initite implicit commit (most common mistake is to use "TRUNCATE"), you cannot use these operations during the game, it breaks the unrolling of transactions and will lead to nasty issues<br />
(https://mariadb.com/kb/en/sql-statements-that-cause-an-implicit-commit).<br />
<br />
<br />
; DbQuery( $sql )<br />
: This is the generic method to access the database.<br />
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database.<br />
: You should use it for UPDATE/DELETE/REPLACE/INSERT queries. For SELECT queries, the specialized methods below are much better.<br />
<br />
; getUniqueValueFromDB( $sql )<br />
: Returns a unique value from DB or null if no value is found.<br />
: $sql must be a SELECT query.<br />
: Raise an exception if more than 1 row is returned.<br />
<br />
; getCollectionFromDB( $sql, $bSingleValue=false )<br />
: Returns an associative array of rows for a sql SELECT query.<br />
: The key of the resulting associative array is the first field specified in the SELECT query.<br />
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.<br />
: First column must be a primary or alternate key.<br />
: The resulting collection can be empty.<br />
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"<br />
<br />
Example 1:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
1234 => 'myuser0',<br />
1235 => 'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getNonEmptyCollectionFromDB( $sql )<br />
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.<br />
<br />
; getObjectFromDB( $sql )<br />
: Returns one row for the sql SELECT query as an associative array or null if there is no result<br />
: Raise an exception if the query return more than one row<br />
<br />
Example:<br />
<pre><br />
self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );<br />
<br />
Result:<br />
array(<br />
'id'=>1234, 'name'=>'myuser0', 'score'=>1 <br />
)<br />
</pre><br />
<br />
; getNonEmptyObjectFromDB( $sql )<br />
: Similar to previous one, but raise an exception if no row is found<br />
<br />
; getObjectListFromDB( $sql, $bUniqueValue=false )<br />
: Return an array of rows for a sql SELECT query.<br />
: The result is the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).<br />
: The result can be empty.<br />
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.<br />
<br />
Example 1:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
'myuser0',<br />
'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )<br />
: Return an associative array of associative array, from a SQL SELECT query.<br />
: First array level correspond to first column specified in SQL query.<br />
: Second array level correspond to second column specified in SQL query.<br />
: If bSingleValue = true, keep only third column on result<br />
<br />
<br />
; DbGetLastId()<br />
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).<br />
<br />
; DbAffectedRow()<br />
: Return the number of row affected by the last operation<br />
<br />
; escapeStringForDB( $string )<br />
: You must use this function on every string type data in your database that contains unsafe data.<br />
: (unsafe = can be modified by a player).<br />
: This method makes sure that no SQL injection will be done through the string used.<br />
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,<br />
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.<br />
<br />
<pre><br />
<br />
<br />
</pre><br />
<br />
Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.<br />
<br />
== Use globals ==<br />
<br />
Sometimes, you want a single global integer value for your game, and you don't want to create a DB table specifically for it.<br />
<br />
You can do this with the BGA framework "global." Your value will be stored in the "global" table in the database, and you can access it with simple methods.<br />
<br />
'''initGameStateLabels'''<br />
<br />
This method should be located at the beginning of __construct() method of ''yourgamename.game.php''. This is where you define the globals used in your game logic, by assigning them IDs.<br />
<br />
You can define up to 80 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.<br />
<br />
<pre><br />
self::initGameStateLabels( array( <br />
"my_first_global_variable" => 10,<br />
"my_second_global_variable" => 11<br />
) );<br />
</pre><br />
<br />
or<br />
<br />
<pre><br />
$this->GAMESTATELABELS = ["my_first_global_variable" => 10, "my_second_global_variable" => 11];<br />
self::initGameStateLabels($this->GAMESTATELABELS);<br />
</pre><br />
<br />
<br />
'''setGameStateInitialValue( $value_label, $value_value )'''<br />
<br />
Initialize your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method. $value_value must be an integer.<br />
<br />
It seems that a non initialized value will not be restored with undo system, so it is therefore advisable to initialize them all in your "setupNewGame" method.<br />
<br />
<pre>foreach ($this->GAMESTATELABELS as $value_label=> $ID) if ($ID >= 10 && $ID < 90) self::setGameStateInitialValue($value_label, 0);</pre><br />
<br />
'''getGameStateValue( $value_label )'''<br />
<br />
Retrieve the current value of a global.<br />
<br />
For debugging purposes, you can have labels and value pairs send to client side by inserting that line of code in your "getAllDatas":<br />
<br />
<pre>$result['labels'] = array_combine(array_keys($this->GAMESTATELABELS), array_map('self::getGameStateValue', array_keys($this->GAMESTATELABELS)));</pre><br />
<br />
'''setGameStateValue( $value_label, $value_value )'''<br />
<br />
Set the current value of a global. $value_value must be an integer.<br />
<br />
'''incGameStateValue( $value_label, $increment )'''<br />
<br />
Increment the current value of a global. If increment is negative, decrement the value of the global.<br />
<br />
Return the final value of the global.<br />
<br />
== Game states and active players ==<br />
<br />
<br />
=== Activate player handling ===<br />
<br />
; $this->activeNextPlayer()<br />
: Make the next player active in the natural player order.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->activePrevPlayer()<br />
: Make the previous player active (in the natural player order).<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->gamestate->changeActivePlayer( $player_id )<br />
: You can call this method to make any player active.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->getActivePlayerId()<br />
: Return the "active_player" id<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"<br />
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.<br />
<br />
=== Multiple activate player handling ===<br />
<br />
; $this->gamestate->setAllPlayersMultiactive()<br />
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').<br />
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)<br />
<br />
Example of usage:<br />
<pre><br />
function st_MultiPlayerInit() {<br />
$this->gamestate->setAllPlayersMultiactive();<br />
}<br />
</pre><br />
<br />
And this is the state declaration:<br />
<pre><br />
2 => array(<br />
"name" => "playerTurnPlace",<br />
"description" => clienttranslate('Other player must place ships'),<br />
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),<br />
"type" => "multipleactiveplayer",<br />
'action' => 'multiPlayerDoSomething',<br />
'args' => 'arg_playerTurnPlace',<br />
"possibleactions" => array( "actionBla" ),<br />
"transitions" => array( "next" => 4, "last" => 99)<br />
),<br />
</pre><br />
<br />
; $this->gamestate->setAllPlayersNonMultiactive( $next_state )<br />
: All playing players are made inactive. Transition to next state<br />
<br />
; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )<br />
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.<br />
: "players" is the array of player id that should be made active.<br />
: If "exclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array<br />
<br />
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
<br />
; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )<br />
: During a multiactive game state, make the specified player inactive.<br />
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.<br />
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
Example of usage (see state declaration of playerTurnPlace above):<br />
<pre><br />
function actionBla($args) {<br />
self::checkAction('actionBla');<br />
// handle the action using $this->getCurrentPlayerId()<br />
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');<br />
}<br />
</pre><br />
<br />
; $this->gamestate->getActivePlayerList()<br />
: With this method you can retrieve the list of the active player at any time.<br />
: During a "game" type gamestate, it will return a void array.<br />
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).<br />
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.<br />
: Note: you should only use this method in the latter case.<br />
<br />
<br />
<br />
; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )<br />
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.<br />
Example: you have player teams and you want to activate all players in one team<br />
<pre><br />
$sql = "UPDATE player SET player_is_multiactive='0'";<br />
self::DbQuery( $sql );<br />
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";<br />
self::DbQuery( $sql );<br />
<br />
$this->gamestate->updateMultiactiveOrNextState( 'error' );<br />
</pre><br />
<br />
; updating database manually<br />
: Use this helper function to change multiactive state without sending notification<br />
<pre><br />
/**<br />
* Changes values of multiactivity in db, does not sent notifications.<br />
* To send notifications after use updateMultiactiveOrNextState<br />
* @param number $player_id, player id <=0 or null - means ALL<br />
* @param number $value - 1 multiactive, 0 non multiactive<br />
*/<br />
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {<br />
if (! $value)<br />
$value = 0;<br />
else<br />
$value = 1;<br />
$sql = "UPDATE player SET player_is_multiactive = '$value' WHERE player_zombie = 0 and player_eliminated = 0";<br />
if ($player_id > 0) {<br />
$sql .= " AND player_id = $player_id";<br />
}<br />
self::DbQuery($sql);<br />
}<br />
</pre><br />
<br />
=== States functions ===<br />
; $this->gamestate->nextState( $transition )<br />
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.<br />
<br />
; $this->checkAction( $actionName, $bThrowException=true )<br />
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.<br />
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).<br />
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.<br />
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.<br />
<br />
; $this->gamestate->checkPossibleAction( $action )<br />
: (rarely used)<br />
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.<br />
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.<br />
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.<br />
<br />
This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute on js side do not checkAction on js side for this specific one.<br />
<br />
function actionUnpass() {<br />
$this->gamestate->checkPossibleAction('actionUnpass'); // player chane mind about passing while others were thinking<br />
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);<br />
}<br />
<br />
; $this->gamestate->state()<br />
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.<br />
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}<br />
<br />
== Players turn order ==<br />
<br />
'''getNextPlayerTable()'''<br />
<br />
Return an associative array which associate each player with the next player around the table.<br />
<br />
In addition, key 0 is associated to the first player to play.<br />
<br />
Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:<br />
<pre><br />
array( <br />
1 => 2, <br />
2 => 3, <br />
3 => 1, <br />
0 => 1 <br />
);<br />
</pre><br />
<br />
'''getPrevPlayerTable()'''<br />
<br />
Same as above, but the associative array associate the previous player around the table. However there no 0 index here.<br />
<br />
'''getPlayerAfter( $player_id )'''<br />
<br />
Get player playing after given player in natural playing order.<br />
<br />
'''getPlayerBefore( $player_id )'''<br />
<br />
Get player playing before given player in natural playing order.<br />
<br />
Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database<br />
and have custom function to access it.<br />
<br />
'''createNextPlayerTable( $players, $bLoop=true )'''<br />
<br />
Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here. <br />
Parmeter $bLoop is true if last player points to first, false otherwise.<br />
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.<br />
<br />
N.B: This function '''DOES NOT''' allow to change players turn order!<br />
<br />
Example of usage:<br />
<pre><br />
function getNextPlayerTableCustom() {<br />
$starting = $this->getStartingPlayer(); // custom function to get starting player<br />
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player<br />
return self::createNextPlayerTable($player_ids, false); // create next player table in custom order<br />
}<br />
</pre><br />
<br />
== Notify players ==<br />
<br />
To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.<br />
<br />
'''IMPORTANT'''<br />
<br />
Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.<br />
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.<br />
<br />
=== NotifyAllPlayers ===<br />
<br />
'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''<br />
<br />
Send a notification to all players of the game.<br />
<br />
* notification_type:<br />
A string that defines the type of your notification.<br />
<br />
Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).<br />
<br />
* notification_log:<br />
A string that defines what is to be displayed in the game log.<br />
<br />
You can use an empty string here (""). In this case, nothing is displayed in the game log.<br />
<br />
If you define a real string here, you should use "clienttranslate" method to make sure it can be translated.<br />
<br />
You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below). <br />
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.<br />
<br />
* notification_args:<br />
The arguments of your notifications, as an associative array.<br />
<br />
This array will be transmitted to the game interface logic, in order the game interface can be updated.<br />
<br />
Complete notifyAllPlayers example (from "Reversi"):<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
</pre><br />
<br />
You can see in the example above the use of the "clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.<br />
<br />
'''Important''': NO private data must be sent with this method, as a cheater could see it even if it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.<br />
<br />
'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.<br />
<br />
'''Important''': When the game page is reloaded (i.e. F5 or when loading turn based game) all previous notifications are replayed as history notifications. These notifications do not trigger notification handlers and are used basically to build the game log. Because of that most of the notification arguments, except i18n, player_id and all arguments used in the message, are removed from these history notifications. If you need additional arguments in history notifications you can add special field <b>preserve</b> to notification arguments, like this:<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y,<br />
'preserve' => [ 'x', 'y' ]<br />
) );<br />
</pre><br />
In this example, fields x and y will be preserved when replaying history notification at the game load.<br />
<br />
==== HTML in Notifications ====<br />
<br />
You CAN use some HTML inside your notification log, however it not recommended for many reasons:<br />
* Its bad architecture, ui elements leak into server now you have to manage ui in many places<br />
* If you decided to change something in ui in future version, old games replay and tutorials may not work, since they use stored notifications<br />
* When you read log preview for old games its unreadable (this is log before you enter the game replay, useful for troubleshooting or game analysis)<br />
* Its more data to transfer and store in db<br />
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.<br />
<br />
If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].<br />
<br />
==== Recursive Notifications ====<br />
<br />
If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but<br />
an array itself, which contains 'log' and 'args', i.e.<br />
<br />
$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),<br />
['token_name_rec'=>['log'=>'${token_name} #${token_number}',<br />
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]<br />
]<br />
]);<br />
<br />
Special handling of arguments:<br />
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.<br />
* ${player_name2} - same <br />
<br />
<br />
==== Excluding some players ====<br />
<br />
Sometimes you want to notify all players of a message but not have it appear in the log of specific players (for example, have every player see "Player X draws a card" but have Player X see "You draw the Ace of Spades").<br />
<br />
To send a notification to all players but have some clients ignore it, send it as normal from the server, but implement '''setIgnoreNotificationCheck''' on the client to ignore the message under given conditions. See the X.js documentation for more details.<br />
<br />
=== NotifyPlayer ===<br />
<br />
'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''<br />
<br />
Same as above, except that the notification is sent to one player only.<br />
<br />
This method must be used each time some private information must be transmitted to a player.<br />
<br />
Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. If you want a second player name in the log, name the variable ${player_name2}, etc.<br />
<br />
Note that spectators cannot be notified using this method, because their player ID is not available via loadPlayersBasicInfos() or otherwise. You must use notifyAllPlayers() for any notification that spectators should get.<br />
<br />
== About random and randomness ==<br />
<br />
A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.<br />
<br />
Here's are a list of techniques you should use in these situations, from the best to the worst.<br />
<br />
=== Dice and bga_rand ===<br />
<br />
'''bga_rand( min, max )''' <br />
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.<br />
<br />
This is the preferred function you should use, because we are updating it when a better method is introduced.<br />
<br />
As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.<br />
<br />
In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).<br />
<br />
Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".<br />
<br />
=== shuffle and cards shuffling ===<br />
<br />
To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.<br />
<br />
As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even it is not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").<br />
<br />
=== Other methods ===<br />
<br />
Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.<br />
<br />
== Game statistics ==<br />
<br />
There are 2 types of statistics:<br />
* a "player" statistic is a statistic associated to a player<br />
* a "table" statistic is a statistic not associated to a player (global statistic for this game).<br />
<br />
See [[Game statistics: stats.inc.php]] to see how you define statistics for your game.<br />
<br />
<br />
'''initStat( $table_or_player, $name, $value, $player_id = null )'''<br />
<br />
Create a statistic entry with a default value.<br />
<br />
This method must be called for each statistic of your game, in your setupNewGame method.<br />
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.<br />
<br />
<br />
'$table_or_player' must be set to "table" if this is a table statistic, or "player" if this is a player statistic.<br />
<br />
'$name' is the name of your statistic, as it has been defined in your stats.inc.php file.<br />
<br />
'$value' is the initial value of the statistic. If this is a player statistic and if the player is not specified by "$player_id" argument, the value is set for ALL players.<br />
<br />
<br />
'''setStat( $value, $name, $player_id = null )'''<br />
<br />
Set a statistic $name to $value.<br />
<br />
If "$player_id" is not specified, setStat consider it is a TABLE statistic.<br />
<br />
If "$player_id" is specified, setStat consider it is a PLAYER statistic.<br />
<br />
<br />
'''incStat( $delta, $name, $player_id = null )'''<br />
<br />
Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.<br />
<br />
<br />
'''getStat( $name, $player_id = null )'''<br />
<br />
Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Manage player scores and Tie breaker ==<br />
<br />
=== Normal scoring ===<br />
<br />
At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...<br />
<br />
During the game, you update player's score directly by updating "player_score" field of "player" table in database.<br />
<br />
Examples:<br />
<pre><br />
<br />
// +2 points to active player<br />
self::DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
// Set score of active player to 5<br />
self::DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
</pre><br />
<br />
Note: don't forget to notify the client side in order the score control can be updated accordingly.<br />
<br />
=== Tie breaker ===<br />
<br />
Tie breaker is used when two players get the same score at the end of a game.<br />
<br />
Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.<br />
<br />
Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.<br />
<br />
When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:<br />
<br />
<pre><br />
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),<br />
</pre><br />
<br />
This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.<br />
<br />
=== Co-operative game ===<br />
<br />
To make everyone win/lose together in a full-coop game:<br />
<br />
Add the following in gameinfos.inc.php :<br />
'is_coop' => 1, // full cooperative<br />
<br />
Assign a score of zero to everyone if it's a loss.<br />
Assign the same score > 0 to everyone if it's a win.<br />
<br />
=== Semi-coop ===<br />
<br />
If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.<br />
<br />
=== Only "winners" and "losers" ===<br />
<br />
For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).<br />
<br />
Examples:<br />
* Coup<br />
* Not Alone<br />
* Werewolves<br />
* Quantum<br />
<br />
In this case:<br />
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.<br />
* Add the following lines to gameinfos.inc.php:<br />
<br />
<pre><br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => true,<br />
</pre><br />
<br />
Werewolves and Coup are implemented like this, as you can see here:<br />
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults<br />
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults<br />
<br />
Adding this has the following effects:<br />
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".<br />
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").<br />
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.<br />
<br />
Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).<br />
<br />
=== Solo ===<br />
<br />
If game supports solo variant, a negative or zero score means defeat, a positive score means victory.<br />
<br />
=== Player elimination ===<br />
<br />
In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.<br />
<br />
This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").<br />
<br />
Usage:<br />
<br />
* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).<br />
* In your PHP code:<br />
self::eliminatePlayer( <player_to_eliminate_id> );<br />
* the player is informed in a dialog box that he no longer have to play and can start another game if he/she wants too (with buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.<br />
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.<br />
<br />
'''Important: this should never be used on a player who has already left the game ("zombie") as leaving/being kicked of the game (outside of the scope of the rules) is not the same as being eliminated from the game (according to the rules). You should also not rely on the database field player_eliminated for the logic of your game, as it's only a consequence (we free the player from the game because the game is over for them)'''<br />
<br />
=== Scoring Helper functions ===<br />
<br />
These functions should have been API but they are not, just add them to your php game and use for every game.<br />
<br />
// get score<br />
function dbGetScore($player_id) {<br />
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");<br />
}<br />
<br />
// set score<br />
function dbSetScore($player_id, $count) {<br />
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");<br />
}<br />
<br />
// set aux score (tie breaker)<br />
function dbSetAuxScore($player_id, $score) {<br />
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");<br />
}<br />
<br />
// increment score (can be negative too)<br />
function dbIncScore($player_id, $inc) {<br />
$count = $this->dbGetScore($player_id);<br />
if ($inc != 0) {<br />
$count += $inc;<br />
$this->dbSetScore($player_id, $count);<br />
}<br />
return $count;<br />
}<br />
<br />
== Reflexion time ==<br />
<br />
; function giveExtraTime( $player_id, $specific_time=null )<br />
: Give standard extra time to this player.<br />
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).<br />
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).<br />
<br />
<br />
== Undo moves ==<br />
<br />
Please read our [[BGA Undo policy]] before.<br />
<br />
<br />
'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:<br />
'db_undo_support' => true<br />
<br />
<br />
; function undoSavepoint( )<br />
: Save the whole game situation inside an "Undo save point".<br />
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.<br />
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matter if you transition to game state not to user state after), which may affect what you end up saved.<br />
<br />
<br />
; function undoRestorePoint()<br />
: Restore the situation previously saved as an "Undo save point".<br />
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).<br />
<br />
function actionUndo() {<br />
self::checkAction('actionUndo');<br />
$this->undoRestorePoint();<br />
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)<br />
}<br />
<br />
== Managing errors and exceptions ==<br />
<br />
Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.<br />
<br />
; throw new BgaUserException ( $error_message)<br />
: Base class to notify a user error<br />
: You must throw this exception when a player wants to do something that they are not allowed to do.<br />
: The error message will be shown to the player as a "red message".<br />
: The error message must be translated, make sure you use self::_() or $this->_() here and NOT clientranslate()<br />
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.<br />
<br />
Example from Gomoku:<br />
<pre><br />
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );<br />
</pre><br />
<br />
<br />
<br />
; throw new BgaVisibleSystemException ( $error_message)<br />
: You must throw this exception when you detect something that is not supposed to happened in your code.<br />
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.<br />
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.<br />
<br />
; throw new BgaSystemException ( $error_message)<br />
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.<br />
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.<br />
<br />
== Zombie mode ==<br />
<br />
When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.<br />
<br />
While developing your zombie mode, keep in mind that:<br />
* Do not refer to the rules, because this situation is not planned by the rules.<br />
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?<br />
* The idea is NOT to develop an artificial intelligence for the game.<br />
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.<br />
<br />
Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.<br />
<br />
Each time a zombie player must play, your "zombieTurn" method is called.<br />
<br />
Parameters:<br />
* $state: the name of the current game state.<br />
* $active_player: the id of the active player.<br />
<br />
Most of the time, your zombieTurn method looks like this:<br />
<br />
<pre><br />
function zombieTurn( $state, $active_player )<br />
{<br />
$statename = $state['name'];<br />
<br />
if( $statename == 'myFirstGameState'<br />
|| $statename == 'my2ndGameState'<br />
|| $statename == 'my3rdGameState'<br />
....<br />
)<br />
{<br />
$this->gamestate->nextState( "zombiePass" );<br />
}<br />
else<br />
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );<br />
}<br />
</pre><br />
<br />
Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.<br />
<br />
'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.<br />
<br />
== Player color preferences ==<br />
<br />
<br />
BGA players (Club members) may now choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.<br />
<br />
Making your game compatible with colors preferences is very easy and requires only 1 line of configuration change:<br />
<br />
On your gameinfos.inc.php file, add the following lines :<br />
<br />
// Favorite colors support: if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)<br />
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.<br />
'favorite_colors_support' => true,<br />
<br />
Then, on your main <your_game>.game.php file check the code of "setupNewGame". New template already have correct code, but if you editing very old game and it may be absent.<br />
<br />
$gameinfos = $this->getGameinfos();<br />
...<br />
if ($gameinfos['favorite_colors_support'])<br />
$this->reattributeColorsBasedOnPreferences($players, $gameinfos['player_colors']); // this should be above reloadPlayersBasicInfos()<br />
self::reloadPlayersBasicInfos();<br />
<br />
<br />
The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.<br />
<br />
Note that you must update the colors to indicate the colors available for your game.<br />
<br />
Some important remarks:<br />
* for some games (i.e. Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (i.e. Starting the game). Color preference mechanism must NOT be used in such a case.<br />
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.<br />
<br />
Colours currently listed as a choice in preferences (Note - you don't have to pick these, the "closest" color will be found):<br />
<br />
* #ff0000 Red<br />
* #008000 Green<br />
* #0000ff Blue<br />
* #ffa500 Yellow<br />
* #000000 Black<br />
* #ffffff White<br />
* #e94190 Pink<br />
* #982fff Purple<br />
* #72c3b1 Cyan<br />
* #f07f16 Orange<br />
* #bdd002 Khaki green<br />
* #7b7b7b Gray<br />
<br />
== Legacy games API ==<br />
<br />
For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.<br />
<br />
This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:<br />
* keeping a player preference/settings (=> player preferences and game options should be used instead)<br />
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.<br />
<br />
You should use it for:<br />
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.<br />
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.<br />
<br />
Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:<br />
<br />
try <br />
{<br />
$this->storeLegacyTeamData( 'my_variable', $my_data );<br />
}<br />
catch( feException $e )<br />
{<br />
if( $e->getCode() == FEX_legacy_size_exceeded )<br />
{<br />
// Do something here to free some space in Legacy data (ex: by removing some variables)<br />
}<br />
else<br />
throw $e;<br />
}<br />
<br />
The keys may only contain letters and numbers, underscore seems not to be allowed.<br />
<br />
; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )<br />
: Store some data associated with $key for the given user / current game<br />
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used<br />
: in a future table with the same game.<br />
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games. <br />
: TTL is a time-to-live: the maximum, and default, is 365 days.<br />
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)<br />
<br />
; function retrieveLegacyData( $player_id, $key )<br />
: Get data associated with $key for the current game<br />
: This data is common to ALL tables from the same game for this player, and persist from one table to another.<br />
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible<br />
: Note: you can use '%' in $key to retrieve all keys matching the given patterns<br />
<br />
; function removeLegacyData( $player_id, $key )<br />
: Remove some legacy data with the given key<br />
: (useful to free some data to avoid going over 64k)<br />
<br />
<br />
<br />
; function storeLegacyTeamData( $key, $data, $ttl = 365 )<br />
: Same as storeLegacyData, except that it stores some data for the whole team within the current table<br />
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.<br />
: This is useful for games which are intended to be played several time by the same team.<br />
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens<br />
<br />
; function retrieveLegacyTeamData($key)<br />
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
; function removeLegacyTeamData()<br />
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
== Language dependent games API ==<br />
<br />
This API is used for games that are heavily language dependent. Two most common use cases are:<br />
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)<br />
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)<br />
<br />
If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages he speaks.<br />
<br />
There is a new property language_dependency in gameinfos.inc.php which can be set like this:<br />
'language_dependecy' => false, //or if the property is missing, the game is not language dependent<br />
'language_dependecy' => true, //all players at the table must speak the same language<br />
'language_dependecy' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages<br />
<br />
In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.<br />
; function getGameLanguage()<br />
: Returns an index of the selected language as defined in gameinfos.inc.php.<br />
<br />
Languages currently available on BGA are:<br />
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic<br />
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian<br />
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali<br />
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian<br />
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan<br />
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech<br />
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish<br />
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German<br />
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek<br />
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English<br />
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish<br />
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian <br />
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish<br />
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French<br />
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew <br />
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi<br />
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian<br />
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian<br />
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian<br />
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian<br />
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian<br />
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese<br />
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese <br />
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean<br />
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian<br />
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian<br />
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch<br />
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian<br />
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan<br />
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish<br />
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese<br />
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian<br />
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian<br />
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak<br />
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian <br />
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian <br />
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish<br />
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish <br />
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian<br />
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)<br />
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)<br />
<br />
== Debugging and Tracing ==<br />
<br />
To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.<br />
<br />
self::debug("Ahh!");<br />
self::dump('my_var',$my_var);<br />
<br />
See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_yourgamename.game.php&diff=8941
Main game logic: yourgamename.game.php
2021-07-27T15:27:35Z
<p>Een: /* Player elimination */ Not to be used for zombies</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.<br />
<br />
== File Structure ==<br />
<br />
The details of how the file is structured are described directly with comments in the code skeleton provided to you.<br />
<br />
Here is the basic structure:<br />
<br />
* Constructor: where you define global variables.<br />
* setupNewGame: initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.<br />
* getAllDatas: where you retrieve all game data during a complete reload of the game. Returned value must include ['players'][playerId]['score'] for scores to populate when F5 is pressed.<br />
* getGameProgression: where you compute the game progression indicator. Returns a number indicating percent of progression (0-100)<br />
* Utility functions: your utility functions.<br />
* Player actions: the entry points for players actions ([https://en.doc.boardgamearena.com/Players_actions:_yourgamename.action.php more info here]). <br />
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).<br />
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).<br />
* zombieTurn: what to do it's the turn of a zombie player.<br />
* upgradeTableDb: function to migrate database if you change it after release on production.<br />
<br />
== Accessing player information ==<br />
<br />
'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!<br />
<br />
<br />
; getPlayersNumber()<br />
: Returns the number of players playing at the table<br />
: Note: doesn't work in setupNewGame (use count($players) instead).<br />
<br />
; getActivePlayerId()<br />
: Get the "active_player", whatever what is the current state type.<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getActivePlayerName()<br />
: Get the "active_player" name<br />
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.<br />
<br />
; getPlayerNameById($player_id)<br />
: Get the name by id<br />
<br />
; getPlayerColorById($player_id)<br />
: Get the color by id<br />
<br />
; getPlayerNoById($player_id)<br />
: Get 'player_no' (number) by id<br />
<br />
<br />
; loadPlayersBasicInfos()<br />
: Get an associative array with generic data about players (ie: not game specific data).<br />
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.<br />
: The content of each value is:<br />
: * player_name - the name of the player<br />
: * player_color (ex: ff0000) - the color code of the player<br />
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3<br />
<br />
; getCurrentPlayerId()<br />
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).<br />
: '''Be careful''': This is not necessarily the active player!<br />
: In general, you shouldn't use this method, unless you are in "multiplayer" state.<br />
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).<br />
<br />
; getCurrentPlayerName()<br />
: Get the "current_player" name<br />
: Be careful using this method (see above).<br />
<br />
; getCurrentPlayerColor()<br />
: Get the "current_player" color<br />
: Be careful using this method (see above).<br />
<br />
; isCurrentPlayerZombie()<br />
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.<br />
<br />
; isSpectator()<br />
: Check the "current_player" spectator status. If true, the user accessing the game is a spectator (not part of the game). For this user, the interface should display all public information, and no private information (like a friend sitting at the same table as players and just spectating the game).<br />
<br />
; getActivePlayerColor()<br />
: This function does not seems to exist in API, if you need it here is implementation<br />
function getActivePlayerColor() {<br />
$player_id = self::getActivePlayerId();<br />
$players = self::loadPlayersBasicInfos();<br />
if (isset($players[$player_id]))<br />
return $players[$player_id]['player_color'];<br />
else<br />
return null;<br />
}<br />
; isPlayerZombie($player_id)<br />
: This method does not exists, but if you need it it looks like this<br />
protected function isPlayerZombie($player_id) {<br />
$players = self::loadPlayersBasicInfos();<br />
if (! isset($players[$player_id]))<br />
throw new feException("Player $player_id is not playing here');<br />
<br />
return ($players[$player_id]['player_zombie'] == 1);<br />
}<br />
<br />
== Accessing the database ==<br />
<br />
The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.<br />
<br />
'''IMPORTANT'''<br />
<br />
BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.<br />
<br />
However there sets of database operation that initite implicit commit (most common mistake is to use "TRUNCATE"), you cannot use these operations during the game, it breaks the unrolling of transactions and will lead to nasty issues<br />
(https://mariadb.com/kb/en/sql-statements-that-cause-an-implicit-commit).<br />
<br />
<br />
; DbQuery( $sql )<br />
: This is the generic method to access the database.<br />
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database.<br />
: You should use it for UPDATE/DELETE/REPLACE/INSERT queries. For SELECT queries, the specialized methods below are much better.<br />
<br />
; getUniqueValueFromDB( $sql )<br />
: Returns a unique value from DB or null if no value is found.<br />
: $sql must be a SELECT query.<br />
: Raise an exception if more than 1 row is returned.<br />
<br />
; getCollectionFromDB( $sql, $bSingleValue=false )<br />
: Returns an associative array of rows for a sql SELECT query.<br />
: The key of the resulting associative array is the first field specified in the SELECT query.<br />
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.<br />
: First column must be a primary or alternate key.<br />
: The resulting collection can be empty.<br />
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"<br />
<br />
Example 1:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
1234 => 'myuser0',<br />
1235 => 'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getNonEmptyCollectionFromDB( $sql )<br />
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.<br />
<br />
; getObjectFromDB( $sql )<br />
: Returns one row for the sql SELECT query as an associative array or null if there is no result<br />
: Raise an exception if the query return more than one row<br />
<br />
Example:<br />
<pre><br />
self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );<br />
<br />
Result:<br />
array(<br />
'id'=>1234, 'name'=>'myuser0', 'score'=>1 <br />
)<br />
</pre><br />
<br />
; getNonEmptyObjectFromDB( $sql )<br />
: Similar to previous one, but raise an exception if no row is found<br />
<br />
; getObjectListFromDB( $sql, $bUniqueValue=false )<br />
: Return an array of rows for a sql SELECT query.<br />
: The result is the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).<br />
: The result can be empty.<br />
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.<br />
<br />
Example 1:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );<br />
<br />
Result:<br />
array(<br />
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),<br />
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )<br />
)<br />
</pre><br />
Example 2:<br />
<pre><br />
self::getObjectListFromDB( "SELECT player_name name FROM player", true );<br />
<br />
Result:<br />
array(<br />
'myuser0',<br />
'myuser1'<br />
)<br />
<br />
</pre><br />
<br />
; getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )<br />
: Return an associative array of associative array, from a SQL SELECT query.<br />
: First array level correspond to first column specified in SQL query.<br />
: Second array level correspond to second column specified in SQL query.<br />
: If bSingleValue = true, keep only third column on result<br />
<br />
<br />
; DbGetLastId()<br />
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).<br />
<br />
; DbAffectedRow()<br />
: Return the number of row affected by the last operation<br />
<br />
; escapeStringForDB( $string )<br />
: You must use this function on every string type data in your database that contains unsafe data.<br />
: (unsafe = can be modified by a player).<br />
: This method makes sure that no SQL injection will be done through the string used.<br />
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,<br />
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.<br />
<br />
<pre><br />
<br />
<br />
</pre><br />
<br />
Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.<br />
<br />
== Use globals ==<br />
<br />
Sometimes, you want a single global integer value for your game, and you don't want to create a DB table specifically for it.<br />
<br />
You can do this with the BGA framework "global." Your value will be stored in the "global" table in the database, and you can access it with simple methods.<br />
<br />
'''initGameStateLabels'''<br />
<br />
This method should be located at the beginning of __construct() method of ''yourgamename.game.php''. This is where you define the globals used in your game logic, by assigning them IDs.<br />
<br />
You can define up to 80 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.<br />
<br />
<pre><br />
self::initGameStateLabels( array( <br />
"my_first_global_variable" => 10,<br />
"my_second_global_variable" => 11<br />
) );<br />
</pre><br />
<br />
or<br />
<br />
<pre><br />
$this->GAMESTATELABELS = ["my_first_global_variable" => 10, "my_second_global_variable" => 11];<br />
self::initGameStateLabels($this->GAMESTATELABELS);<br />
</pre><br />
<br />
<br />
'''setGameStateInitialValue( $value_label, $value_value )'''<br />
<br />
Initialize your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method. $value_value must be an integer.<br />
<br />
It seems that a non initialized value will not be restored with undo system, so it is therefore advisable to initialize them all in your "setupNewGame" method.<br />
<br />
<pre>foreach ($this->GAMESTATELABELS as $value_label=> $ID) if ($ID >= 10 && $ID < 90) self::setGameStateInitialValue($value_label, 0);</pre><br />
<br />
'''getGameStateValue( $value_label )'''<br />
<br />
Retrieve the current value of a global.<br />
<br />
For debugging purposes, you can have labels and value pairs send to client side by inserting that line of code in your "getAllDatas":<br />
<br />
<pre>$result['labels'] = array_combine(array_keys($this->GAMESTATELABELS), array_map('self::getGameStateValue', array_keys($this->GAMESTATELABELS)));</pre><br />
<br />
'''setGameStateValue( $value_label, $value_value )'''<br />
<br />
Set the current value of a global. $value_value must be an integer.<br />
<br />
'''incGameStateValue( $value_label, $increment )'''<br />
<br />
Increment the current value of a global. If increment is negative, decrement the value of the global.<br />
<br />
Return the final value of the global.<br />
<br />
== Game states and active players ==<br />
<br />
<br />
=== Activate player handling ===<br />
<br />
; $this->activeNextPlayer()<br />
: Make the next player active in the natural player order.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->activePrevPlayer()<br />
: Make the previous player active (in the natural player order).<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->gamestate->changeActivePlayer( $player_id )<br />
: You can call this method to make any player active.<br />
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.<br />
<br />
; $this->getActivePlayerId()<br />
: Return the "active_player" id<br />
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"<br />
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.<br />
<br />
=== Multiple activate player handling ===<br />
<br />
; $this->gamestate->setAllPlayersMultiactive()<br />
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').<br />
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)<br />
<br />
Example of usage:<br />
<pre><br />
function st_MultiPlayerInit() {<br />
$this->gamestate->setAllPlayersMultiactive();<br />
}<br />
</pre><br />
<br />
And this is the state declaration:<br />
<pre><br />
2 => array(<br />
"name" => "playerTurnPlace",<br />
"description" => clienttranslate('Other player must place ships'),<br />
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),<br />
"type" => "multipleactiveplayer",<br />
'action' => 'multiPlayerDoSomething',<br />
'args' => 'arg_playerTurnPlace',<br />
"possibleactions" => array( "actionBla" ),<br />
"transitions" => array( "next" => 4, "last" => 99)<br />
),<br />
</pre><br />
<br />
; $this->gamestate->setAllPlayersNonMultiactive( $next_state )<br />
: All playing players are made inactive. Transition to next state<br />
<br />
; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )<br />
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.<br />
: "players" is the array of player id that should be made active.<br />
: If "exclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array<br />
<br />
: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
<br />
; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )<br />
: During a multiactive game state, make the specified player inactive.<br />
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.<br />
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.<br />
: returns true if state transition happened, false otherwise<br />
Example of usage (see state declaration of playerTurnPlace above):<br />
<pre><br />
function actionBla($args) {<br />
self::checkAction('actionBla');<br />
// handle the action using $this->getCurrentPlayerId()<br />
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');<br />
}<br />
</pre><br />
<br />
; $this->gamestate->getActivePlayerList()<br />
: With this method you can retrieve the list of the active player at any time.<br />
: During a "game" type gamestate, it will return a void array.<br />
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).<br />
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.<br />
: Note: you should only use this method in the latter case.<br />
<br />
<br />
<br />
; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )<br />
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.<br />
Example: you have player teams and you want to activate all players in one team<br />
<pre><br />
$sql = "UPDATE player SET player_is_multiactive='0'";<br />
self::DbQuery( $sql );<br />
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";<br />
self::DbQuery( $sql );<br />
<br />
$this->gamestate->updateMultiactiveOrNextState( 'error' );<br />
</pre><br />
<br />
; updating database manually<br />
: Use this helper function to change multiactive state without sending notification<br />
<pre><br />
/**<br />
* Changes values of multiactivity in db, does not sent notifications.<br />
* To send notifications after use updateMultiactiveOrNextState<br />
* @param number $player_id, player id <=0 or null - means ALL<br />
* @param number $value - 1 multiactive, 0 non multiactive<br />
*/<br />
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {<br />
if (! $value)<br />
$value = 0;<br />
else<br />
$value = 1;<br />
$sql = "UPDATE player SET player_is_multiactive = '$value' WHERE player_zombie = 0 and player_eliminated = 0";<br />
if ($player_id > 0) {<br />
$sql .= " AND player_id = $player_id";<br />
}<br />
self::DbQuery($sql);<br />
}<br />
</pre><br />
<br />
=== States functions ===<br />
; $this->gamestate->nextState( $transition )<br />
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.<br />
<br />
; $this->checkAction( $actionName, $bThrowException=true )<br />
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.<br />
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).<br />
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.<br />
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.<br />
<br />
; $this->gamestate->checkPossibleAction( $action )<br />
: (rarely used)<br />
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.<br />
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.<br />
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.<br />
<br />
This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute on js side do not checkAction on js side for this specific one.<br />
<br />
function actionUnpass() {<br />
$this->gamestate->checkPossibleAction('actionUnpass'); // player chane mind about passing while others were thinking<br />
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);<br />
}<br />
<br />
; $this->gamestate->state()<br />
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.<br />
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}<br />
<br />
== Players turn order ==<br />
<br />
'''getNextPlayerTable()'''<br />
<br />
Return an associative array which associate each player with the next player around the table.<br />
<br />
In addition, key 0 is associated to the first player to play.<br />
<br />
Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:<br />
<pre><br />
array( <br />
1 => 2, <br />
2 => 3, <br />
3 => 1, <br />
0 => 1 <br />
);<br />
</pre><br />
<br />
'''getPrevPlayerTable()'''<br />
<br />
Same as above, but the associative array associate the previous player around the table. However there no 0 index here.<br />
<br />
'''getPlayerAfter( $player_id )'''<br />
<br />
Get player playing after given player in natural playing order.<br />
<br />
'''getPlayerBefore( $player_id )'''<br />
<br />
Get player playing before given player in natural playing order.<br />
<br />
Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database<br />
and have custom function to access it.<br />
<br />
'''createNextPlayerTable( $players, $bLoop=true )'''<br />
<br />
Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here. <br />
Parmeter $bLoop is true if last player points to first, false otherwise.<br />
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.<br />
<br />
N.B: This function '''DOES NOT''' allow to change players turn order!<br />
<br />
Example of usage:<br />
<pre><br />
function getNextPlayerTableCustom() {<br />
$starting = $this->getStartingPlayer(); // custom function to get starting player<br />
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player<br />
return self::createNextPlayerTable($player_ids, false); // create next player table in custom order<br />
}<br />
</pre><br />
<br />
== Notify players ==<br />
<br />
To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.<br />
<br />
'''IMPORTANT'''<br />
<br />
Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.<br />
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.<br />
<br />
=== NotifyAllPlayers ===<br />
<br />
'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''<br />
<br />
Send a notification to all players of the game.<br />
<br />
* notification_type:<br />
A string that defines the type of your notification.<br />
<br />
Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).<br />
<br />
* notification_log:<br />
A string that defines what is to be displayed in the game log.<br />
<br />
You can use an empty string here (""). In this case, nothing is displayed in the game log.<br />
<br />
If you define a real string here, you should use "clienttranslate" method to make sure it can be translated.<br />
<br />
You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below). <br />
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.<br />
<br />
* notification_args:<br />
The arguments of your notifications, as an associative array.<br />
<br />
This array will be transmitted to the game interface logic, in order the game interface can be updated.<br />
<br />
Complete notifyAllPlayers example (from "Reversi"):<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y<br />
) );<br />
</pre><br />
<br />
You can see in the example above the use of the "clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.<br />
<br />
'''Important''': NO private data must be sent with this method, as a cheater could see it even if it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.<br />
<br />
'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.<br />
<br />
'''Important''': When the game page is reloaded (i.e. F5 or when loading turn based game) all previous notifications are replayed as history notifications. These notifications do not trigger notification handlers and are used basically to build the game log. Because of that most of the notification arguments, except i18n, player_id and all arguments used in the message, are removed from these history notifications. If you need additional arguments in history notifications you can add special field <b>preserve</b> to notification arguments, like this:<br />
<br />
<pre><br />
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),<br />
array(<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'returned_nbr' => count( $turnedOverDiscs ),<br />
'x' => $x,<br />
'y' => $y,<br />
'preserve' => [ 'x', 'y' ]<br />
) );<br />
</pre><br />
In this example, fields x and y will be preserved when replaying history notification at the game load.<br />
<br />
==== HTML in Notifications ====<br />
<br />
You CAN use some HTML inside your notification log, however it not recommended for many reasons:<br />
* Its bad architecture, ui elements leak into server now you have to manage ui in many places<br />
* If you decided to change something in ui in future version, old games replay and tutorials may not work, since they use stored notifications<br />
* When you read log preview for old games its unreadable (this is log before you enter the game replay, useful for troubleshooting or game analysis)<br />
* Its more data to transfer and store in db<br />
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.<br />
<br />
If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].<br />
<br />
==== Recursive Notifications ====<br />
<br />
If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but<br />
an array itself, which contains 'log' and 'args', i.e.<br />
<br />
$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),<br />
['token_name_rec'=>['log'=>'${token_name} #${token_number}',<br />
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]<br />
]<br />
]);<br />
<br />
Special handling of arguments:<br />
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.<br />
* ${player_name2} - same <br />
<br />
<br />
==== Excluding some players ====<br />
<br />
Sometimes you want to notify all players of a message but not have it appear in the log of specific players (for example, have every player see "Player X draws a card" but have Player X see "You draw the Ace of Spades").<br />
<br />
To send a notification to all players but have some clients ignore it, send it as normal from the server, but implement '''setIgnoreNotificationCheck''' on the client to ignore the message under given conditions. See the X.js documentation for more details.<br />
<br />
=== NotifyPlayer ===<br />
<br />
'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''<br />
<br />
Same as above, except that the notification is sent to one player only.<br />
<br />
This method must be used each time some private information must be transmitted to a player.<br />
<br />
Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. If you want a second player name in the log, name the variable ${player_name2}, etc.<br />
<br />
Note that spectators cannot be notified using this method, because their player ID is not available via loadPlayersBasicInfos() or otherwise. You must use notifyAllPlayers() for any notification that spectators should get.<br />
<br />
== About random and randomness ==<br />
<br />
A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.<br />
<br />
Here's are a list of techniques you should use in these situations, from the best to the worst.<br />
<br />
=== Dice and bga_rand ===<br />
<br />
'''bga_rand( min, max )''' <br />
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.<br />
<br />
This is the preferred function you should use, because we are updating it when a better method is introduced.<br />
<br />
As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.<br />
<br />
In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).<br />
<br />
Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".<br />
<br />
=== shuffle and cards shuffling ===<br />
<br />
To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.<br />
<br />
As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even it is not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").<br />
<br />
=== Other methods ===<br />
<br />
Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.<br />
<br />
== Game statistics ==<br />
<br />
There are 2 types of statistics:<br />
* a "player" statistic is a statistic associated to a player<br />
* a "table" statistic is a statistic not associated to a player (global statistic for this game).<br />
<br />
See [[Game statistics: stats.inc.php]] to see how you define statistics for your game.<br />
<br />
<br />
'''initStat( $table_or_player, $name, $value, $player_id = null )'''<br />
<br />
Create a statistic entry with a default value.<br />
<br />
This method must be called for each statistic of your game, in your setupNewGame method.<br />
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.<br />
<br />
<br />
'$table_or_player' must be set to "table" if this is a table statistic, or "player" if this is a player statistic.<br />
<br />
'$name' is the name of your statistic, as it has been defined in your stats.inc.php file.<br />
<br />
'$value' is the initial value of the statistic. If this is a player statistic and if the player is not specified by "$player_id" argument, the value is set for ALL players.<br />
<br />
<br />
'''setStat( $value, $name, $player_id = null )'''<br />
<br />
Set a statistic $name to $value.<br />
<br />
If "$player_id" is not specified, setStat consider it is a TABLE statistic.<br />
<br />
If "$player_id" is specified, setStat consider it is a PLAYER statistic.<br />
<br />
<br />
'''incStat( $delta, $name, $player_id = null )'''<br />
<br />
Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.<br />
<br />
<br />
'''getStat( $name, $player_id = null )'''<br />
<br />
Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.<br />
<br />
== Translations ==<br />
<br />
See [[Translations]]<br />
<br />
== Manage player scores and Tie breaker ==<br />
<br />
=== Normal scoring ===<br />
<br />
At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...<br />
<br />
During the game, you update player's score directly by updating "player_score" field of "player" table in database.<br />
<br />
Examples:<br />
<pre><br />
<br />
// +2 points to active player<br />
self::DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
// Set score of active player to 5<br />
self::DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );<br />
<br />
</pre><br />
<br />
Note: don't forget to notify the client side in order the score control can be updated accordingly.<br />
<br />
=== Tie breaker ===<br />
<br />
Tie breaker is used when two players get the same score at the end of a game.<br />
<br />
Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.<br />
<br />
Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.<br />
<br />
When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:<br />
<br />
<pre><br />
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),<br />
</pre><br />
<br />
This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.<br />
<br />
=== Co-operative game ===<br />
<br />
To make everyone win/lose together in a full-coop game:<br />
<br />
Add the following in gameinfos.inc.php :<br />
'is_coop' => 1, // full cooperative<br />
<br />
Assign a score of zero to everyone if it's a loss.<br />
Assign the same score > 0 to everyone if it's a win.<br />
<br />
=== Semi-coop ===<br />
<br />
If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.<br />
<br />
=== Only "winners" and "losers" ===<br />
<br />
For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).<br />
<br />
Examples:<br />
* Coup<br />
* Not Alone<br />
* Werewolves<br />
* Quantum<br />
<br />
In this case:<br />
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.<br />
* Add the following lines to gameinfos.inc.php:<br />
<br />
<pre><br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => true,<br />
</pre><br />
<br />
Werewolves and Coup are implemented like this, as you can see here:<br />
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults<br />
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults<br />
<br />
Adding this has the following effects:<br />
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".<br />
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").<br />
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.<br />
<br />
Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).<br />
<br />
=== Solo ===<br />
<br />
If game supports solo variant, a negative or zero score means defeat, a positive score means victory.<br />
<br />
=== Player elimination ===<br />
<br />
In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.<br />
<br />
This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").<br />
<br />
Usage:<br />
<br />
* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).<br />
* In your PHP code:<br />
self::eliminatePlayer( <player_to_eliminate_id> );<br />
* the player is informed in a dialog box that he no longer have to play and can start another game if he/she wants too (with buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.<br />
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.<br />
<br />
'''Important: this should never be used on a player who has already left the game ("zombie") as leaving/being kicked of the game (outside of the scope of the rules) is not the same as being eliminated from the game (according to the rules).'''<br />
<br />
=== Scoring Helper functions ===<br />
<br />
These functions should have been API but they are not, just add them to your php game and use for every game.<br />
<br />
// get score<br />
function dbGetScore($player_id) {<br />
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");<br />
}<br />
<br />
// set score<br />
function dbSetScore($player_id, $count) {<br />
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");<br />
}<br />
<br />
// set aux score (tie breaker)<br />
function dbSetAuxScore($player_id, $score) {<br />
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");<br />
}<br />
<br />
// increment score (can be negative too)<br />
function dbIncScore($player_id, $inc) {<br />
$count = $this->dbGetScore($player_id);<br />
if ($inc != 0) {<br />
$count += $inc;<br />
$this->dbSetScore($player_id, $count);<br />
}<br />
return $count;<br />
}<br />
<br />
== Reflexion time ==<br />
<br />
; function giveExtraTime( $player_id, $specific_time=null )<br />
: Give standard extra time to this player.<br />
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).<br />
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).<br />
<br />
<br />
== Undo moves ==<br />
<br />
Please read our [[BGA Undo policy]] before.<br />
<br />
<br />
'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:<br />
'db_undo_support' => true<br />
<br />
<br />
; function undoSavepoint( )<br />
: Save the whole game situation inside an "Undo save point".<br />
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.<br />
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matter if you transition to game state not to user state after), which may affect what you end up saved.<br />
<br />
<br />
; function undoRestorePoint()<br />
: Restore the situation previously saved as an "Undo save point".<br />
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).<br />
<br />
function actionUndo() {<br />
self::checkAction('actionUndo');<br />
$this->undoRestorePoint();<br />
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)<br />
}<br />
<br />
== Managing errors and exceptions ==<br />
<br />
Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.<br />
<br />
; throw new BgaUserException ( $error_message)<br />
: Base class to notify a user error<br />
: You must throw this exception when a player wants to do something that they are not allowed to do.<br />
: The error message will be shown to the player as a "red message".<br />
: The error message must be translated, make sure you use self::_() or $this->_() here and NOT clientranslate()<br />
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.<br />
<br />
Example from Gomoku:<br />
<pre><br />
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );<br />
</pre><br />
<br />
<br />
<br />
; throw new BgaVisibleSystemException ( $error_message)<br />
: You must throw this exception when you detect something that is not supposed to happened in your code.<br />
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.<br />
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.<br />
<br />
; throw new BgaSystemException ( $error_message)<br />
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.<br />
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.<br />
<br />
== Zombie mode ==<br />
<br />
When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.<br />
<br />
While developing your zombie mode, keep in mind that:<br />
* Do not refer to the rules, because this situation is not planned by the rules.<br />
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?<br />
* The idea is NOT to develop an artificial intelligence for the game.<br />
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.<br />
<br />
Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.<br />
<br />
Each time a zombie player must play, your "zombieTurn" method is called.<br />
<br />
Parameters:<br />
* $state: the name of the current game state.<br />
* $active_player: the id of the active player.<br />
<br />
Most of the time, your zombieTurn method looks like this:<br />
<br />
<pre><br />
function zombieTurn( $state, $active_player )<br />
{<br />
$statename = $state['name'];<br />
<br />
if( $statename == 'myFirstGameState'<br />
|| $statename == 'my2ndGameState'<br />
|| $statename == 'my3rdGameState'<br />
....<br />
)<br />
{<br />
$this->gamestate->nextState( "zombiePass" );<br />
}<br />
else<br />
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );<br />
}<br />
</pre><br />
<br />
Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.<br />
<br />
'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.<br />
<br />
== Player color preferences ==<br />
<br />
<br />
BGA players (Club members) may now choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.<br />
<br />
Making your game compatible with colors preferences is very easy and requires only 1 line of configuration change:<br />
<br />
On your gameinfos.inc.php file, add the following lines :<br />
<br />
// Favorite colors support: if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)<br />
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.<br />
'favorite_colors_support' => true,<br />
<br />
Then, on your main <your_game>.game.php file check the code of "setupNewGame". New template already have correct code, but if you editing very old game and it may be absent.<br />
<br />
$gameinfos = $this->getGameinfos();<br />
...<br />
if ($gameinfos['favorite_colors_support'])<br />
$this->reattributeColorsBasedOnPreferences($players, $gameinfos['player_colors']); // this should be above reloadPlayersBasicInfos()<br />
self::reloadPlayersBasicInfos();<br />
<br />
<br />
The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.<br />
<br />
Note that you must update the colors to indicate the colors available for your game.<br />
<br />
Some important remarks:<br />
* for some games (i.e. Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (i.e. Starting the game). Color preference mechanism must NOT be used in such a case.<br />
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.<br />
<br />
Colours currently listed as a choice in preferences (Note - you don't have to pick these, the "closest" color will be found):<br />
<br />
* #ff0000 Red<br />
* #008000 Green<br />
* #0000ff Blue<br />
* #ffa500 Yellow<br />
* #000000 Black<br />
* #ffffff White<br />
* #e94190 Pink<br />
* #982fff Purple<br />
* #72c3b1 Cyan<br />
* #f07f16 Orange<br />
* #bdd002 Khaki green<br />
* #7b7b7b Gray<br />
<br />
== Legacy games API ==<br />
<br />
For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.<br />
<br />
This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:<br />
* keeping a player preference/settings (=> player preferences and game options should be used instead)<br />
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.<br />
<br />
You should use it for:<br />
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.<br />
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.<br />
<br />
Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:<br />
<br />
try <br />
{<br />
$this->storeLegacyTeamData( 'my_variable', $my_data );<br />
}<br />
catch( feException $e )<br />
{<br />
if( $e->getCode() == FEX_legacy_size_exceeded )<br />
{<br />
// Do something here to free some space in Legacy data (ex: by removing some variables)<br />
}<br />
else<br />
throw $e;<br />
}<br />
<br />
The keys may only contain letters and numbers, underscore seems not to be allowed.<br />
<br />
; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )<br />
: Store some data associated with $key for the given user / current game<br />
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used<br />
: in a future table with the same game.<br />
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games. <br />
: TTL is a time-to-live: the maximum, and default, is 365 days.<br />
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)<br />
<br />
; function retrieveLegacyData( $player_id, $key )<br />
: Get data associated with $key for the current game<br />
: This data is common to ALL tables from the same game for this player, and persist from one table to another.<br />
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible<br />
: Note: you can use '%' in $key to retrieve all keys matching the given patterns<br />
<br />
; function removeLegacyData( $player_id, $key )<br />
: Remove some legacy data with the given key<br />
: (useful to free some data to avoid going over 64k)<br />
<br />
<br />
<br />
; function storeLegacyTeamData( $key, $data, $ttl = 365 )<br />
: Same as storeLegacyData, except that it stores some data for the whole team within the current table<br />
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.<br />
: This is useful for games which are intended to be played several time by the same team.<br />
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens<br />
<br />
; function retrieveLegacyTeamData($key)<br />
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
; function removeLegacyTeamData()<br />
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)<br />
<br />
== Language dependent games API ==<br />
<br />
This API is used for games that are heavily language dependent. Two most common use cases are:<br />
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)<br />
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)<br />
<br />
If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages he speaks.<br />
<br />
There is a new property language_dependency in gameinfos.inc.php which can be set like this:<br />
'language_dependecy' => false, //or if the property is missing, the game is not language dependent<br />
'language_dependecy' => true, //all players at the table must speak the same language<br />
'language_dependecy' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages<br />
<br />
In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.<br />
; function getGameLanguage()<br />
: Returns an index of the selected language as defined in gameinfos.inc.php.<br />
<br />
Languages currently available on BGA are:<br />
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic<br />
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian<br />
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali<br />
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian<br />
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan<br />
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech<br />
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish<br />
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German<br />
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek<br />
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English<br />
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish<br />
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian <br />
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish<br />
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French<br />
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew <br />
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi<br />
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian<br />
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian<br />
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian<br />
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian<br />
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian<br />
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese<br />
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese <br />
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean<br />
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian<br />
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian<br />
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch<br />
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian<br />
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan<br />
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish<br />
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese<br />
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian<br />
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian<br />
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak<br />
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian <br />
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian <br />
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish<br />
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish <br />
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian<br />
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)<br />
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)<br />
<br />
== Debugging and Tracing ==<br />
<br />
To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.<br />
<br />
self::debug("Ahh!");<br />
self::dump('my_var',$my_var);<br />
<br />
See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Practical_debugging&diff=8940
Practical debugging
2021-07-27T14:45:33Z
<p>Een: Table of contents</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
This page gives you practical tips to debug your game during development. Don't hesitate to share your difficulties with us so that we can improve this section.<br />
<br />
__TOC__<br />
<br />
== Tools ==<br />
<br />
To work on BGA Studio, we recommend that you use [http://www.google.com/chrome Google Chrome] as it's currently the fastest browser for the BGA platform, and it's available for all OSes.<br />
<br />
Another reason to use Chrome is that it embeds all the tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").<br />
<br />
A good practice is to use a second browser to develop the game, in order to verify that your game is working fine on this browser too.<br />
<br />
To debug with Firefox browser, we advise you to use these 2 extensions:<br />
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]<br />
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developer]<br />
<br />
To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...<br />
<br />
== General tip for debugging ==<br />
<br />
=== Save & Restore ===<br />
<br />
In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.<br />
<br />
You can save up to 3 different states.<br />
<br />
=== Refresh ===<br />
<br />
If something does not seems to work properly even you "fixed it", it may be refresh issue. Not all files born equal. Some require a lot more steps to get into the game.<br />
<br />
See https://en.doc.boardgamearena.com/Studio_file_reference for information on how to "refresh" each files.<br />
<br />
== Debugging my game when it cannot start ==<br />
<br />
If your game won't start because of an error, you are probably in one of these situations:<br />
* There is a SQL error in your dbmodel.sql file.<br />
* You have a syntax error in your PHP file.<br />
* Your PHP "setup" - or any method used during the game initial states - generates an exception.<br />
<br />
If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].<br />
More cases of why game can't start are described on the [[Troubleshooting]] page.<br />
<br />
== Debugging an issue with the waiting screen ==<br />
<br />
BGA displays a waiting screen during a few seconds inviting free players to become premium when they are playing a lot.<br />
<br />
This waiting screen should not in principle impact your game, but in some cases it might.<br />
<br />
To test the waiting screen on the studio, you can set the desired duration by adding the get parameter studioLockingDuration with the number of seconds for the lock screen to be displayed. For example to have a 10 seconds waiting screen when you launch a game on the studio:<br />
https://studio.boardgamearena.com?studioLockingDuration=10<br />
<br />
Then you can just set it back to zero in the same way with https://studio.boardgamearena.com?studioLockingDuration=0 (or restart your browser to clear the session value).<br />
<br />
== Debugging my PHP game logic (or my view) ==<br />
<br />
<br />
=== Add traces to your code ===<br />
<br />
You can use the following functions in your game to add server side logging:<br />
<br />
'''self::dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]<br />
<br />
'''self::warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]<br />
<br />
'''self::error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]<br />
<br />
Check [[Studio logs]] for more details on how to access your logs.<br />
<br />
This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.<br />
<br />
Only the error log level will appear in production. This level should be used only for critical problems. <br />
Other levels will show only in the development environment and can be used as you see fit.<br />
<br />
'''WARNING''': tracing does not work in constructor, setupNewGame and game states immediately following starting state (not sure why). Use other method described below in this case (seciton "Debugging setupNewGame").<br />
<br />
=== Call php functions from chat ===<br />
<br />
This is best feature ever, you can call individual function in your game.php from chat window, see details<br />
at https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Run_PHP_functions_from_the_chat<br />
<br />
<br />
=== Dump data and die ===<br />
<br />
Most of the time, debugging PHP is quite easy. Here's what I do when I want to develop/debug some game logic that is triggered by some game action:<br />
<br />
* At first, I make sure that I can reproduce the needed game situation with one click. To do this, I use the "[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]" function.<br />
* Another possibility for this is to place a '''die('ok');''' PHP statement right after the PHP I am developing/debugging. This way, I make sure that every request will fail and then nothing will be committed to the database.<br />
* Then, I use the '''var_dump''' function to dump PHP variables and check what's wrong, until it works.<br />
<br />
Example:<br />
<pre><br />
<br />
// (...my code to debug)<br />
<br />
var_dump( $my_variable );<br />
die('ok');<br />
<br />
// (...my code to debug)<br />
<br />
</pre><br />
<br />
Now since this text will be returned back to client it will usually choke on this, but you can actually see it better if you wrap it some html, i.e.<br />
<pre><br />
echo "<pre>";<br />
var_dump( $my_variable );<br />
echo "&lt;/pre>";<br />
</pre><br />
<br />
=== Debug at home ===<br />
<br />
If you develop some complex logic it is better sometimes to stub all external calls and debug it locally using command line or IDE debugger for php.<br />
You can get some basic stubs here https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php<br />
<br />
To run php locally you need to wrap it into test or something, see example https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally<br />
<br />
=== Debugging setupNewGame ===<br />
<br />
This is separate section because tracing method do not work in this function.<br />
Recommended way to debug it <br />
* leave setupNewGame exactly as in template (inlcuding setting up player table and activating first player), and add a single call at the end<br />
$this->initTables();<br />
This will be your own function which you will be changing, so you don't touch setupNewGame anymore.<br />
<br />
Remember that this function cannot send notification or query active or current player. If you need to get player data use $this->loadPlayersBasicInfos().<br />
<br />
function initTables() {<br />
try {<br />
$players = $this->loadPlayersBasicInfos();<br />
// ... code the function<br />
} catch ( Exception $e ) {<br />
// logging does not actually work in game init :(<br />
// but if you calling from php chat it will work<br />
$this->error("Fatal error while creating game");<br />
$this->dump('err', $e);<br />
}<br />
}<br />
<br />
Create a code for this function, and if it does not work run it from the chat window of the just created game (i.e. 'initTables()' without quotes). That way you can see debug output!<br />
The only trick is you have to clear all your tables in the begging so when you run it multiple times your db does not puke.<br />
If your game does not start at all - do not even call it from setupNewGame, comment it out and only call from chat window until it works.<br />
Don't forget you can also look at tables in db using php-admin tool (link at the bottom of the game table in studio).<br />
<br />
The same problem exists if you game state immediately follow starting state (problem of debugging it without the logs), in this case create a dummy player state in which player just press OK that will transition<br />
to you game state, after you done debugging it remove the state and shortcut the transition to your game state.<br />
<br />
Instead of calling initTables directly you can call helper function instead from chat window which will also reset the client, i.e.<br />
function debug_initTables() {<br />
$this->deleteAllTables(); // this suppose to delete/reset all data - you have to implement this function<br />
$this->initTables();<br />
$newGameDatas = $this->getAllTableDatas(); // this is framework function<br />
$this->notifyPlayer($this->getActivePlayerId(), 'resetInterfaceWithAllDatas', '', $newGameDatas); // this is notification to reset all data <br />
$this->notifyAllPlayers("message",'setup called',[]);<br />
}<br />
<br />
== Debugging my HTML/CSS layout ==<br />
<br />
Example situations<br />
<br />
* Why doesn't my game element show up in the interface?<br />
* Why hasn't my CSS property been applied to this element?<br />
* Why is this game element displayed at this position?<br />
<br />
A useful tip when an element does not show up in the interface is to give it a red background:<br />
<pre><br />
#my_element {<br />
... some CSS definitions ...<br />
background-color: red;<br />
}<br />
</pre><br />
<br />
This way, you know if the element is not visible because of some CSS property or because of something else.<br />
<br />
Another tip: sometimes, changing a CSS property has no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.<br />
<br />
Using Chrome "Elements" tab (the first one), you can:<br />
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.<br />
* Using the "magnifying glass", you can click on any part of your game interface and check its HTML code and associated CSS styles.<br />
* You can even modify directly some CSS properties and see how it looks immediately in the game interface.<br />
<br />
When changing css you have to force reload (Ctrl+R). But it also reloads all images which is long, if you want it faster you can define this function in js file, and call it from Browser js console<br />
<pre><br />
// this goes outside dojo class - before or after<br />
function reloadCss() {<br />
var links = document.getElementsByTagName("link");<br />
for (var cl in links) {<br />
var link = links[cl];<br />
if (link.rel === "stylesheet" && link.href.includes("99999")) {<br />
var index = link.href.indexOf("?timestamp=");<br />
var href = link.href;<br />
if (index >= 0) {<br />
href = href.substring(0, index);<br />
}<br />
<br />
link.href = href + "?timestamp=" + Date.now();<br />
<br />
console.log("reloading " + link.href);<br />
}<br />
}<br />
}<br />
<br />
</pre><br />
<br />
For mobile its also handy to have this as button (studio only), this goes to setup() function in js:<br />
<pre><br />
// add reload Css debug button<br />
var parent = document.querySelector('.debug_section');<br />
if (parent) {<br />
var butt = dojo.create('a', { class: 'bgabutton bgabutton_gray', innerHTML: "Reload CSS" }, parent);<br />
dojo.connect(butt, 'onclick', () => reloadCss());<br />
}<br />
</pre><br />
=== Debugging Toolips CSS/Layout ===<br />
<br />
To inspect tooltip you need to pin it so it does not disappear.<br />
* Chrome tools:<br />
** Open dev tools and switch to Source tab to engage with debugger<br />
** Hover over you element until tooltip showing<br />
** Press F8 - that stops the JS, so tooltip should freeze<br />
** Now you can go to Elements tab and find your tooltip at the botton in dijitTooltip div<br />
** Don't forget to resume it again to continue (F8 again or resume button)<br />
* Other method: Open the console (dev tools) large enough window, hover to make the tooltip appear and alt + tab to focus the console that will cover the tooltip. That way the onmouseout will never be triggered.<br />
<br />
=== Debugging my Javascript game interface logic ===<br />
<br />
To debug javascript you just use embedded browser debugger, usually found in Source tab of dev tools (F12)<br />
<br />
Modern browsers also allow you to put breakpoints in your js code. It is in source tab, but its a bit difficult to find (your code that is), see picture below on how to insert breakpoints.<br />
<br />
[[File:Bga-debug.jpg]]<br />
<br />
The easier method is to add breakpoint directly into your code and reload.<br />
<br />
In Chrome, to add a breakpoint: add a line to your .js file<br />
<br />
<pre>debugger; </pre><br />
<br />
Refresh the page F5, and make sure you have the Developer tools window open, press F12. <br />
When the break-point is hit you can then step through your code and visualise variables, etc.<br />
<br />
=== Do complex things on the PHP side ===<br />
<br />
The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Do it in PHP, and transfer the results to your client interface using the "args" game state property.<br />
<br />
Note: See the Reversi tutorial for an example.<br />
<br />
=== Add traces in your code ===<br />
<br />
You can use the following:<br />
<br />
'''console.log( variable_to_inspect )'''<br />
<br />
It will give you the object structure of the variable in the Javascript console, without blocking the execution.<br />
<br />
It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.<br />
<br />
'''alert( variable_to_inspect )'''<br />
<br />
It will popup what you wish and pause the execution until you click ok.<br />
<br />
This won't be useful for complex structures; only native types will be plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.<br />
<br />
== Online format checkers ==<br />
Copy and paste code for a quick code sanity check like the right number of brackets.<br />
<br />
PHP: [https://phpcodechecker.com/ https://phpcodechecker.com/]<br />
<br />
JS: [http://esprima.org/demo/validate.html http://esprima.org/demo/validate.html]<br />
<br />
Checks for proper attributes values and browser's compatibility<br />
<br />
CSS: http://jigsaw.w3.org/css-validator/<br />
<br />
== Some frequent errors ==<br />
<br />
See [[Troubleshooting]].<br />
<br />
== Get the database matching a bug report ==<br />
<br />
When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:<br />
* Create a table in the studio with the same game and number of players as the table for which the report has been written. Launch this table.<br />
* Open another tab on the studio and go to "Manage game" page for your project (you have to be admin for this project)<br />
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.<br />
* If the snapshot is correctly retrieved, you see a "Done!" message.<br />
* Go back to the tab with your studio table and click "Load 1".<br />
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.<br />
** '''Important note:''' if you see a "Done!" message but clicking "Load 1" doesn't bring any change, it's that the snapshot is unfortunately not available (most likely because the bug report was declared too long after the game ended and the database had already been garbage collected to reclaim space).<br />
* Click on the "Go to game database" button<br />
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.<br />
* Tables to update:<br />
** player<br />
** global (value with ID 2 is the active player)<br />
** stats<br />
** tables specific to your schema that use player_ids<br />
* If your changes to player_ids are not taken into account, it may be a cache problem: use the "Clear PHP cache" button on your "Manage game" page.<br />
* Then you should be able to play with the same state of the game as when the report was created in production.<br />
* If the game has ended, you can place it again in the game state you want to debug by setting the value with ID 1 in the global table to the appropriate state value, and the value with ID 2 to the player you want active).<br />
*<br />
* Below is an example php function you may want to make. You can call this function from the chat window: LoadDebug() <br />
* change instances of 2308257, and 2308258 to you own BGA Studio logins YourLogin0 and YourLogin1<br />
* change $id0 and $id1 to the player_ids from the table you want to debug, and have recently imported.<br />
* Before you load Slot1, open a second tab with the table, because after loading the slot, that tab will be unusable. In the second tab you can call LoadDebug() in the chat window<br />
<br />
<pre><br />
public function LoadDebug()<br />
{<br />
// These are the id's from the BGAtable I need to debug.<br />
$ids = [<br />
86107517,<br />
86872172,<br />
85086097,<br />
84380410,<br />
11000525<br />
];<br />
<br />
// Id of the first player in BGA Studio<br />
$sid = 2296755;<br />
<br />
foreach ($ids as $id) {<br />
// basic tables<br />
self::DbQuery("UPDATE player SET player_id=$sid WHERE player_id = $id" );<br />
self::DbQuery("UPDATE global SET global_value=$sid WHERE global_value = $id" );<br />
self::DbQuery("UPDATE stats SET stats_player_id=$sid WHERE stats_player_id = $id" );<br />
<br />
// 'other' game specific tables. example:<br />
// tables specific to your schema that use player_ids<br />
self::DbQuery("UPDATE card SET card_location_arg=$sid WHERE card_location_arg = $id" );<br />
<br />
++$sid;<br />
}<br />
}<br />
</pre><br />
<br />
=== Fully automated version ===<br />
Thanks to quietmint for [https://boardgamearena.com/forum/viewtopic.php?f=12&t=16454#p63167 coming up] with that!<br />
<br />
; In ggg.php<br />
<pre><br />
/*<br />
* loadBug: in studio, type loadBug(20762) into the table chat to load a bug report from production<br />
* client side JavaScript will fetch each URL below in sequence, then refresh the page<br />
*/<br />
public function loadBug($reportId)<br />
{<br />
$db = explode('_', self::getUniqueValueFromDB("SELECT SUBSTRING_INDEX(DATABASE(), '_', -2)"));<br />
$game = $db[0];<br />
$tableId = $db[1];<br />
self::notifyAllPlayers('loadBug', "Trying to load <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a>", [<br />
'urls' => [<br />
// Emulates "load bug report" in control panel<br />
"https://studio.boardgamearena.com/admin/studio/getSavedGameStateFromProduction.html?game=$game&report_id=$reportId&table_id=$tableId",<br />
<br />
// Emulates "load 1" at this table<br />
"https://studio.boardgamearena.com/table/table/loadSaveState.html?table=$tableId&state=1",<br />
<br />
// Calls the function below to update SQL<br />
"https://studio.boardgamearena.com/1/$game/$game/loadBugSQL.html?table=$tableId&report_id=$reportId",<br />
<br />
// Emulates "clear PHP cache" in control panel<br />
// Needed at the end because BGA is caching player info<br />
"https://studio.boardgamearena.com/admin/studio/clearGameserverPhpCache.html?game=$game",<br />
]<br />
]);<br />
}<br />
<br />
/*<br />
* loadBugSQL: in studio, this is one of the URLs triggered by loadBug() above<br />
*/<br />
public function loadBugSQL($reportId)<br />
{<br />
$studioPlayer = self::getCurrentPlayerId();<br />
$players = self::getObjectListFromDb("SELECT player_id FROM player", true);<br />
<br />
// Change for your game<br />
// We are setting the current state to match the start of a player's turn if it's already game over<br />
$sql = [<br />
"UPDATE global SET global_value=2 WHERE global_id=1 AND global_value=99"<br />
];<br />
foreach ($players as $pId) {<br />
// All games can keep this SQL<br />
$sql[] = "UPDATE player SET player_id=$studioPlayer WHERE player_id=$pId";<br />
$sql[] = "UPDATE global SET global_value=$studioPlayer WHERE global_value=$pId";<br />
$sql[] = "UPDATE stats SET stats_player_id=$studioPlayer WHERE stats_player_id=$pId";<br />
<br />
// Add game-specific SQL update the tables for your game<br />
$sql[] = "UPDATE card SET card_location_arg=$studioPlayer WHERE card_location_arg=$pId";<br />
$sql[] = "UPDATE piece SET player_id=$studioPlayer WHERE player_id=$pId";<br />
$sql[] = "UPDATE log SET player_id=$studioPlayer WHERE player_id=$pId";<br />
$sql[] = "UPDATE log SET action_arg=REPLACE(action_arg, $pId, $studioPlayer)";<br />
<br />
// This could be improved, it assumes you had sequential studio accounts before loading<br />
// e.g., quietmint0, quietmint1, quietmint2, etc. are at the table<br />
$studioPlayer++;<br />
}<br />
$msg = <nowiki>"<b>Loaded <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a></b><hr><ul><li>" . implode(';</li><li>', $sql) . ';</li></ul>';</nowiki><br />
self::warn($msg);<br />
self::notifyAllPlayers('message', $msg, []);<br />
<br />
foreach ($sql as $q) {<br />
self::DbQuery($q);<br />
}<br />
self::reloadPlayersBasicInfos();<br />
}<br />
</pre><br />
<br />
; In ggg.action.php<br />
<pre><br />
public function loadBugSQL() {<br />
self::setAjaxMode();<br />
$reportId = (int) self::getArg('report_id', AT_int, true);<br />
$this->game->loadBugSQL($reportId);<br />
self::ajaxResponse();<br />
}<br />
</pre><br />
<br />
; In ggg.js<br />
<pre><br />
// Load production bug report handler<br />
dojo.subscribe("loadBug", this, function loadBug(n) {<br />
function fetchNextUrl() {<br />
var url = n.args.urls.shift();<br />
console.log("Fetching URL", url);<br />
dojo.xhrGet({<br />
url: url,<br />
load: function (success) {<br />
console.log("Success for URL", url, success);<br />
if (n.args.urls.length > 0) {<br />
fetchNextUrl();<br />
} else {<br />
console.log("Done, reloading page");<br />
window.location.reload();<br />
}<br />
},<br />
});<br />
}<br />
console.log("Notif: load bug", n.args);<br />
fetchNextUrl();<br />
});<br />
</pre></div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=8658
Game meta-information: gameinfos.inc.php
2021-07-01T07:51:36Z
<p>Een: Publisher/designer info</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Overview ==<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Most information provided in this file are self-explainable.<br />
<br />
See sections below for specific cases.<br />
<br />
<br />
== Publisher/Designer fields ==<br />
<br />
These fields should match the publisher/designer for the game. In the case of a public domain name, they should be left empty (empty string '')<br />
<br />
== Beta ==<br />
<br />
You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
<br />
== Time Profiles ==<br />
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
<br />
== Number of players ==<br />
<br />
'''players'''<br />
'players' => array( 3, 4, 6 ),<br />
<br />
* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.<br />
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.<br />
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.<br />
<br />
'''suggest_player_number''' / '''not_recommend_player_number'''<br />
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.<br />
<br />
<br />
== Colors ==<br />
<br />
'''player_colors'''<br />
'player_colors' => array( "ff0000", "008000", "0000ff", "ffa500", "ffffff" ),<br />
<br />
This array defines the default player colors, theoretically this can be bigger then maximum number of players but you have to support all of the in your game.<br />
Your setupNewGame in php is responsible for attributing these values to players. See section "Player color preferences" in [[Main_game_logic:_yourgamename.game.php]] for details.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
The score in this case should be 1 for the winner and 0 for the losers.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to false<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.<br />
<br />
Main game category (you MUST specify one tag AND ONLY ONE from this category):<br />
* 1: Abstract game<br />
* 2: Casual games<br />
* 3: For regular players<br />
* 4: For core gamers<br />
<br />
Other tags (you can specify any numbers of tags):<br />
* 10: Short game (<10 minutes)<br />
* 11: Medium length game (10 minutes to 30 minutes)<br />
* 12: Long game (>30mn)<br />
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* 22: Prototype (This game has not been published yet)<br />
* 23: Classic (This game is a classic from Public Domain)<br />
* 30: 2 players (2p game / best with 2 players)<br />
* 100: Fantasy theme<br />
* 101: Science Fiction them<br />
* 102: Historical theme<br />
* 103: Adventure<br />
* 104: Exploration<br />
* 105: Conquest<br />
* 106: Building<br />
* 200: Card game (Cards plays a central role in this game)<br />
* 201: Dice<br />
* 202: Solo game<br />
* 203: Worker placement<br />
* 204: Hand management<br />
* 205: Bluff<br />
* 206: Tile placement<br />
* 207: Combinations<br />
* 208: Majority<br />
* 209: Race<br />
* 210: Collection<br />
* 211: Cooperative game<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),<br />
<br />
== Tie breaker description ==<br />
Describe tie breaker score calculation (player_score_aux in player table).<br />
<br />
Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.<br />
<br />
Example:<br />
'tie_breaker_description' => totranslate('Number of remaining cards in hand"),<br />
<br />
== Language dependency ==<br />
<br />
If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]<br />
<br />
== Coop Elo Mode ==<br />
<br />
For cooperative games, by default players will earn as many Elo points as the score. <br />
<br />
For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill and/or where the number of players has a significant impact on the difficulty, we have to set up a reference scale for Elo points (between 1300 and 2500). Players regularly winning with a specific difficulty setting will have their Elo nearing this value asymptotically over time.<br />
<br />
For this, you have to set up the coop_elo_mode parameter.<br />
<br />
Here is an example using options and win/loss (score 1/0):<br />
<br />
'coop_elo_mode' => [<br />
'type' => 'points_references',<br />
'references' => [<br />
// Difficulty 1<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
// Difficulty 2<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
// Difficulty 3<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
// Difficulty 4<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
// Difficulty 5<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
],<br />
],<br />
<br />
Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:<br />
<br />
'coop_elo_mode' => array(<br />
'type' => 'points_references',<br />
'references' => array(<br />
array(<br />
'players_nbr' => 2,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1350,<br />
2 => 1425,<br />
3 => 1500,<br />
4 => 1576,<br />
5 => 1651,<br />
6 => 1727,<br />
7 => 1802,<br />
8 => 1878,<br />
9 => 1953,<br />
10 => 2029,<br />
11 => 2104,<br />
12 => 2180<br />
)<br />
),<br />
array(<br />
'players_nbr' => 3,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1400,<br />
2 => 1470,<br />
3 => 1541,<br />
4 => 1612,<br />
5 => 1683,<br />
6 => 1754,<br />
7 => 1825,<br />
8 => 1895,<br />
9 => 1966,<br />
10 => 2018,<br />
11 => 2095,<br />
12 => 2250<br />
)<br />
),<br />
array(<br />
'players_nbr' => 4,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1430,<br />
2 => 1505,<br />
3 => 1580,<br />
4 => 1655,<br />
5 => 1730,<br />
6 => 1805,<br />
7 => 1880,<br />
8 => 1955,<br />
9 => 2030,<br />
10 => 2105,<br />
11 => 2180,<br />
12 => 2330<br />
)<br />
),<br />
array(<br />
'players_nbr' => 5,<br />
// 'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1480,<br />
2 => 1558,<br />
3 => 1636,<br />
4 => 1714,<br />
5 => 1792,<br />
6 => 1870,<br />
7 => 1949,<br />
8 => 2027,<br />
9 => 2105,<br />
10 => 2183,<br />
11 => 2261,<br />
12 => 2340<br />
)<br />
)<br />
)<br />
),</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Translations&diff=8624
Translations
2021-06-30T08:41:51Z
<p>Een: /* What do I have to do from a programming standpoint? */ Fix misunderstanding about gameoptions/stats translations</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
<br />
Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.<br />
<br />
== Localization Overview ==<br />
<br />
Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.<br />
<br />
It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.<br />
<br />
For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.<br />
<br />
<br />
== How will my strings be translated? ==<br />
<br />
When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.<br />
<br />
Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".<br />
<br />
<br />
== What do I have to do from a programming standpoint? ==<br />
<br />
Not as much as you think. Read on for full details, but the golden rules are:<br />
<br />
<br />
<br />
# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.<br />
# On the client side, just display your text, but wrap it in _().<br />
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.<br />
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.<br />
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.<br />
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.<br />
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.<br />
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.<br />
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.<br />
<br />
== What strings should be translated? ==<br />
<br />
Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.<br />
<br />
This does NOT include error messages that are not supposed to happen (unexpected errors).<br />
<br />
<br />
== What rules should I follow for the original English strings? ==<br />
<br />
For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'<br />
<br />
* As a general rule:<br />
** If a sentence is displayed isolated in the interface => no final period<br />
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.<br />
<br />
* In detail:<br />
** No final period:<br />
*** button labels<br />
*** section titles<br />
*** menu elements<br />
*** links triggering an isolated action<br />
*** anything that is not a full sentence<br />
*** current actions in the status bar<br />
** Final period:<br />
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences<br />
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:<br />
*** isolated tooltips / small sentences<br />
*** game logs (no period is usually preferable)<br />
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)<br />
<br />
Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.<br />
<br />
<br />
== Focus on translating notifications ==<br />
<br />
Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.<br />
<br />
However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.<br />
<br />
== How to not make translators crazy ;) ==<br />
<br />
* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.<br />
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre><br />
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.<br />
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).<br />
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:<br />
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre><br />
Write instead:<br />
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre><br />
(or the equivalent "dojo.string.substitute" in Javascript)<br />
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.<br />
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.<br />
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".<br />
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".<br />
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.<br />
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.<br />
<br />
== WARNING: Make sure your strings will be translated! ==<br />
<br />
For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)<br />
<br />
If your original string is not completely contained inside one of these markers, it won't be translated.<br />
<br />
<pre><br />
// Examples: the following strings will be translated:<br />
var mystring_translated = _("my string"); // JS<br />
$mystring_translated = self::_("my string"); // PHP<br />
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP<br />
<br />
// Examples: the following strings WILL NOT be translated:<br />
$my_string = "my string";<br />
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation<br />
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto<br />
</pre><br />
<br />
== On client side (Javascript) ==<br />
<br />
On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.<br />
<br />
Examples:<br />
<pre><br />
// Get a string in player's language:<br />
var translated = _("original english string");<br />
<br />
// Get a string in player's language with parameter:<br />
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {<br />
p: 2,<br />
d: 4<br />
} );<br />
</pre><br />
<br />
'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.<br />
<br />
'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method<br />
<br />
== On server side (PHP) ==<br />
<br />
On PHP side, you can use 3 different functions to specify that a string must be translated.<br />
<br />
'''clienttranslate( "string to translate" ):'''<br />
<br />
This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.<br />
<br />
In general, you use clienttranslate:<br />
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".<br />
<br />
<pre><br />
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),<br />
</pre><br />
<br />
* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.<br />
<br />
<pre><br />
$this->card_types = array(<br />
<br />
1 => array(<br />
'name' => clienttranslate("Amulet of Air"), // Thus, we can use "_( card_name )" on Javascript side.<br />
</pre><br />
<br />
* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.<br />
<br />
<pre><br />
// A game log string with no argument:<br />
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate("Everyone draw cards from their library"), array() );<br />
</pre><br />
<br />
As a consequence there is no point passing variables to this function. E.g.:<br />
<br />
<pre><br />
notif="foo";<br />
self::notifyAllPlayers( 'log', clienttranslate(notif)); // BAD<br />
<br />
notif=clienttranslate("foo");<br />
self::notifyAllPlayers( 'log', notif); // GOOD<br />
</pre><br />
<br />
Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:<br />
<br />
<pre><br />
// In the following example, we translate the game log itself, but also the "card_name" argument:<br />
<br />
self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(<br />
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'points' => $points,<br />
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.<br />
) ); <br />
</pre><br />
<br />
To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:<br />
<br />
<pre><br />
$this->card_types = array(<br />
...<br />
8 => array(<br />
'name' => clienttranslate("Amulet of Fire"),<br />
...<br />
</pre><br />
<br />
Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.<br />
<br />
'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).<br />
<br />
'''self::_( "my string to translate" ):'''<br />
<br />
This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).<br />
<br />
Most of the time, you don't need to translate strings on server side, except on the following 3 situations:<br />
* When throwing an exception because the player did a forbidden move.<br />
<br />
<pre><br />
// This will display a translatable red message to the player that just did some wrong action:<br />
throw new BgaUserException( self::_('You must choose 3 cards') );<br />
<br />
// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.<br />
</pre><br />
<br />
* In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.<br />
<br />
<pre><br />
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");<br />
</pre><br />
<br />
'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.<br />
<br />
* Eventually, in your material.inc.php, if for example you need to use some string elements in your exceptions.<br />
<br />
<pre><br />
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:<br />
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );<br />
</pre><br />
<br />
* Eventually, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.<br />
<br />
'''totranslate( "my string to translate" ):'''<br />
<br />
This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.<br />
<br />
You should not use this function, except on the following cases:<br />
* Statistics name in stats.inc.php<br />
* Option names and option values name in gameoptions.inc.php<br />
<br />
<br />
== Top Secret Undocumented Feature ==<br />
<br />
If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.<br />
<br />
== On server side - advanced (PHP) ==<br />
<br />
If you want to use translation system in your custom static modules, you will first need to expose the _() function :<br />
<pre><br />
class mygame extends Table {<br />
// Exposing protected method translation<br />
public static function totranslate($text) {<br />
return self::_($text);<br />
}<br />
}<br />
</pre><br />
<br />
Then you'll be able to use this directly in other modules by doing<br />
<pre><br />
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));<br />
</pre><br />
<br />
Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :<br />
<pre><br />
$msg = "Translated error from my awesome module file";<br />
throw new BgaUserException(mygame::totranslate($msg));<br />
</pre></div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=8605
Game meta-information: gameinfos.inc.php
2021-06-27T09:15:56Z
<p>Een: /* Coop Elo Mode */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Overview ==<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Most information provided in this file are self-explainable.<br />
<br />
See sections below for specific cases.<br />
<br />
== Beta ==<br />
<br />
You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
<br />
== Time Profiles ==<br />
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
<br />
== Number of players ==<br />
<br />
'''players'''<br />
'players' => array( 3, 4, 6 ),<br />
<br />
* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.<br />
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.<br />
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.<br />
<br />
'''suggest_player_number''' / '''not_recommend_player_number'''<br />
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.<br />
<br />
<br />
== Colors ==<br />
<br />
'''player_colors'''<br />
'player_colors' => array( "ff0000", "008000", "0000ff", "ffa500", "ffffff" ),<br />
<br />
This array defines the default player colors, theoretically this can be bigger then maximum number of players but you have to support all of the in your game.<br />
Your setupNewGame in php is responsible for attributing these values to players. See section "Player color preferences" in [[Main_game_logic:_yourgamename.game.php]] for details.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
The score in this case should be 1 for the winner and 0 for the losers.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to false<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.<br />
<br />
Main game category (you MUST specify one tag AND ONLY ONE from this category):<br />
* 1: Abstract game<br />
* 2: Casual games<br />
* 3: For regular players<br />
* 4: For core gamers<br />
<br />
Other tags (you can specify any numbers of tags):<br />
* 10: Short game (<10 minutes)<br />
* 11: Medium length game (10 minutes to 30 minutes)<br />
* 12: Long game (>30mn)<br />
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* 22: Prototype (This game has not been published yet)<br />
* 23: Classic (This game is a classic from Public Domain)<br />
* 30: 2 players (2p game / best with 2 players)<br />
* 100: Fantasy theme<br />
* 101: Science Fiction them<br />
* 102: Historical theme<br />
* 103: Adventure<br />
* 104: Exploration<br />
* 105: Conquest<br />
* 106: Building<br />
* 200: Card game (Cards plays a central role in this game)<br />
* 201: Dice<br />
* 202: Solo game<br />
* 203: Worker placement<br />
* 204: Hand management<br />
* 205: Bluff<br />
* 206: Tile placement<br />
* 207: Combinations<br />
* 208: Majority<br />
* 209: Race<br />
* 210: Collection<br />
* 211: Cooperative game<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),<br />
<br />
== Tie breaker description ==<br />
Describe tie breaker score calculation (player_score_aux in player table).<br />
<br />
Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.<br />
<br />
Example:<br />
'tie_breaker_description' => totranslate('Number of remaining cards in hand"),<br />
<br />
== Language dependency ==<br />
<br />
If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]<br />
<br />
== Coop Elo Mode ==<br />
<br />
For cooperative games, by default players will earn as many Elo points as the score. <br />
<br />
For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill and/or where the number of players has a significant impact on the difficulty, we have to set up a reference scale for Elo points (between 1300 and 2500). Players regularly winning with a specific difficulty setting will have their Elo nearing this value asymptotically over time.<br />
<br />
For this, you have to set up the coop_elo_mode parameter.<br />
<br />
Here is an example using options and win/loss (score 1/0):<br />
<br />
'coop_elo_mode' => [<br />
'type' => 'points_references',<br />
'references' => [<br />
// Difficulty 1<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
// Difficulty 2<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
// Difficulty 3<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
// Difficulty 4<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
// Difficulty 5<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
],<br />
],<br />
<br />
Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:<br />
<br />
'coop_elo_mode' => array(<br />
'type' => 'points_references',<br />
'references' => array(<br />
array(<br />
'players_nbr' => 2,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1350,<br />
2 => 1425,<br />
3 => 1500,<br />
4 => 1576,<br />
5 => 1651,<br />
6 => 1727,<br />
7 => 1802,<br />
8 => 1878,<br />
9 => 1953,<br />
10 => 2029,<br />
11 => 2104,<br />
12 => 2180<br />
)<br />
),<br />
array(<br />
'players_nbr' => 3,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1400,<br />
2 => 1470,<br />
3 => 1541,<br />
4 => 1612,<br />
5 => 1683,<br />
6 => 1754,<br />
7 => 1825,<br />
8 => 1895,<br />
9 => 1966,<br />
10 => 2018,<br />
11 => 2095,<br />
12 => 2250<br />
)<br />
),<br />
array(<br />
'players_nbr' => 4,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1430,<br />
2 => 1505,<br />
3 => 1580,<br />
4 => 1655,<br />
5 => 1730,<br />
6 => 1805,<br />
7 => 1880,<br />
8 => 1955,<br />
9 => 2030,<br />
10 => 2105,<br />
11 => 2180,<br />
12 => 2330<br />
)<br />
),<br />
array(<br />
'players_nbr' => 5,<br />
// 'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1480,<br />
2 => 1558,<br />
3 => 1636,<br />
4 => 1714,<br />
5 => 1792,<br />
6 => 1870,<br />
7 => 1949,<br />
8 => 2027,<br />
9 => 2105,<br />
10 => 2183,<br />
11 => 2261,<br />
12 => 2340<br />
)<br />
)<br />
)<br />
),</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=8568
Game meta-information: gameinfos.inc.php
2021-06-22T09:32:38Z
<p>Een: /* Coop Elo Mode */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Overview ==<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Most information provided in this file are self-explainable.<br />
<br />
See sections below for specific cases.<br />
<br />
== Beta ==<br />
<br />
You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
<br />
== Time Profiles ==<br />
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
<br />
== Number of players ==<br />
<br />
'''players'''<br />
'players' => array( 3, 4, 6 ),<br />
<br />
* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.<br />
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.<br />
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.<br />
<br />
'''suggest_player_number''' / '''not_recommend_player_number'''<br />
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
The score in this case should be 1 for the winner and 0 for the losers.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to false<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.<br />
<br />
Main game category (you MUST specify one tag AND ONLY ONE from this category):<br />
* 1: Abstract game<br />
* 2: Casual games<br />
* 3: For regular players<br />
* 4: For core gamers<br />
<br />
Other tags (you can specify any numbers of tags):<br />
* 10: Short game (<10 minutes)<br />
* 11: Medium length game (10 minutes to 30 minutes)<br />
* 12: Long game (>30mn)<br />
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* 22: Prototype (This game has not been published yet)<br />
* 23: Classic (This game is a classic from Public Domain)<br />
* 30: 2 players (2p game / best with 2 players)<br />
* 100: Fantasy theme<br />
* 101: Science Fiction them<br />
* 102: Historical theme<br />
* 103: Adventure<br />
* 104: Exploration<br />
* 105: Conquest<br />
* 106: Building<br />
* 200: Card game (Cards plays a central role in this game)<br />
* 201: Dice<br />
* 202: Solo game<br />
* 203: Worker placement<br />
* 204: Hand management<br />
* 205: Bluff<br />
* 206: Tile placement<br />
* 207: Combinations<br />
* 208: Majority<br />
* 209: Race<br />
* 210: Collection<br />
* 211: Cooperative game<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),<br />
<br />
== Tie breaker description ==<br />
Describe tie breaker score calculation (player_score_aux in player table).<br />
<br />
Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.<br />
<br />
Example:<br />
'tie_breaker_description' => totranslate('Number of remaining cards in hand"),<br />
<br />
== Language dependency ==<br />
<br />
If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]<br />
<br />
== Coop Elo Mode ==<br />
<br />
For cooperative games, by default players will earn as many Elo points as the score. <br />
<br />
For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill and/or where the number of players has a significant impact on the difficulty, we have to set up a reference scale for Elo points (between 1000 and 2500). Players regularly winning with a specific difficulty setting will have their Elo nearing this value asymptotically over time.<br />
<br />
For this, you have to set up the coop_elo_mode parameter.<br />
<br />
Here is an example using options and win/loss (score 1/0):<br />
<br />
'coop_elo_mode' => [<br />
'type' => 'points_references',<br />
'references' => [<br />
// Difficulty 1<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
// Difficulty 2<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
// Difficulty 3<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
// Difficulty 4<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
// Difficulty 5<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
],<br />
],<br />
<br />
Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:<br />
<br />
'coop_elo_mode' => array(<br />
'type' => 'points_references',<br />
'references' => array(<br />
array(<br />
'players_nbr' => 2,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1350,<br />
2 => 1425,<br />
3 => 1500,<br />
4 => 1576,<br />
5 => 1651,<br />
6 => 1727,<br />
7 => 1802,<br />
8 => 1878,<br />
9 => 1953,<br />
10 => 2029,<br />
11 => 2104,<br />
12 => 2180<br />
)<br />
),<br />
array(<br />
'players_nbr' => 3,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1400,<br />
2 => 1470,<br />
3 => 1541,<br />
4 => 1612,<br />
5 => 1683,<br />
6 => 1754,<br />
7 => 1825,<br />
8 => 1895,<br />
9 => 1966,<br />
10 => 2018,<br />
11 => 2095,<br />
12 => 2250<br />
)<br />
),<br />
array(<br />
'players_nbr' => 4,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1430,<br />
2 => 1505,<br />
3 => 1580,<br />
4 => 1655,<br />
5 => 1730,<br />
6 => 1805,<br />
7 => 1880,<br />
8 => 1955,<br />
9 => 2030,<br />
10 => 2105,<br />
11 => 2180,<br />
12 => 2330<br />
)<br />
),<br />
array(<br />
'players_nbr' => 5,<br />
// 'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1480,<br />
2 => 1558,<br />
3 => 1636,<br />
4 => 1714,<br />
5 => 1792,<br />
6 => 1870,<br />
7 => 1949,<br />
8 => 2027,<br />
9 => 2105,<br />
10 => 2183,<br />
11 => 2261,<br />
12 => 2340<br />
)<br />
)<br />
)<br />
),</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=8567
Game meta-information: gameinfos.inc.php
2021-06-22T08:44:10Z
<p>Een: /* Coop Elo Mode */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Overview ==<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Most information provided in this file are self-explainable.<br />
<br />
See sections below for specific cases.<br />
<br />
== Beta ==<br />
<br />
You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
<br />
== Time Profiles ==<br />
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
<br />
== Number of players ==<br />
<br />
'''players'''<br />
'players' => array( 3, 4, 6 ),<br />
<br />
* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.<br />
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.<br />
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.<br />
<br />
'''suggest_player_number''' / '''not_recommend_player_number'''<br />
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
The score in this case should be 1 for the winner and 0 for the losers.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to false<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.<br />
<br />
Main game category (you MUST specify one tag AND ONLY ONE from this category):<br />
* 1: Abstract game<br />
* 2: Casual games<br />
* 3: For regular players<br />
* 4: For core gamers<br />
<br />
Other tags (you can specify any numbers of tags):<br />
* 10: Short game (<10 minutes)<br />
* 11: Medium length game (10 minutes to 30 minutes)<br />
* 12: Long game (>30mn)<br />
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* 22: Prototype (This game has not been published yet)<br />
* 23: Classic (This game is a classic from Public Domain)<br />
* 30: 2 players (2p game / best with 2 players)<br />
* 100: Fantasy theme<br />
* 101: Science Fiction them<br />
* 102: Historical theme<br />
* 103: Adventure<br />
* 104: Exploration<br />
* 105: Conquest<br />
* 106: Building<br />
* 200: Card game (Cards plays a central role in this game)<br />
* 201: Dice<br />
* 202: Solo game<br />
* 203: Worker placement<br />
* 204: Hand management<br />
* 205: Bluff<br />
* 206: Tile placement<br />
* 207: Combinations<br />
* 208: Majority<br />
* 209: Race<br />
* 210: Collection<br />
* 211: Cooperative game<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),<br />
<br />
== Tie breaker description ==<br />
Describe tie breaker score calculation (player_score_aux in player table).<br />
<br />
Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.<br />
<br />
Example:<br />
'tie_breaker_description' => totranslate('Number of remaining cards in hand"),<br />
<br />
== Language dependency ==<br />
<br />
If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]<br />
<br />
== Coop Elo Mode ==<br />
<br />
For cooperative games, by default players will earn as many Elo points as the score. <br />
<br />
For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill, you have to set up a reference scale for Elo points between 1000 and 2500. Players regularly winning with a specific difficulty setting will have their Elo nearing this value asymptotically over time.<br />
<br />
For this, you have to set up the coop_elo_mode parameter. <br />
<br />
Here is an example using options and win/loss (score 1/0):<br />
<br />
'coop_elo_mode' => [<br />
'type' => 'points_references',<br />
'references' => [<br />
// Difficulty 1<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
// Difficulty 2<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
// Difficulty 3<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
// Difficulty 4<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
// Difficulty 5<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
],<br />
],<br />
<br />
Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:<br />
<br />
'coop_elo_mode' => array(<br />
'type' => 'points_references',<br />
'references' => array(<br />
array(<br />
'players_nbr' => 2,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1350,<br />
2 => 1425,<br />
3 => 1500,<br />
4 => 1576,<br />
5 => 1651,<br />
6 => 1727,<br />
7 => 1802,<br />
8 => 1878,<br />
9 => 1953,<br />
10 => 2029,<br />
11 => 2104,<br />
12 => 2180<br />
)<br />
),<br />
array(<br />
'players_nbr' => 3,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1400,<br />
2 => 1470,<br />
3 => 1541,<br />
4 => 1612,<br />
5 => 1683,<br />
6 => 1754,<br />
7 => 1825,<br />
8 => 1895,<br />
9 => 1966,<br />
10 => 2018,<br />
11 => 2095,<br />
12 => 2250<br />
)<br />
),<br />
array(<br />
'players_nbr' => 4,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1430,<br />
2 => 1505,<br />
3 => 1580,<br />
4 => 1655,<br />
5 => 1730,<br />
6 => 1805,<br />
7 => 1880,<br />
8 => 1955,<br />
9 => 2030,<br />
10 => 2105,<br />
11 => 2180,<br />
12 => 2330<br />
)<br />
),<br />
array(<br />
'players_nbr' => 5,<br />
// 'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1480,<br />
2 => 1558,<br />
3 => 1636,<br />
4 => 1714,<br />
5 => 1792,<br />
6 => 1870,<br />
7 => 1949,<br />
8 => 2027,<br />
9 => 2105,<br />
10 => 2183,<br />
11 => 2261,<br />
12 => 2340<br />
)<br />
)<br />
)<br />
),</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=8566
Game meta-information: gameinfos.inc.php
2021-06-22T08:41:54Z
<p>Een: /* Coop Elo Mode */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Overview ==<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Most information provided in this file are self-explainable.<br />
<br />
See sections below for specific cases.<br />
<br />
== Beta ==<br />
<br />
You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
<br />
== Time Profiles ==<br />
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
<br />
== Number of players ==<br />
<br />
'''players'''<br />
'players' => array( 3, 4, 6 ),<br />
<br />
* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.<br />
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.<br />
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.<br />
<br />
'''suggest_player_number''' / '''not_recommend_player_number'''<br />
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
The score in this case should be 1 for the winner and 0 for the losers.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to false<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.<br />
<br />
Main game category (you MUST specify one tag AND ONLY ONE from this category):<br />
* 1: Abstract game<br />
* 2: Casual games<br />
* 3: For regular players<br />
* 4: For core gamers<br />
<br />
Other tags (you can specify any numbers of tags):<br />
* 10: Short game (<10 minutes)<br />
* 11: Medium length game (10 minutes to 30 minutes)<br />
* 12: Long game (>30mn)<br />
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* 22: Prototype (This game has not been published yet)<br />
* 23: Classic (This game is a classic from Public Domain)<br />
* 30: 2 players (2p game / best with 2 players)<br />
* 100: Fantasy theme<br />
* 101: Science Fiction them<br />
* 102: Historical theme<br />
* 103: Adventure<br />
* 104: Exploration<br />
* 105: Conquest<br />
* 106: Building<br />
* 200: Card game (Cards plays a central role in this game)<br />
* 201: Dice<br />
* 202: Solo game<br />
* 203: Worker placement<br />
* 204: Hand management<br />
* 205: Bluff<br />
* 206: Tile placement<br />
* 207: Combinations<br />
* 208: Majority<br />
* 209: Race<br />
* 210: Collection<br />
* 211: Cooperative game<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),<br />
<br />
== Tie breaker description ==<br />
Describe tie breaker score calculation (player_score_aux in player table).<br />
<br />
Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.<br />
<br />
Example:<br />
'tie_breaker_description' => totranslate('Number of remaining cards in hand"),<br />
<br />
== Language dependency ==<br />
<br />
If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]<br />
<br />
== Coop Elo Mode ==<br />
<br />
For cooperative games, by default players will earn as many Elo points as the score. <br />
<br />
For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill, you have to set up a reference scale for Elo points.<br />
<br />
For this, you have to set up the coop_elo_mode parameter. <br />
<br />
Here is an example using options and win/loss (score 1/0):<br />
<br />
'coop_elo_mode' => [<br />
'type' => 'points_references',<br />
'references' => [<br />
// Difficulty 1<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
// Difficulty 2<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
// Difficulty 3<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
// Difficulty 4<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
// Difficulty 5<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
],<br />
],<br />
<br />
Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:<br />
<br />
'coop_elo_mode' => array(<br />
'type' => 'points_references',<br />
'references' => array(<br />
array(<br />
'players_nbr' => 2,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1350,<br />
2 => 1425,<br />
3 => 1500,<br />
4 => 1576,<br />
5 => 1651,<br />
6 => 1727,<br />
7 => 1802,<br />
8 => 1878,<br />
9 => 1953,<br />
10 => 2029,<br />
11 => 2104,<br />
12 => 2180<br />
)<br />
),<br />
array(<br />
'players_nbr' => 3,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1400,<br />
2 => 1470,<br />
3 => 1541,<br />
4 => 1612,<br />
5 => 1683,<br />
6 => 1754,<br />
7 => 1825,<br />
8 => 1895,<br />
9 => 1966,<br />
10 => 2018,<br />
11 => 2095,<br />
12 => 2250<br />
)<br />
),<br />
array(<br />
'players_nbr' => 4,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1430,<br />
2 => 1505,<br />
3 => 1580,<br />
4 => 1655,<br />
5 => 1730,<br />
6 => 1805,<br />
7 => 1880,<br />
8 => 1955,<br />
9 => 2030,<br />
10 => 2105,<br />
11 => 2180,<br />
12 => 2330<br />
)<br />
),<br />
array(<br />
'players_nbr' => 5,<br />
// 'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1480,<br />
2 => 1558,<br />
3 => 1636,<br />
4 => 1714,<br />
5 => 1792,<br />
6 => 1870,<br />
7 => 1949,<br />
8 => 2027,<br />
9 => 2105,<br />
10 => 2183,<br />
11 => 2261,<br />
12 => 2340<br />
)<br />
)<br />
)<br />
),</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=8565
Game meta-information: gameinfos.inc.php
2021-06-22T08:39:19Z
<p>Een: /* Number of players */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Overview ==<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Most information provided in this file are self-explainable.<br />
<br />
See sections below for specific cases.<br />
<br />
== Beta ==<br />
<br />
You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
<br />
== Time Profiles ==<br />
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
<br />
== Number of players ==<br />
<br />
'''players'''<br />
'players' => array( 3, 4, 6 ),<br />
<br />
* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.<br />
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.<br />
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.<br />
<br />
'''suggest_player_number''' / '''not_recommend_player_number'''<br />
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
The score in this case should be 1 for the winner and 0 for the losers.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to false<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.<br />
<br />
Main game category (you MUST specify one tag AND ONLY ONE from this category):<br />
* 1: Abstract game<br />
* 2: Casual games<br />
* 3: For regular players<br />
* 4: For core gamers<br />
<br />
Other tags (you can specify any numbers of tags):<br />
* 10: Short game (<10 minutes)<br />
* 11: Medium length game (10 minutes to 30 minutes)<br />
* 12: Long game (>30mn)<br />
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* 22: Prototype (This game has not been published yet)<br />
* 23: Classic (This game is a classic from Public Domain)<br />
* 30: 2 players (2p game / best with 2 players)<br />
* 100: Fantasy theme<br />
* 101: Science Fiction them<br />
* 102: Historical theme<br />
* 103: Adventure<br />
* 104: Exploration<br />
* 105: Conquest<br />
* 106: Building<br />
* 200: Card game (Cards plays a central role in this game)<br />
* 201: Dice<br />
* 202: Solo game<br />
* 203: Worker placement<br />
* 204: Hand management<br />
* 205: Bluff<br />
* 206: Tile placement<br />
* 207: Combinations<br />
* 208: Majority<br />
* 209: Race<br />
* 210: Collection<br />
* 211: Cooperative game<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),<br />
<br />
== Tie breaker description ==<br />
Describe tie breaker score calculation (player_score_aux in player table).<br />
<br />
Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.<br />
<br />
Example:<br />
'tie_breaker_description' => totranslate('Number of remaining cards in hand"),<br />
<br />
== Language dependency ==<br />
<br />
If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]<br />
<br />
== Coop Elo Mode ==<br />
<br />
For cooperative games, by default players will earn as many Elo points as the score. <br />
<br />
For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill, you have to set up a reference scale for Elo points.<br />
<br />
For this, you have to set up the coop_elo_mode parameter. <br />
<br />
Here is an example using options and win/loss (score 1/0):<br />
<br />
'coop_elo_mode' => [<br />
'type' => 'points_references',<br />
'references' => [<br />
// Difficulty 1<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
// Difficulty 2<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
// Difficulty 3<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
// Difficulty 4<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
// Difficulty 5<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
],<br />
],<br />
<br />
Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:<br />
<br />
'coop_elo_mode' => array(<br />
'type' => 'points_references',<br />
'references' => array(<br />
// see tgtEloPoints() in tranquility.game.php<br />
array(<br />
'players_nbr' => 2,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1350,<br />
2 => 1425,<br />
3 => 1500,<br />
4 => 1576,<br />
5 => 1651,<br />
6 => 1727,<br />
7 => 1802,<br />
8 => 1878,<br />
9 => 1953,<br />
10 => 2029,<br />
11 => 2104,<br />
12 => 2180<br />
)<br />
),<br />
array(<br />
'players_nbr' => 3,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1400,<br />
2 => 1470,<br />
3 => 1541,<br />
4 => 1612,<br />
5 => 1683,<br />
6 => 1754,<br />
7 => 1825,<br />
8 => 1895,<br />
9 => 1966,<br />
10 => 2018,<br />
11 => 2095,<br />
12 => 2250<br />
)<br />
),<br />
array(<br />
'players_nbr' => 4,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1430,<br />
2 => 1505,<br />
3 => 1580,<br />
4 => 1655,<br />
5 => 1730,<br />
6 => 1805,<br />
7 => 1880,<br />
8 => 1955,<br />
9 => 2030,<br />
10 => 2105,<br />
11 => 2180,<br />
12 => 2330<br />
)<br />
),<br />
array(<br />
'players_nbr' => 5,<br />
// 'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1480,<br />
2 => 1558,<br />
3 => 1636,<br />
4 => 1714,<br />
5 => 1792,<br />
6 => 1870,<br />
7 => 1949,<br />
8 => 2027,<br />
9 => 2105,<br />
10 => 2183,<br />
11 => 2261,<br />
12 => 2340<br />
)<br />
)<br />
)<br />
),</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=8564
Game meta-information: gameinfos.inc.php
2021-06-22T08:37:21Z
<p>Een: /* Coop Elo Mode */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Overview ==<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Most information provided in this file are self-explainable.<br />
<br />
See sections below for specific cases.<br />
<br />
== Beta ==<br />
<br />
You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
<br />
== Time Profiles ==<br />
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
<br />
== Number of players ==<br />
<br />
'''players'''<br />
'players' => array( 3, 4, 6 ),<br />
<br />
** during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.<br />
** if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.<br />
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.<br />
<br />
'''suggest_player_number''' / '''not_recommend_player_number'''<br />
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
The score in this case should be 1 for the winner and 0 for the losers.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to false<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.<br />
<br />
Main game category (you MUST specify one tag AND ONLY ONE from this category):<br />
* 1: Abstract game<br />
* 2: Casual games<br />
* 3: For regular players<br />
* 4: For core gamers<br />
<br />
Other tags (you can specify any numbers of tags):<br />
* 10: Short game (<10 minutes)<br />
* 11: Medium length game (10 minutes to 30 minutes)<br />
* 12: Long game (>30mn)<br />
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* 22: Prototype (This game has not been published yet)<br />
* 23: Classic (This game is a classic from Public Domain)<br />
* 30: 2 players (2p game / best with 2 players)<br />
* 100: Fantasy theme<br />
* 101: Science Fiction them<br />
* 102: Historical theme<br />
* 103: Adventure<br />
* 104: Exploration<br />
* 105: Conquest<br />
* 106: Building<br />
* 200: Card game (Cards plays a central role in this game)<br />
* 201: Dice<br />
* 202: Solo game<br />
* 203: Worker placement<br />
* 204: Hand management<br />
* 205: Bluff<br />
* 206: Tile placement<br />
* 207: Combinations<br />
* 208: Majority<br />
* 209: Race<br />
* 210: Collection<br />
* 211: Cooperative game<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),<br />
<br />
== Tie breaker description ==<br />
Describe tie breaker score calculation (player_score_aux in player table).<br />
<br />
Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.<br />
<br />
Example:<br />
'tie_breaker_description' => totranslate('Number of remaining cards in hand"),<br />
<br />
== Language dependency ==<br />
<br />
If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]<br />
<br />
== Coop Elo Mode ==<br />
<br />
For cooperative games, by default players will earn as many Elo points as the score. <br />
<br />
For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill, you have to set up a reference scale for Elo points.<br />
<br />
For this, you have to set up the coop_elo_mode parameter. <br />
<br />
Here is an example using options and win/loss (score 1/0):<br />
<br />
'coop_elo_mode' => [<br />
'type' => 'points_references',<br />
'references' => [<br />
// Difficulty 1<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
// Difficulty 2<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
// Difficulty 3<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
// Difficulty 4<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
// Difficulty 5<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
],<br />
],<br />
<br />
Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:<br />
<br />
'coop_elo_mode' => array(<br />
'type' => 'points_references',<br />
'references' => array(<br />
// see tgtEloPoints() in tranquility.game.php<br />
array(<br />
'players_nbr' => 2,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1350,<br />
2 => 1425,<br />
3 => 1500,<br />
4 => 1576,<br />
5 => 1651,<br />
6 => 1727,<br />
7 => 1802,<br />
8 => 1878,<br />
9 => 1953,<br />
10 => 2029,<br />
11 => 2104,<br />
12 => 2180<br />
)<br />
),<br />
array(<br />
'players_nbr' => 3,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1400,<br />
2 => 1470,<br />
3 => 1541,<br />
4 => 1612,<br />
5 => 1683,<br />
6 => 1754,<br />
7 => 1825,<br />
8 => 1895,<br />
9 => 1966,<br />
10 => 2018,<br />
11 => 2095,<br />
12 => 2250<br />
)<br />
),<br />
array(<br />
'players_nbr' => 4,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1430,<br />
2 => 1505,<br />
3 => 1580,<br />
4 => 1655,<br />
5 => 1730,<br />
6 => 1805,<br />
7 => 1880,<br />
8 => 1955,<br />
9 => 2030,<br />
10 => 2105,<br />
11 => 2180,<br />
12 => 2330<br />
)<br />
),<br />
array(<br />
'players_nbr' => 5,<br />
// 'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1480,<br />
2 => 1558,<br />
3 => 1636,<br />
4 => 1714,<br />
5 => 1792,<br />
6 => 1870,<br />
7 => 1949,<br />
8 => 2027,<br />
9 => 2105,<br />
10 => 2183,<br />
11 => 2261,<br />
12 => 2340<br />
)<br />
)<br />
)<br />
),</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Game_meta-information:_gameinfos.inc.php&diff=8563
Game meta-information: gameinfos.inc.php
2021-06-22T08:37:01Z
<p>Een: Document coop elo mode</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
== Overview ==<br />
<br />
From this file, you can edit the various meta-information of your game.<br />
<br />
Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.<br />
<br />
Most information provided in this file are self-explainable.<br />
<br />
See sections below for specific cases.<br />
<br />
== Beta ==<br />
<br />
You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.<br />
<br />
<br />
== Time Profiles ==<br />
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.<br />
<br />
<br />
== Number of players ==<br />
<br />
'''players'''<br />
'players' => array( 3, 4, 6 ),<br />
<br />
** during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.<br />
** if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.<br />
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.<br />
<br />
'''suggest_player_number''' / '''not_recommend_player_number'''<br />
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.<br />
<br />
== Losers not ranked between themselves ==<br />
<br />
By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.<br />
<br />
The score in this case should be 1 for the winner and 0 for the losers.<br />
<br />
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true <br />
// The game end result will display "Winner" for the 1st player and "Loser" for all other players<br />
'losers_not_ranked' => false,<br />
<br />
== Disable player rotation in case of rematch ==<br />
<br />
By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.<br />
<br />
// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same<br />
// If you want to disable this, set this to false<br />
'disable_player_order_swap_on_rematch' => false,<br />
<br />
== Custom "buy this game" button ==<br />
<br />
By default, the "buy this game" button is a link to an Amazon search with the name of the game.<br />
<br />
You can replace it by a different URL / game button label with :<br />
<br />
'custom_buy_button' => array(<br />
'url' => 'http://yoururl.com',<br />
'label' => 'Name of the website'<br />
),<br />
<br />
Note : button label will be "Buy on <Name of the website>"<br />
<br />
== Tags ==<br />
<br />
Any number of '''Tags''' can be attribute to your game. Tags are useful to place your game in the correct place and to give a good quick overview of what the game is about to players.<br />
<br />
Main game category (you MUST specify one tag AND ONLY ONE from this category):<br />
* 1: Abstract game<br />
* 2: Casual games<br />
* 3: For regular players<br />
* 4: For core gamers<br />
<br />
Other tags (you can specify any numbers of tags):<br />
* 10: Short game (<10 minutes)<br />
* 11: Medium length game (10 minutes to 30 minutes)<br />
* 12: Long game (>30mn)<br />
* 20: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).<br />
* 22: Prototype (This game has not been published yet)<br />
* 23: Classic (This game is a classic from Public Domain)<br />
* 30: 2 players (2p game / best with 2 players)<br />
* 100: Fantasy theme<br />
* 101: Science Fiction them<br />
* 102: Historical theme<br />
* 103: Adventure<br />
* 104: Exploration<br />
* 105: Conquest<br />
* 106: Building<br />
* 200: Card game (Cards plays a central role in this game)<br />
* 201: Dice<br />
* 202: Solo game<br />
* 203: Worker placement<br />
* 204: Hand management<br />
* 205: Bluff<br />
* 206: Tile placement<br />
* 207: Combinations<br />
* 208: Majority<br />
* 209: Race<br />
* 210: Collection<br />
* 211: Cooperative game<br />
<br />
== Game Presentation ==<br />
<br />
Short game presentation text that will appear on the game description page, structured as an array of paragraphs.<br />
<br />
Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)<br />
<br />
Example:<br />
'presentation' => array(<br />
totranslate("This wonderful game is about geometric shapes!"),<br />
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),<br />
...<br />
),<br />
<br />
== Tie breaker description ==<br />
Describe tie breaker score calculation (player_score_aux in player table).<br />
<br />
Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.<br />
<br />
Example:<br />
'tie_breaker_description' => totranslate('Number of remaining cards in hand"),<br />
<br />
== Language dependency ==<br />
<br />
If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]<br />
<br />
== Coop Elo Mode ==<br />
<br />
For cooperative games, by default players will earn as many Elo points as the score. <br />
<br />
For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill, you have to set up a reference scale for Elo points.<br />
<br />
For this, you have to set up the coop_elo_mode parameter. <br />
<br />
Here is an example using options and win/loss (score 1/0):<br />
<br />
'coop_elo_mode' => [<br />
'type' => 'points_references',<br />
'references' => [<br />
// Difficulty 1<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],<br />
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],<br />
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],<br />
// Difficulty 2<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],<br />
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
// Difficulty 3<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],<br />
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],<br />
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],<br />
// Difficulty 4<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],<br />
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],<br />
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],<br />
// Difficulty 5<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],<br />
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],<br />
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],<br />
],<br />
],<br />
<br />
Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:<br />
<br />
'coop_elo_mode' => array(<br />
'type' => 'points_references',<br />
'references' => array(<br />
// see tgtEloPoints() in tranquility.game.php<br />
array(<br />
'players_nbr' => 2,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1350,<br />
2 => 1425,<br />
3 => 1500,<br />
4 => 1576,<br />
5 => 1651,<br />
6 => 1727,<br />
7 => 1802,<br />
8 => 1878,<br />
9 => 1953,<br />
10 => 2029,<br />
11 => 2104,<br />
12 => 2180<br />
)<br />
),<br />
array(<br />
'players_nbr' => 3,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1400,<br />
2 => 1470,<br />
3 => 1541,<br />
4 => 1612,<br />
5 => 1683,<br />
6 => 1754,<br />
7 => 1825,<br />
8 => 1895,<br />
9 => 1966,<br />
10 => 2018,<br />
11 => 2095,<br />
12 => 2250<br />
)<br />
),<br />
array(<br />
'players_nbr' => 4,<br />
//'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1430,<br />
2 => 1505,<br />
3 => 1580,<br />
4 => 1655,<br />
5 => 1730,<br />
6 => 1805,<br />
7 => 1880,<br />
8 => 1955,<br />
9 => 2030,<br />
10 => 2105,<br />
11 => 2180,<br />
12 => 2330<br />
)<br />
),<br />
array(<br />
'players_nbr' => 5,<br />
// 'options' => array( ),<br />
'elo' => array(<br />
0 => 1000,<br />
1 => 1480,<br />
2 => 1558,<br />
3 => 1636,<br />
4 => 1714,<br />
5 => 1792,<br />
6 => 1870,<br />
7 => 1949,<br />
8 => 2027,<br />
9 => 2105,<br />
10 => 2183,<br />
11 => 2261,<br />
12 => 2340<br />
)<br />
)<br />
)<br />
),</div>
Een
http://en.doc.boardgamearena.com/index.php?title=Translations&diff=8437
Translations
2021-06-03T16:06:55Z
<p>Een: /* How to not make translators crazy ;) */</p>
<hr />
<div>{{Studio_Framework_Navigation}}<br />
<br />
<br />
Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.<br />
<br />
== Localization Overview ==<br />
<br />
Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.<br />
<br />
It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.<br />
<br />
For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.<br />
<br />
<br />
== How will my strings be translated? ==<br />
<br />
When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.<br />
<br />
Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".<br />
<br />
<br />
== What do I have to do from a programming standpoint? ==<br />
<br />
Not as much as you think. Read on for full details, but the golden rules are:<br />
<br />
<br />
<br />
# Make sure that any string on the server side that needs to be translated is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.<br />
# On the client side, just display your text, but wrap it in _().<br />
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.<br />
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.<br />
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.<br />
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.<br />
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated. If your string is never used in the game itself (and only in the options screen) then you may consider defining it with totranslate() instead of clienttranslate(). Both functions will request that your string be translated, but totranslate() won't make your string available to the client during the game itself (which isn't required if it's only required through the options screen).<br />
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client, and need to ensure that it is wrapped in a clienttranslate() on the server (if you want it also to be usable during the game itself) or totranslate() (if it is never used outside of the statistics screen).<br />
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.<br />
<br />
== What strings should be translated? ==<br />
<br />
Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.<br />
<br />
This does NOT include error messages that are not supposed to happen (unexpected errors).<br />
<br />
<br />
== What rules should I follow for the original English strings? ==<br />
<br />
For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'<br />
<br />
* As a general rule:<br />
** If a sentence is displayed isolated in the interface => no final period<br />
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.<br />
<br />
* In detail:<br />
** No final period:<br />
*** button labels<br />
*** section titles<br />
*** menu elements<br />
*** links triggering an isolated action<br />
*** anything that is not a full sentence<br />
*** current actions in the status bar<br />
** Final period:<br />
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences<br />
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:<br />
*** isolated tooltips / small sentences<br />
*** game logs (no period is usually preferable)<br />
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)<br />
<br />
Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.<br />
<br />
<br />
== Focus on translating notifications ==<br />
<br />
Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.<br />
<br />
However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.<br />
<br />
== How to not make translators crazy ;) ==<br />
<br />
* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.<br />
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre><br />
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.<br />
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).<br />
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:<br />
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre><br />
Write instead:<br />
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre><br />
(or the equivalent "dojo.string.substitute" in Javascript)<br />
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.<br />
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.<br />
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".<br />
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".<br />
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.<br />
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.<br />
<br />
== WARNING: Make sure your strings will be translated! ==<br />
<br />
For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)<br />
<br />
If your original string is not completely contained inside one of these markers, it won't be translated.<br />
<br />
<pre><br />
// Examples: the following strings will be translated:<br />
var mystring_translated = _("my string"); // JS<br />
$mystring_translated = self::_("my string"); // PHP<br />
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP<br />
<br />
// Examples: the following strings WILL NOT be translated:<br />
$my_string = "my string";<br />
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation<br />
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto<br />
</pre><br />
<br />
== On client side (Javascript) ==<br />
<br />
On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.<br />
<br />
Examples:<br />
<pre><br />
// Get a string in player's language:<br />
var translated = _("original english string");<br />
<br />
// Get a string in player's language with parameter:<br />
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {<br />
p: 2,<br />
d: 4<br />
} );<br />
</pre><br />
<br />
'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.<br />
<br />
'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method<br />
<br />
== On server side (PHP) ==<br />
<br />
On PHP side, you can use 3 different functions to specify that a string must be translated.<br />
<br />
'''clienttranslate( "string to translate" ):'''<br />
<br />
This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.<br />
<br />
In general, you use clienttranslate:<br />
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".<br />
<br />
<pre><br />
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),<br />
</pre><br />
<br />
* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.<br />
<br />
<pre><br />
$this->card_types = array(<br />
<br />
1 => array(<br />
'name' => clienttranslate("Amulet of Air"), // Thus, we can use "_( card_name )" on Javascript side.<br />
</pre><br />
<br />
* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.<br />
<br />
<pre><br />
// A game log string with no argument:<br />
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate("Everyone draw cards from their library"), array() );<br />
</pre><br />
<br />
As a consequence there is no point passing variables to this function. E.g.:<br />
<br />
<pre><br />
notif="foo";<br />
self::notifyAllPlayers( 'log', clienttranslate(notif)); // BAD<br />
<br />
notif=clienttranslate("foo");<br />
self::notifyAllPlayers( 'log', notif); // GOOD<br />
</pre><br />
<br />
Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:<br />
<br />
<pre><br />
// In the following example, we translate the game log itself, but also the "card_name" argument:<br />
<br />
self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(<br />
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated<br />
'player_id' => $player_id,<br />
'player_name' => self::getActivePlayerName(),<br />
'points' => $points,<br />
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.<br />
) ); <br />
</pre><br />
<br />
To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:<br />
<br />
<pre><br />
$this->card_types = array(<br />
...<br />
8 => array(<br />
'name' => clienttranslate("Amulet of Fire"),<br />
...<br />
</pre><br />
<br />
Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.<br />
<br />
'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).<br />
<br />
'''self::_( "my string to translate" ):'''<br />
<br />
This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).<br />
<br />
Most of the time, you don't need to translate strings on server side, except on the following 3 situations:<br />
* When throwing an exception because the player did a forbidden move.<br />
<br />
<pre><br />
// This will display a translatable red message to the player that just did some wrong action:<br />
throw new BgaUserException( self::_('You must choose 3 cards') );<br />
<br />
// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.<br />
</pre><br />
<br />
* In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.<br />
<br />
<pre><br />
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");<br />
</pre><br />
<br />
'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.<br />
<br />
* Eventually, in your material.inc.php, if for example you need to use some string elements in your exceptions.<br />
<br />
<pre><br />
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:<br />
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );<br />
</pre><br />
<br />
* Eventually, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.<br />
<br />
'''totranslate( "my string to translate" ):'''<br />
<br />
This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.<br />
<br />
You should not use this function, except on the following cases:<br />
* Statistics name in stats.inc.php<br />
* Option names and option values name in gameoptions.inc.php<br />
<br />
<br />
== Top Secret Undocumented Feature ==<br />
<br />
If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.<br />
<br />
== On server side - advanced (PHP) ==<br />
<br />
If you want to use translation system in your custom static modules, you will first need to expose the _() function :<br />
<pre><br />
class mygame extends Table {<br />
// Exposing protected method translation<br />
public static function totranslate($text) {<br />
return self::_($text);<br />
}<br />
}<br />
</pre><br />
<br />
Then you'll be able to use this directly in other modules by doing<br />
<pre><br />
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));<br />
</pre><br />
<br />
Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :<br />
<pre><br />
$msg = "Translated error from my awesome module file";<br />
throw new BgaUserException(mygame::totranslate($msg));<br />
</pre></div>
Een