Environment management – ShiVa Engine

Environment management

You have 2 ways to initialize environment of a game.
The first and easier way is to create the variables in the Environment Tab of Game Editor.
These variables will be set at game-start but the major inconvenient is that their values are hard-coded.

The second way is to ask a network configuration to a HTTP server.

How to ask this network configuration ?

There is 2 ways to retrieve it.
To receive the network configuration before the start of the game, set the ‘Server’ parameter of the plugin or of the standalone player with the url.
Web player : STK display web generator

Standalone player : S3DEngine.exe –Server=http://www.myurl.com/NetworkConfiguration.php
To receive the network configuration during the game, use network.authenticate ( sURL, sLogin, sPassword ).
The login and the password can be empty.
The login is sent through the post variable $_POST[‘LOGIN’]. The password is sent through $_POST[‘PWD’].

How does the server respond to that request ?

The response must be an XML response formatted as following :

<AUTH>
  <Network>
    <S3DServer name="Name of the S3DServer"  url="IP:Port of the S3DServer" />
    <EnvServer url="URL of the page to manage  environment" method="method of the management"/>
   </Network>
   <Users>
     <Local userId="Id of the player" />
    </Users>
    <VE i="Id of the Local player" n="Name of the environement">Initialization of the player environment </VE>
 </AUTH>

S3DServer gives the IP and the listening port of the S3DServer (only use for multiplayer applications)
EnvServer gives the web url which is in charge of managing environment save and load requests. The method can be set to ‘POST’ or to ‘XML’. By default, method is set to ‘XML’.
Local userId change the ID of the local user which is, by default, to 0.
For request send via network.authenticate function, answer must be waited as long as the network.getStatus( ) function returns network.kStatusPending.
If the ID is set to -1 or to the keyword ‘INVALID’, network.getStatus( ) function will go from network.kStatusPending to network.kStatusNone. This indicates that the player authentication has been refused.
Else, the network.getStatus( ) function will go from network.kStatusPending to network.kStatusAuthenticated.
The initial environment for the local player is formatted as the response of a load environment request (see bellow).
Take care to set the ID environment (‘i’ attribute of VE) to the same ID that Local userId.
if Local userId is -1 or INVALID, the ID of the local user will stay unchanged. So you have to set the ID environment to 0.

Load Variables

To load a complete environment, use application.loadCurrentUserEnvironment ( the environment name you want to load ).
To load only an environment variable, use application.loadCurrentUserEnvironmentVariable ( the variable name you want to load ).
If the network configuration contains ‘EnvServer’, the load request will be automatically sent to the Environment Server. Otherwise, it will load a local binary file (.sts).

How is the load request sent to Environment server ?

The load request will send a HTTP POST request with following variables :
$_POST[‘PLAYER’] contains the ID of the current user
$_POST[‘ENV’] contains the name of the current environment
For single variable load, it will add :
$_Post[‘VAR’] contains the name of the requested variable
Tips : The variable name may be what you want in reality such as a pre-built SQL command.

How does the server respond to that request ?

The response must be an XML response formatted as following :
value
value
value
… as many as you want to add variable
The variable type is a number
– 1 for number (value can’t be greater than 2147483648)
– 2 for string
– 3 for boolean (true value can be written ‘1’ or ‘true’ )

How do I know when response is arrived ?

If you load a complete environment, the response is arrived when the environment variable count is greater than 0 (remember that loadCurrentUserEnvironment function entirely cleans the current environment).
If you load a single environment variable (or a set of variables using wildcards), you have to check the status of the variable (or just one of the variables of the set) using application.getCurrentUserEnvironmentVariableStatus (Nameof the variable).
The status of variable(s) is set to application.kStatusLoading when the load is requested and go to application.kStatusReady when it’s arrived.
If you didn’t use the name of an existing variable, you cannot test its status. The tricks is to add a new variable in your response (LoadIsArrived for example) and test its status.
As long as this variable is not arrived, its status is application.kStatusNone and then will be application.kStatusReady when it’s arrived.
Use application.unsetCurrentUserEnvironmentVariable (Name of your temporary variable) to destroy it and reuse it later for the same purpose.
To wait a response, you can do it in a loop of a state.
You also can build a timer : create an handler which will check the status and send to itself a delayed event if the check failed to check later (postEvent function).

Save Variables

To save a complete environment, use application.saveCurrentUserEnvironment (the environment name under which you want to save it ).
To save only an environment variable, use application.saveCurrentUserEnvironmentVariable (the variable name you want to save). The variable name can contain wildcards *.
If the network configuration contains ‘EnvServer’, the save request will be automatically sent to the Environment Server and no response is expected in return (if any, it will be ignored). Otherwise, it will save in a local binary file (.sts).

How is the save request sent to Environment server ?

The format of the save request depends on the chosen method (‘POST’ or ‘XML’). Each one have pros and cons.
The POST method will send a POST variable for each variable of the environment.
$_POST[‘SAVE_PLAYER’] contains the current user ID
$_POST[‘SAVE_ENVNAME’] contains the current environment name
$_POST[‘Variable Name’] contains the value of the variable named with the “Variable Name”
$_POST[‘Variable Name’] contains the value of the variable named with the “Variable Name”
$_POST[‘Variable Name’] contains the value of the variable named with the “Variable Name”
… as many as the environment variable count
This method is very easy to implement but need to know in advance the name of the variables.
The XML method will send a XML representing the environment in a single POST variable.
$_Post[‘stm’] contains the complete environment in a formatted xml as following
value
value
value
… as many as the environment variable count
The variable type is a number
– 1 for number (value can’t be greater than 2147483648)
– 2 for string
– 3 for boolean (true value can be written ‘1’ or ‘true’ )
This method is need a XML parser but you don’t need to know in advance the name of the variables.

How does the server respond to that request ?

The server don’t have to send response ! Even if it does, the response will be ignored.

How do I know when response is arrived ?

The saving operation is not an asynchronous operation for now. So just after the return of the function, consider that it’s done.


  • slackBanner