[futureal]

vbProArcade v1.0 Beta 2 Documentation

/////////////////////////////////
// vbProArcade v1.0 Beta 2 //
// The Extended Documentation! //
// v1b2.030105 //
// by futureal //
////////////////////////////////


Introduction
------------

vbProArcade is a PHP script designed to provide an interface between the vBulletin Instant Community and Macromedia Flash-produced games. vbProArcade is made freely available via vbulletin.org to licensed vBulletin owners ONLY, and should not be redistributed or modified in any other way without the express written consent of the author.


Installation
------------

There are multiple steps required to making vbProArcade work with your vBulletin installation. They are:

- uploading the vbProArcade files
- uploading the arcade game files
- modifying your SQL database with the vbProArcade tables and settings
- modifying (hacking) the vBulletin PHP code
- installing (and possibly editing) the vbProArcade templates

The majority of these instructions are contained in a separate file (vbproarcade-install.txt). This file is meant as more of an explanaton of vbProArcade's features and how to use them effectively, as well as a revision log and other information from the author.

Note that this is an EXTENSIVE hack and will require some time and effort to get to work correctly. As a word of warning, there have been sites where vbProArcade would not work, for whatever reason. While I hope that your site is not one of them, I cannot guarantee that this will work everywhere. Still, I will make every effort to continually update the code to get it working in as many environments as possible.


Games and How to Modify Them
----------------------------

vbProArcade interfaces with Macromedia Flash games that have been specially modified to work with it. To modify a Flash game to work with vbProArcade, you will need access to the game's source code (usually a .FLA file). Just having the pre-compiled .SWF file will NOT work.

This is the block of code that needs to be added to a Flash Game to make it compatible with vbProArcade:

-----

// set up vars to return
vpaver = "100B2";
scorevariable = score;
action = "gameover";
game = gamename;
score_loc = location + "/proarcade.php";

// this needs to match the Admin CP value
// and should be between 0 and 31
hashoffset = 5;

// do security shuffle to return newhash
subhash1 = gamehash.substr(0,hashoffset);
subhash2 = gamehash.substr(hashoffset);
newhash = subhash2.concat(subhash1);

// redirect back to vbProArcade
getURL (score_loc, "_self", "POST");

-----

There are a couple of things to pay attention to here. First, "scorevariable" MUST match whatever you set the score variable to be in the Admin Control Panel in vBulletin. In this case, "scorevariable" would correspond to "$scorevariable" in the CP. Second, "hashoffset" MUST match the hash offset defined for the game in the Admin Control Panel in vBulletin. This value needs to be between 0 and 31, since the MD5 hash is a 32-character string. If these values do not match, you game will always return a Security Violation after exiting.

When you add a game to the arcade, you must give the arcade the HTML code associated with the Flash file, which should look something like this (this is the default code for Tetris):

-----

<object classid="clsid27CDB6E-AE6D-11cf-96B8-444553540000" codebase="http://download.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=6,0,0,0" width="550" height="380">
<param name="movie" value="$vpa_gameurl?location=$vpa_bburl&gamename=$ game&gamehash=$gamehash&s=$session[sessionhash]&username=$username&highscore=$highscore&bbtitle=$ bbtitle">
<param name="quality" value="high">
<param name=bgcolor value="#576375">
<embed src="$vpa_gameurl" pluginspage="http://www.macromedia.com/go/getflashplayer" type="application/x-shockwave-flash" width="550" height="380">
</embed></object>

-----

Note the variables that can be used in this process:

$vpa_gameurl - The Path to the Arcade Games on your Server
$vpa_bburl - The Path to your Forum on your Server
$game - Game's Text Identifier
$gamehash - Game Security Hash (will not return scores correctly without this)
$session[sessionhash] - vBulletin Session Data (should pass this for non-cookied users)
$username - User who is Playing
$highscore - Current High Score for this Game
$bbtitle - Title of your Forums

