How to use Game Session Storage
In this tutorial, we’re going to explain how to save a match’s data with Game session storage. The first thing that must be made clear is that this function is designed to save the state of a match in a certain context. And what do we mean by context? The best way to explain it is with an example.
Imagine it were possible to create tournaments for a certain game. This way, a player could have, for a single game, several matches in a tournament with one set of characteristics, other matches played in another tournament with other characteristics, and even normal matches outside tournaments. All of these situations (the different tournaments, the normal matches) are what we call contexts.
That is to say, it is possible that one player in one game saves several different matches’ data depending on the context at the time it was saved. Continuing with our example, the game would have a series of specific data for a tournament, different data for another tournament, etc. This information belongs to the platform and is not available within the programming of the game.
How to save the data from a match?
Before beginning to save data, some decisions have to be made, based on the nature of the game and the data to be saved. Game Session Storage allows us to save data locally or on the server (the server is only available to players registered on the platform), so the first thing we have to decide is which data we need to save and where.
You can make this decision based on the following criteria:
- They should be saved on the server when:
- You want the player to be able to continue the same match on several different devices.
- The data are important for the integrity of the match.
- They should be saved locally when:
- You want the player to be able to play without an active connection.
- The data to be saved are not critical.
Generally, it’s preferable to save everything you can locally except the most sensitive data for the match (score, lives, level, money, etc.).
How the Game Session Storage Panel Works
After analyzing the game’s needs, the time has come to get to work. To start, the Games Editor provides a plug-in to be able to define the data to be saved and where to save them. To access this plug-in, select it on any open panel in the Logic Editor:
With this, the following panel will open:
Firstly, at (1) you can see the plug-in has 2 tabs:
- Edition. The Edition tab allows us to define the data we want to save and what their default values are.
- Simulation. In the Simulation tab, you can see, in real time, the values that the data we defined in the Edition tab are acquiring, and we can also edit them at any time during the running of the game; that is, when we click on the play button in the Preview
When we have many storage keys created, we can filter the list using the filtering buttons (2). From left to right, each icon means “locally”, “on the server”, and “locally/on the server” (more on that later).
In order to define the data we’re going to save, we’ll create what we call “save keys”. To create one of these keys, use the ‘+’ button (3).
Once you’ve clicked on it, the following dialog box appears:
As you can see in the image, 4 properties need to be defined for a save key:
- Storage field. This property defines where the game data will be saved, and has 3 possible values: locally, on the server, or locally/on the server. It is very important to understand the differences between these 3 values, since, depending on how we want to use the save service, we’ll need to use one option or the other.
- Locally. Establishing a local key implies that the value will be saved on the machine that’s running the game. This has the advantage that a connection isn’t required in order to be able to obtain or save the value. The disadvantages are that that value can’t be shared with other devices and that there is no type of security control over it, which means that it could be externally modified. Its main use is for saving non-critical data, or saving data that we want to be available without a connection.
- On the server. The keys saved on the server are only accessible to players who are registered on the platform, and are accessible from any device. If an anonymous player tries to access a server key in any way, he will get an access error message. Use this type when you want to save critical match data for a specific player (level, lives, etc.)
- Locally/On the Server. By establishing this option, the key will be saved on the server for registered players and locally for non-registered players. A common mistake is to think that the key is saved on the server if there is a connection and locally if there is not, and that is not correct. In the case of a registered user, this acts exactly like “on the server”. This allows us to save match data whether the player is registered or not.
- Type. At this time, you can save 3 types of data: Boolean (true/false), numeric, and strings.
- Name. The name that identifies the key, which must be unique. We will not be allowed to save two keys with the same name.
- Default value. This is the key’s default value. If we haven’t gotten around to saving the key (either locally or on the server) and we ask for it, we will get this value.
Once you’ve established the properties, you can click the OK button to finish creating the key.
Once all the keys we need to save the game’s state are created, you should have something similar to the image below.
For each key, you can modify only the environment (clicking on the icon) and the default value. If you need to change the name or type, you’ll have to delete the key and re-create it.
On the dashboard, there is a clonable project called space dogfight. This game saves the current level of the match, the player’s name (for a registered user) and, should the level be abandoned halfway through, the life of the player and the enemy. The options chosen to create the keys were:
- UserName. Saved on the server, since for anonymous players we’ll only use the name ‘guest’. This is a string-type and its default value is ‘GUEST’
- Level. In the case of a logged-in user, we’ll save the level on the server (that way the match can be continued on any device) and locally if the user isn’t logged in (locally/on the server). This is a numeric-type and its default value is ‘1’.
- Enemy Life and Player Life. These keys are not important, so we’ll always save them locally. If the keys exist, we’ll continue the match with the value they have, and if they don’t, we’ll use the default value to establish the lives of the player and the enemy (100).
How to save the data of a match?
In order to work with these data, 3 specific blackboxes have been created (GameSessionStorage tab), which work the same way:
- GetGameSessionData. Allows us to read the data saved in the selected keys. If there is nothing saved in any of the keys, the default value for that key will be returned.
- SetGameSessionData. This is used to save the values of the selected keys.
- ResetGameSessionData. Establishes the default values for the selected keys.
If you drag one of these blackboxes to a script and select it, you’ll see the following in its properties:
- The secure property is common to other blackboxes that perform actions on the server (for example, virtual goods). If this is activated (true) and the blackbox is run, should an attempt be made to run it again and there hasn’t been a response from the previous petition, the onPrevious output will be triggered and that petition will be omitted. If it’s deactivated, all the petitions that reach it will be sent.
- All and none simply mean select all or none of the keys (3).
- Here are the keys we’ve defined for our game are listed, and which ones we’re going to want to read, save, or restart are defined by making its value “true”.
These blackboxes have 4 possible outputs:
- onPrevious, already explained.
- available or done (depending on the blackbox) is triggered when an operation has been performed correctly.
- error. Is triggered when there has been any type of error in the operation.
- accesDenied. This output is triggered when the game tries to access a key which is stored on the server and the player is anonymous (not logged into the platform).
With everything we’ve covered so far, you have everything you need to be able to save the state of the match for each player.
Going back to the space dogfight example, we have basically 3 data we need to obtain:
- The name of the player.
- The current level.
- The life left for the enemy and the player.
The first thing you have to keep in mind is that the game is designed to be able to be played either anonymously or as a registered user. If the player is registered, he will have certain extra features, which, in this case, are asking for his name when a new match is created and saving that name on the server in order to welcome him to each match. The first thing we thought of was, at the game’s start, to put a GetGameSessionData and get the three data; the problem with that is that if the player were not registered, he’d always get the accessDenied output, since a non-registered player cannot access the server data. So, we need to obtain the server data one way and the local and local/server data another.
The first thing we’re going to do when the game starts is to try to get the player’s name (Script menu à get player name) by using the GetGameSessionData blackbox and setting it up to get only the “UserName” key. If the available output is triggered, that will mean the player is registered and it will give me the saved datum or its default value should nothing have been saved in it yet. If the accessDenied output is triggered, that will mean the player is anonymous, so we won’t ask for the player’s name:
In order to save the player’s name, in the game, upon clicking Start New Game, if the player is not anonymous, he’ll be asked to introduce the player’s name, and when Return is pressed, the name will be saved using the SetGameSessionData blackbox (Script menu -> enter name).
If he clicks on the Continue Last Game text, we’ll get the saved data by using GetGameSessionData and setting up the blackbox with all the keys except UserName. With this, we’ll get the player’s life and the enemy’s locally, and the level from the server should the player be logged in, or everything locally if he’s anonymous. As you can see, the behavior is different if the key is on the server since it always gives the response available (unless there is an error).
Finally, the data are updated when the level is changed (script SetNextLevel, in this case the level is updated with SetGameSessionData and the ResetGameSessionData blackbox is used to set the live of the player and of the enemy to their default value) and also when the home button is clicked during play (script play à fight à home button, in which case only the life is saved).
Now we have enough to load and save the game data for space dogfight.
How to simulate the storage and management of saved games? Is there any way to be able to put my game in a certain state?
Well, yes, for that, there is the simulation tab:
In this tab, we can see in real time the values for the keys in the Editor. There are several options:
20/01/2015 / No Comments
- Value of the simulation of each key. This is the value of each key; its content can be edited and it allows us to put the game in a certain state. Its most obvious use is for establishing startup conditions for a match, but it can also modify them during the match.
- When a value changes its initial value for another, this button appears, which allows us to reset it to the default value.
- When we stop a simulation (the stop button in the preview panel), we may want the values of the simulation that we’ve established to be put just as they were when we pressed play (in order to repeat the same situation several times), or maybe we want the last value to be saved (for example, in order to simulate that we’re playing several matches in a row). If we activate the do not persist option, the changes during the simulation will be omitted and when the simulation is stopped, the initial values will be reset.
- They should be saved on the server when:
- How to Integrate a Game into Your Website
- How to integrate a WiMi5 game in Moodle
- How to create texts from sprites using a SpriteText Blackbox
- How to clone a project
- New ways of interacting in wimi5
- How to easily adapt WiMi5 game templates to create your own games
- How to monetize your games using Virtual Goods
- How to use the CodeRunner blackbox
- How to use Game Session Storage
- How to Use Rankings
- How to publish your HTML5 game to other game platforms
- How to publish your HTML5 game on the Google Chrome Web Store
- How to set up game levels based on data from a text file: using the ParamMap.
- How to create a scoreboard for lives, time, and points
- How to Make a Scroll and a Parallax Scroll in 2D Games
- How to create collisions
- How to debug in WiMi5