gistfile1.txt

* Overview 
  + We're providing new Data Persistence API, which lets you store some data 
  between server runs for ROBLOX places 
  + Significant improvement over previous API, including: 
    - Arbitrary global data, not just per-place data 
      * Allows to subscribe to updates made by other instances! 
    - Guaranteed saves - as soon as call returns, data will not be lost 
    - In future, will allow sharing this data between different places 
    - Saves arbitrary lua tables 
    
* Setup 
  + To access it, open place from website (for example, from Start Page->My Projects) 
  + WARNING: call from studio will affect data server sees, 
  so it's higly advised to have a separate test place! 
  
* Accessing data persistence: 
  ds = game:GetService("UniverseService"):GetGlobalDataStore()
  
* API: 
  + All action APIs on DataStore yield(as shown by Async suffix) 
  + All keys are global per-place, not per player 
  + GetAsync(key) - returns value 
  + UpdateAsync(key, function(oldValue) return newValue; end) - to update a key,
  you need to provide function that receives old value and returns new one 
    - This function can be run multiple times in case of conflict, so make sure you use oldValue 
    - To cancel update, return nil 
    - If key doesn't exist, will receive nil 
    - If sucessful, returns value of the key
    - If update is cancelled, returns result of callback function (may return multiple values)
  + IncrementAsync(key, delta=1) - increments value for a particular key, returns incremented value 
  + SetAsync(key,value) - sets value. Very dangerous, since it can overwrite data from another instance. 
  Almost always using UpdateAsync is preferred 
  + OnUpdate(key, function(value) end) - subscribe for key change. Change could come both from this 
  instance or other instances 
    - Returns connection, like event would 
  + value can be number, boolean, string or lua table. ROBLOX types like Instances, Vector3, etc are not allowed 
  
* Example: 
  ds = game:GetService("UniverseService"):GetGlobalDataStore()
  ds:GetAsync("mykey") -- will return null
  ds:Update("mykey", function(oldValue) return oldValue == nil and 4 or nil) -- If key doesn't exist, create it, otherwise cancel update
  ds:IncrementAsync("mykey",3) -- will return 1
  ds:UpdateAsync("mykey", function(oldValue) return oldValue*2; end)
  ds:GetAsync("mykey") -- will return 4
  
  ds:OnUpdate("mykey", function(value) print(value) end)
  ds:SetAsync("mykey", 10) -- will print 10