Not all games will support all of these, but if you are creating (or modifying) a game to work with vbProArcade, you might make use of some of these variables to "spice it up" a bit.

The rest of the code should remain the same from game to game and does not need to be specially modified. If you are wondering about the security features, see the section on security further down in this documentation.

Also note that before modifying any games you find, please make sure that you have the author's permission, *especially* if you intend to redistribute the file after it has been modified.


Templates
---------

vbProArcade is a completely templated-out hack, meaning that it is remarkably easy to change the look of your Arcade without having to edit the PHP code itself. The downside of this is that there are a bunch of templates to install and manage. Here is a list of the templates that come with vbProArcade, and where each one is used:

- vbproarcade_arcade - Main Arcade Page
- vbproarcade_arcadebit - Main Arcade Page - "Bit" to Display Each Game on the Main Page
- vbproarcade_arcade_gamedesc_icon - Main Arcade Page - Game Description (with Game Icon)
- vbproarcade_arcade_gamedesc_noicon - Main Arcade Page - Game Description (without Game Icon)
- vbproarcade_arcade_gamename_icon - Main Arcade Page - Game Name (with Game Icon)
- vbproarcade_arcade_gamename_noicon - Main Arcade Page - Game Name (without Game Icon)
- vbproarcade_arcade_gamescorecell - Main Arcade Page - Mini-Scoreboard Game Score Cell
- vbproarcade_arcade_gamescorecellbit - Main Arcade Page - Mini-Scoreboard Game Score Cell "Bit"
- vbproarcade_arcade_userscore_guest - Main Arcade Page - Score Message for a Guest
- vbproarcade_arcade_userscore_king - Main Arcade Page - Score Message for the Champion
- vbproarcade_arcade_userscore_notking - Main Arcade Page - Score Message for Normal Players
- vbproarcade_arcade_userscore_notplayed - Main Arcade Page - Score Message for Users who Have Not Played
- vbproarcade_errormessage - Arcade Message - Template
- vbproarcade_gameover - Game Over Template
- vbproarcade_playgame - Game Screen Template
- vbproarcade_scorebit - Game Scoreboard - Score "Bit"
- vbproarcade_scoreboard - Game Scoreboard
- vbproarcade_scoreboard_gamelinkbit - Game Scoreboard - Game Links (at bottom of pages) "Bit"
- vbproarcade_scoreboard_gamelinks - Game Scoreboard - Game Links (at bottom of pages)
- vbproarcade_scoreboard_userstats - Game Scoreboard - User Statistics
- vbproarcade_topscoreboard - Game Top Scoreboard
- vbproarcade_userdetail - User Detail Main Page
- vbproarcade_userdetail_gamecell - User Detail Game Cell

As it stands, there are 23 templates in use in vbProArcade Beta 2. As the code is optimized further, this number *should* go down; however, as new features are added, new templates may be necessary. I know that maintaining this many is a heavy workload for an administrator, but it seems to be the best way to allow for customization, so I am sticking with it (for now).


Arcade Tables
-------------

There are five tables that make up vbProArcade:

arcadeconfig - Stores the Arcade Configuration
arcadegames - Stores the Arcade Games' Configuration
arcadescoregroups - Defines Groups of Scores (not fully implemented)
arcadescores - Stores the Top Scores for each Game
arcadetopscores - Stores the Scores for each Game

To see the individual layouts of each table, you can execute a "desc tablename;" query from the MySQL command line.



Score Table Structure and Security
----------------------------------

One of the major problems with Beta 1 of vbProArcade was a lack of security. This has been addressed (somewhat) in Beta 2 by a rather large modification of the way scores are stored and handled.

First of all, the arcadescores table (which stores the regular scores themselves) now looks like this:

int(10) unsigned scoreid unique score identifier
int(10) unsigned scoregroup group the score belongs to
varchar(50) game game's textual identifier

