webDip dev coordination forum / public access todo list
It is currently Fri May 25, 2018 4:46 pm

All times are UTC

Post new topic Reply to topic  [ 1 post ] 
Author Message
 Post subject: VariantData API
PostPosted: Sat Jul 06, 2013 5:18 pm 
Site Admin

Joined: Sat Jun 28, 2008 6:24 am
Posts: 892
From webDip 1.35 on there's a new class designed to assist variants called VariantData, which is in variants/variantData.php

It's designed to be a generic data store for variant related information which doesn't fit into existing tables, to help avoid the need for variants to try and use existing data storage space in unintended ways which may cause issues down the line. I just wanted a way to make fair country balancing apply to all variants, instead of just classic, but making a data store for that was 90% of the work towards making a generic variant store for any purpose.

It's simply an interface to a new table, wD_VariantData, which contains val_int and val_float columns to store integers or floats (or both), and the rest are lookup fields which default to 0:
  • variantID: The variant ID associated with this data
  • gameID: The game ID associated with this data (0 means it's not associated with a game ID)
  • systemToken: A random number from 0 to ~2^31, which can distinguish the function you are using this for. This should be a randomly generated number so that it is unlikely to conflict with any other system. To generate one go to excel and do e.g. =RANDBETWEEN(0,POWER(2,31))
  • typeID: The type of data being stored, or 0 if not distinguishing on type.
  • userID: The user ID associated with the data, or 0 if not distinguishing based on userID
  • offset: An additional number which can denote another dimension, e.g. for additional information which needs to be tracked on a turn by turn basis this could contain the turn, or for additional unit information this could contain the unit ID
The lookup fields are all unsigned integers, val_int is a signed integer and val_float is a float.

So for example the only current use for this system is country balancing, and it is used for all variantIDs, it has a systemToken = 948379409, the gameID is 0 because it's not per game, the typeID is 0 because there is only one type of data stored (the chance of being a certain country), the userID links to the user whos country chances are being stored, and the offset contains the country ID for that particular variant.

So e.g. this image shows my country chances for variantID = 1 (Classic):
Untitled picture.png
Untitled picture.png [ 12.59 KiB | Viewed 2590 times ]

The API is pretty straightforward:
protected function setUserCountryChances($countryChances)
   global $Game;
   $vd = new VariantData($Game->variantID); // Create a new VD reference object, with the variant ID
   // All other parameters besides the variantID are optional, and will default to 0, so you could store a variant wide variable
   $vd->systemToken = 948379409; // The unique system token, to ensure nothing else interferes with this data
   foreach($countryChances as $userID=>$chances)
      $vd->userID = $userID; // Set the userID
      foreach($chances as $countryID=>$chance)
         $vd->setFloat($chance, $countryID); // Now store the $chance data, at the $countryID offset
         // (Note that the second parameter, $countryID, for the offset, is also optional and defaults to 0

And fetching back the data, which is just the same thing in reverse:
   protected function getUserCountryChances($userIDs)
      global $Game;
      $vd = new VariantData($Game->variantID);
      $vd->systemToken = 948379409;
      $countryChances = array();
      $countryCount = count($Game->Variant->countries);
      foreach($userIDs as $userID)
         $countryChances[$userID] = array();
         $vd->userID = $userID;
            $countryChances[$userID][$countryID] = $vd->getFloat($countryID, 1.0/$countryCount); // The first $countryID offset field is optional, as is the second field, which contains the default value to return if no value was found (in this case the default is 1.0/$countryCount i.e. an equal chance of being this country)
      return $countryChances;

Note that each call to getFloat/getInt/setFloat/setInt will run a SQL query, so if you will be storing / retrieving large amounts of data using this interface you should query wD_VariantData directly. Also the table does use a lot of space for each variant (for each e.g. 4 byte integer/float stored there are about 21 bytes of lookup data, plus some extra for indexing, so this isn't a very space efficient way to store data.
e.g. if you wanted to store new data for every territory, for every user, for every game, for every turn, you might still need to implement a custom solution.

However I expect that most of the time there's a more modest requirement for some extra storage space for variant specific data, which otherwise wouldn't quite fit, and hopefully this new API will help.

Display posts from previous:  Sort by  
Post new topic Reply to topic  [ 1 post ] 

All times are UTC

Who is online

Users browsing this forum: No registered users and 2 guests

You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot post attachments in this forum

Search for:
Jump to:  
Powered by phpBB® Forum Software © phpBB Group