This is a documentation for Board Game Arena: play board games online !

Post-release phase: Difference between revisions

From Board Game Arena
Jump to navigation Jump to search
(Add new case that breaks games in progress)
(23 intermediate revisions by 6 users not shown)
Line 1: Line 1:
{{Studio_Framework_Navigation}}


Your game is now on BGA: congrats!
Your game is now on BGA: congrats!
Line 8: Line 9:
== Bugs reporting ==
== Bugs reporting ==


Bugs are reported in the [http://forum.boardgamearena.com/viewforum.php?f=4 BGA bugs forum].
Bugs are reported on the [https://boardgamearena.com/bugs BGA bugs page].


During days after your game has been published and from time to time, please have a look at it to check if everything is fine.
During days after your game has been published and from time to time, please have a look at it to check if everything is fine.
Line 14: Line 15:
== How to submit changes? ==
== How to submit changes? ==


To submit your changes, you just have to commit your work from BGA Studio backoffice, as you did during the development phase.
There is 3 (short) steps to make your changes visible on BGA (from your Control Panel):


'''Warning''': as soon as you commited your changes, we assume that your code is ready to deploy '''anytime''' on BGA. Consequently, please do not commit a development in progress.
* Commit your changes.
* Build a new version (don't forget to do a successful commit BEFORE your build).
* Deploy your new version in production.


== BGA packages: when my updates will be visible by players? ==
BGA website is updated with "packages". When needed, we build a new package with all games and release a new version of BGA with this package.
It means that your updates won't be visible by players until a new package is build and released on the website.
Usually, there is less than 2 weeks between 2 packages, so it's quick. BUT, if you detect some major bug in your game, please warn us immediately so we can decide what to do. Usually, we do the following:
* We can do a "hotfix": you send us a very little change and we fix the website immediately. This is only possible if you change only the PHP side. The good news is that most blocking bugs are on PHP side - the client side bugs are most of the time solved by a page refresh. Of course, we don't hotfix minor bugs.
* We can build another package. Of course, it's better to fix several bugs in each package, in order we don't have to build another package right after the first one :)
* If the situation is critical, we can suspend the game from BGA waiting for the update.
Of course, we particularly care of your game during the days after your game is available on BGA. During this period of time, there's no problem to build package and to hotfix just for your game, and this is done in close collaboration with you. You just have to inform us when you're ready to publish a new version.
Note: don't forget that in any case, you need to commit your changes to made them available for the next package. Modifications that are not commited are not included in the packages.


== What can be modified after release? ==
== What can be modified after release? ==
Line 44: Line 33:
* Changes in the database schema of the game (dbmodel.sql).
* Changes in the database schema of the game (dbmodel.sql).
* New global variable or game option accessed during the game (if it's only used during setup, it should be safe).
* New global variable or game option accessed during the game (if it's only used during setup, it should be safe).
* New statistic (it won't be initialized properly, so it's going to crash the game).
* Change ID of existing game states (adding new game states is fine).
* Change ID of existing game states (adding new game states is fine).
* Changing flow of game states (for example, if you change 1 -> 2 -> 3 -> 4 to 1 -> 3 -> 2 -> 4, players at state 2 will skip state 3)


Of course, as a rule of thumb, you should avoid to introduce changes that break a game in progress. Sometimes however, you do not have any other choice. In this case:
Of course, as a rule of thumb, you should avoid to introduce changes that break a game in progress. Sometimes however, you do not have any other choice. In this case:
* Try to group all your updates in one BGA package, thus we won't have to block your game several times.
* Try to group all your updates in one version, thus we won't have to block your game several times.
* Tell us explicitly that you introduce some update that can break games in progress, '''as soon as you commit your update'''.
* Tell us explicitly that you introduce some update that can break games in progress so we can block the game during a short time.
* Thus, during the package delivery, we will block the game and let game in progress end before publishing the new version.
 
Note: in the near future, we will introduce the possibility for you to block/unblock a game directly from your Control Panel in order to perform all the process by yourself.
 
=== Updating game options ===
 
* If you add options, you should let us know which value should be used for the arena mode, so that we can update the arena configuration.
* If you remove an option or change a version ID, it will break the arena configuration and prevent creating new arena games, so you should let us know so that we can synchronize to update the configuration at the same time as you deploy the new version.
* Do not change option IDs once the game is in production, it will break ongoing games and audience option statistics.
 
=== Updating Statistics ===
 
You should be careful when updating a statistics:
 
* If you want to add a new statistic, please be aware that for ongoing games this statistic won't always be correct since it has not been counted from the start of that game.
* If you want to update a statistic, please update it and do not remove/create another one. Otherwise, the statistic won't keep the same ID and players will lose all the historical statistics data.
* If your game is published on BGA, please don't remove any statistics (historical data will be lost).
 
=== Updating the database schema ===
 
If you want to update the database schema of the game (dbmodel.sql) and your game is already open to everyone on BGA (from BETA onwards), you should inform us before releasing the new version (see "[[#Changes that breaks the games in progress|changes that breaks the games in progress]]").
 
Any modification in dbmodel.sql should also appear in your nameofyourgame.game.php, in a function
 
  function upgradeTableDb( $from_version ){
 
  if( $from_version <= YYMMDDHHMM ){ // where your CURRENT version in production has number YYMMDD-HHMM
 
            // You DB schema update request.
            // Note: all tables names should be prefixed by "DBPREFIX_" to be compatible with the applyDbUpgradeToAllDB method you should use below
            $sql = "CREATE TABLE DBPREFIX_xxxxxxx ....";
 
            // The method below is applying your DB schema update request to all tables, including the BGA framework utility tables like "zz_replayXXXX" or "zz_savepointXXXX".
            // You should really use this request, in conjunction with "DBPREFIX_" in your $sql, so ALL tables are updated. All utility tables MUST have the same schema than the main table, otherwise the game may be blocked.
            self::applyDbUpgradeToAllDB( $sql );
 
  }}
 
Note1: of course you need to change your dbmodel.sql accordingly, so that new games get your updated scheme.
 
Note2: this is always risky to modify the DB scheme, so:
* if your game is already open to everyone on BGA (from BETA onwards), it may be worth contacting us before, so we can stop the realtime games during the update (this way, only turn based games are concerned by the DB live upgrade).
* if you can avoid it... try to avoid it :)
 
Note3: testing on the studio is possible by following the following procedure:
* make sure the current state of your project is correctly committed
* revert to the revision currently in production using the version control tools ("Display commit log" -> find the revision matching the current version in production, then "Overwrite working copy with this revision" to get back the matching code)
* launch a game with this code
* revert to your code latest version using the version control tools (use "Overwrite working copy with this revision" with "head" for the revision)
* access the game database
* in the "global" table, find the row with id 300. Its value is 999999999 by default on the studio. Change it to the current production version number
* hit refresh to reload your game page. Your upgradeTableDb() function will be run and the global value will be updated again to the studio value
* check the database to see if your changes have been correctly applied.
 
=== Updating string to be translated  ===
 
When you update a string that has been marked to be translatable, please keep in mind that all current translations done by the BGA community will be lost.
 
Consequently, when you are about to modify a string to be translated (after release), please ask you the following questions:
* Is it just an English misspelling? In this case, it is better to fix the English translation of the string than the original string to be translated.
* Has the meaning of the string changed? If yes, you HAVE to change the original string in order to invalidate all translations that has been done already.
* Is there a similar string already used elsewhere in my game? In this case, you'd better use it again to enjoy immediately all translations already available.
 
===Tell the community about your changes :)===
 
The player's community is always happy to know that someone is taking care of their preferred game :)
 
If your are the developer of game XXXX, you are also the administrator of player's group "XXXX's players", and you can publish some news in this group newsfeed.
 
When you fix a bug or add something, do not hesitate to tell the players about this in this group: you'll get the "thank you" you deserved :)
 
See for example Werewolves group:
https://boardgamearena.com/group?id=2465913
 


===Major changes===
===Major changes===
Line 60: Line 121:
... please tell us. In this case, we can:
... please tell us. In this case, we can:
* Make your game back from "gold" to "public beta", to incite player to report bugs.
* Make your game back from "gold" to "public beta", to incite player to report bugs.
* Discuss with you about the release date of the next BGA package.
* Pay attention to your game when publishing the package.
* And eventually, publish a news about it :)
* And eventually, publish a news about it :)