int(11) begintime timestamp for game start
int(11) endtime timestamp for game end

varchar(50) gamehash md5 encrypted identifier
tinyint(1) valid see if score is valid (0 invalid, 1 valid)

int(10) unsigned userid userid of player
varchar(50) username username of player

int(11) score user's score
varchar(70) comment user's comment

When a user chooses to play a game, the database creates an invalid score entry containing that user's name and ID, the current UNIX timestamp, and an MD5 hash of some encrypted value. The hash, along with any other interesting information, is passed into the Flash game.

When a Flash game exits, it redirects the user to the "Game Over" screen, and passes along the hash with the other data. The Arcade then queries the database, looking for the most recent entry for that particular user, checking to see if the game matches, the hash matches, and that the time is greater than the recorded time. If everything checks out, the score is recorded as a valid score, and the user is prompted to enter a comment.

When the user clicks "Submit" on the comment screen, a new, random MD5 hash is generated and stored alongside the score in the database, which is then passed along with the form data, and re-checked against the database. This will prevent users from "brute-forcing" the Arcade to record a new comment for a given score, as was possible in Beta 1.

On top of the MD5 security, the server is recording the entry and exit timestamps of each game, which cannot be altered by user input at all. An astute administrator should be able to determine whether or not a game was completed in a reasonable amount of time or not, thus giving him or her yet another method of weeding out fake scores, should they arise.

Another new feature of the score table is "Score Grouping." Although this is not yet implemented, it will allow the Administrator to define sets of scores for a given time period. This could be used for daily, weekly, or monthly scoreboards, for example, or perhaps for a tournament or some other form of grouping.

Obviously, this system is not foolproof, since a cheater could (for example) still wait the requisite amount of time for a game and use a hex-editor to change memory locations. Still, this is a good start, and should prevent all of the "address bar cheating" that we saw with Beta 1.


History
-------

Release History (so far):

8/31/02 - vbProArcade Beta 1 Released
9/13/02 - vbProArcade Beta 1.03 Released
1/05/03 - vbProArcade Beta 2 Released


Revision History:

Beta 2:

- Fixed Top Score Board bug
- Fixed Champions System to Correctly Integrate with postbit
- Added Icons to Champions System
- Added Template Support to Champions System
- Added Usergroup Access Control to Admin CP
- Added Mini Scoreboards to Main Arcade Page
- Changed Score Tables to use UNIX timestamps
- Changed Score Tables for additional security
- Added Score Grouping for future expansion
- Added Customizable Icons for User Detail Pages
- Added User Scoreboards for Individual Games
- Added User Statistics Pages
- Removed/Cleaned Up Some Old Templates
- Added Simple Score Editor Framework (for future expansion)
- Added Ability to Reset Scores

Beta 1.03:

- Fixed PHP Safe Mode bug
- Fixed Top Score Board Division by Zero error
- Fixed Undefined Function Call in online.php
- Fixed URL Redirection Problems

Beta 1:

- Initial Release
- Basic Arcade/Scoreboard Functionality


Conclusion
----------

Although I certainly *hope* that vbProArcade will work flawlessly on your forums, I am sure that as time goes on people will run across small bugs and problems that need to be corrected. I will make every effort to make myself available for support, though I urge you to exercise patience, as I have a very, very busy schedule.

I plan to continue to work on vbProArcade for the foreseeable future, including porting it over to vBulletin v3.0 when it is released to the public.

Should anybody feel ambitious, Paypal donations are always graciously accepted, and any money received in this manner will go directly towards the upkeep and maintenence of my two websites. To donate, go to www.paypal.com and use my futureal@rctech.net email address. Note that donations are not at all required for support purposes!

Any support questions should be directed to the vbProArcade thread on www.vbulletin.org, though my email addresses are available should they become necessary.

Thanks for using vbProArcade!


- Shane (futureal)

futureal@rctech.net
futureal@shadowsofnamek.com