Repository data storage
- Note: Freefrom storage of text-based data to the repository is only one way to transfer data chunks to the client. Another is to use the node serialization storage, described at Repository Node Serialization.
Both the servers and privileged clients can modify and retrieve the data. However, non-privileged clients (such as those used by non-developers) only have read-only access to the data.
The FireStorm Repository is a data storage system accessible to both client and server. It supports updating, and notification of updates to connected systems. Carefully controlled access to the Repository can be given to clients and servers in order to facilitate their data transfer needs.
The Local Repository Cache LRC allows data storage local to a particular client. It is not subject to the restrictions of the FireStorm Repository on controlling access, but it is also only available for access by the client. Additionally, there is no sharing of LRC data even for the same account so data you save for a user on one computer is not available on another computer even for that same user.
Accessing the Repository is generally an asynchronous operation. To support the asynchronous nature of uploads and downloads, well known script callback function names are used to notify the scripting environment of the occurrence of events.
Server exposed functions
These external functions are for use with the FireStorm repository, data is available to both server an client but access to saving data must be carefully managed.
external function SaveRepositoryData(name as String, callbackScript as ScriptRef, data as String) as ID
Writes the data to the repository as a text file with the given name. The name has strict requirements which must be met or a Script Error will be thrown. The ID tag of the request is returned. Any existing data stored previously under this name is lost. No extension is provided automatically, so if the name does not have one, the file will be without extension.
The file is stored always in the ScriptData folder under the root of the repository.
external function LoadRepositoryData(name as String, callbackScript as ScriptRef) as ID
Starts a request to retrieve script data from a text file called 'name' in the ScriptData folder under the repository root. Returns the ID tag of the request.
Server script callbacks
These functions must be declared in the callbackScript for the previously defined functions to work.
function RepositoryDataLoaded(name as String, requestTag as ID, successful as Boolean, data as String)
This function is called after a LoadScriptData request. If successful is FALSE, the data was not found, and the data parameter will be an empty string.
function RepositoryDataSaved(name as String, requestTag as ID, successful as Boolean)
Called after a SaveScriptData completes. Successful indicates if the save request worked.
Client exposed functions
external function DownloadRepositoryData(name as String, callbackScript as ScriptRef) as ID
This exposed function initiates a request for data from the Repository in the ScriptData folder.
external function UploadRepositoryData(name as String, callbackScript as ScriptRef, data as String) as ID
Requests an upload of data to the Repository in the ScriptData folder.
Client script callbacks
function RepositoryDataDownloaded(name as string, requestTag as ID, successful as Boolean, data as String) as Boolean
This function is called after the download request has been processed. This function can also be called when downloaded data has been updated. Return TRUE from this function if you want to be called at a later point with new data. If FALSE is returned, or if successful was not true, you will not be able to get new data.
function RepositoryDataUploaded(name as string, requestTag as ID, successful as Boolean)
This function is called after an upload request has been processed. The successful parameter indicates if the upload was successful.
Local Client Repository Storage
It is often useful to be able to store information locally on the user's computer, either as a cache or a place to store information unique to a particular computer such as graphics settings. Data stored in the local repository cache is only available when using the computer in which the LRC is installed.
external function LoadLocalRepositoryData(inputFQN as String, callbackScript as ScriptRef) as ID // asynchronous, does not expect prepended local repository path // callback is made to the function function RepositoryDataDownloaded(name as String, requestTag as ID, successful as Boolean, data as String) as Boolean // in the specified callback script
external function SaveLocalRepositoryData(inputFQN as String, callbackScript as ScriptRef, data as String) as Boolean // synchronous, does not expect prepended local repository path, interestingly this does not actually callback to // the callback script. Since the call is synchronous, the inclusion of a callback script parameter seems to be // an oversight as it is unnecessary and unused..
external function DeleteLocalRepositoryData(inputFQN as String) as Boolean // synchronous, does not expect prepended local repository path
external function GetExternalReferenceForLocalRepositoryFQN(inputFQN as String) as String // expects FQN with leading slash
external function DoesLocalRepositoryFQNExist(inputFQN as String) as Boolean // synchronous, does not expect prepended local repository path
external function StageGetTextureAsRawData(stageNameParam as String, formatParam as String) as RawData // used to save off a virtual stage's texture
external function SaveLocalRepositoryAsRawData(inputFQN as String, callbackScript as ScriptRef, data as RawData) as Boolean // synchronous, does not expect prepended local repository path, interestingly this does not actually callback to // the callback script. Since the call is synchronous, the inclusion of a callback script parameter seems to be // an oversight as it is unnecessary and unused.
The servers do not have the same local repository structure that the clients use. In particular, the notification of updates is not supported at the server level. This can be worked around by client/server communication during update events.
Much like modifying prototypes, this ability needs to be suppressed in the live version of the game. The normal deploy mechanism should be able to move the new data over when needed. This will however create deploy dependencies, since most of this data will be generated from GOM definition changes, and the deploy mechanism will have to be very informative that deploying generated data should only happen if the definition changes are also deployed.
The string that is saved and loaded is a wide character string, so storing Unicode text in these files is okay.
On the server, if you attempt to load a file, but the file is not found by FQN in the Repository, the response that you get in script will lack an FQN. You will still be able to identify the response by the tag.
On the client, the RepositoryDataUploaded callback is never called. The FireStorm API lacks the required information to reliably connect the request to upload with the response of successful or unsuccessful uploads. If the upload is not successful, an Error message will be printed to the client's error output.