Revision as of 01:42, 2 December 2020


Game File Reference



Useful Components

Official

  • Deck: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).
  • Draggable: a JS component to manage drag'n'drop actions.
  • Counter: a JS component to manage a counter that can increase/decrease (ex: player's score).
  • ExpandableSection: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
  • Scrollmap: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
  • Stock: a JS component to manage and display a set of game elements displayed at a position.
  • 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).

Undocumented component (if somebody knows please help with docs)

  • Wrapper: a JS component to wrap a <div> element around its child, even if these elements are absolute positioned.

Unofficial



Game Development Process



Guides for Common Topics



Miscellaneous Resources

Your game is now on BGA: congrats!

But what happened when there are some bugs to fix or when you want to optimize something?

Don't be afraid: you're still allowed to modify your game. You just have to pay attention to the points below.

Bugs reporting

Bugs are reported on the BGA bugs page.

During days after your game has been published and from time to time, please have a look at it to check if everything is fine.

How to submit changes?

There is 3 (short) steps to make your changes visible on BGA (from your Control Panel):

  • Commit your changes.
  • Build a new version (don't forget to do a successful commit BEFORE your build).
  • Deploy your new version in production.


What can be modified after release?

Everything can be modified. BUT, some items requires a special attention, and you must inform us in some cases:

Changes that breaks the games in progress

Some changes will break the games in progress at the moment the release/the hotfix will be performed. Each time you make a change, you should ask you the question "it is safe to make this change in a game in progress", and if the answer is "no" you have to inform us.

Example of changes that break the games in progress:

  • Changes in the database schema of the game (dbmodel.sql).
  • New global variable or game option accessed during the game (if it's only used during setup, it should be safe).
  • Change ID of existing game states (adding new game states is fine).
  • Changing flow of game states (for example, if you change 1 -> 2 -> 3 -> 4 to 1 -> 3 -> 2 -> 4, players at state 2 will skip state 3)

Of course, as a rule of thumb, you should avoid to introduce changes that break a game in progress. Sometimes however, you do not have any other choice. In this case:

  • Try to group all your updates in one version, thus we won't have to block your game several times.
  • Tell us explicitly that you introduce some update that can break games in progress so we can block the game during a short time.

Note: in the near future, we will introduce the possibility for you to block/unblock a game directly from your Control Panel in order to perform all the process by yourself.

Updating game options

  • If you add options, you should let us know which value should be used for the arena mode, so that we can update the arena configuration.
  • If you remove an option or change a version ID, it will break the arena configuration and prevent creating new arena games, so you should let us know so that we can synchronize to update the configuration at the same time as you deploy the new version.
  • Do not change option IDs once the game is in production, it will break ongoing games and audience option statistics.

Updating Statistics

You should be careful when updating a statistics:

  • If you want to add a new statistic, please be aware that for ongoing games this statistic won't always be correct since it has not been counted from the start of that game.
  • If you want to update a statistic, please update it and do not remove/create another one. Otherwise, the statistic won't keep the same ID and players will lose all the historical statistics data.
  • If your game is published on BGA, please don't remove any statistics (historical data will be lost).

Updating the database schema

If you want to update the database schema of the game (dbmodel.sql) and your game is already open to everyone on BGA (from BETA onwards), you should inform us before releasing the new version (see "changes that breaks the games in progress").

Any modification in dbmodel.sql should also appear in your nameofyourgame.game.php, in a function

 function upgradeTableDb( $from_version ){
 
 if( $from_version <= YYMMDDHHMM ){ // where your CURRENT version in production has number YYMMDD-HHMM
 
           // You DB schema update request.
           // Note: all tables names should be prefixed by "DBPREFIX_" to be compatible with the applyDbUpgradeToAllDB method you should use below
           $sql = "CREATE TABLE DBPREFIX_xxxxxxx ....";
 
           // The method below is applying your DB schema update request to all tables, including the BGA framework utility tables like "zz_replayXXXX" or "zz_savepointXXXX".
           // You should really use this request, in conjunction with "DBPREFIX_" in your $sql, so ALL tables are updated. All utility tables MUST have the same schema than the main table, otherwise the game may be blocked.
           self::applyDbUpgradeToAllDB( $sql );
 
 }}

Note1: of course you need to change your dbmodel.sql accordingly, so that new games get your updated scheme.

Note2: this is always risky to modify the DB scheme, so:

  • if your game is already open to everyone on BGA (from BETA onwards), it may be worth contacting us before, so we can stop the realtime games during the update (this way, only turn based games are concerned by the DB live upgrade).
  • if you can avoid it... try to avoid it :)

Note3: testing on the studio is possible by following the following procedure:

  • make sure the current state of your project is correctly committed
  • revert to the revision currently in production using the version control tools ("Display commit log" -> find the revision matching the current version in production, then "Overwrite working copy with this revision" to get back the matching code)
  • launch a game with this code
  • revert to your code latest version using the version control tools (use "Overwrite working copy with this revision" with "head" for the revision)
  • access the game database
  • in the "global" table, find the row with id 300. Its value is 999999999 by default on the studio. Change it to the current production version number
  • hit refresh to reload your game page. Your upgradeTableDb() function will be run and the global value will be updated again to the studio value
  • check the database to see if your changes have been correctly applied.

Updating string to be translated

When you update a string that has been marked to be translatable, please keep in mind that all current translations done by the BGA community will be lost.

Consequently, when you are about to modify a string to be translated (after release), please ask you the following questions:

  • Is it just an English misspelling? In this case, it is better to fix the English translation of the string than the original string to be translated.
  • Has the meaning of the string changed? If yes, you HAVE to change the original string in order to invalidate all translations that has been done already.
  • Is there a similar string already used elsewhere in my game? In this case, you'd better use it again to enjoy immediately all translations already available.

Tell the community about your changes :)

The player's community is always happy to know that someone is taking care of their preferred game :)

If your are the developer of game XXXX, you are also the administrator of player's group "XXXX's players", and you can publish some news in this group newsfeed.

When you fix a bug or add something, do not hesitate to tell the players about this in this group: you'll get the "thank you" you deserved :)

See for example Werewolves group: https://boardgamearena.com/group?id=2465913


Major changes

If you do some major changes to your game like:

  • Introducing a new expansion.
  • Major code rewriting/refactoring.

... please tell us. In this case, we can:

  • Make your game back from "gold" to "public beta", to incite player to report bugs.
  • And eventually, publish a news about it :)