category: Application fundamentals

Stormancer applications are managed using a set of web apis that can be leveraged from any programming language supporting web requests (through CURL from instance.)

Furthermore, the Stormancer management portal offers some basic management capabilities. We intend to improve them with time.

Libraries

A PHP library & a .NET library are available on github. This article will focus on the .NET library, but most informations are applicable to the PHP version.

The management libraries can be included in Stormancer server applications like in our game lobby component or in any external application, client or server. The library is a wrapper of the Stormancer web API, and is built using asynchronous Tasks for optimal performance.

It allows you to - Create scenes - Delete scenes - Get scene informations - Send secure requests to scenes through HTTP (Handled through the Scene.RegisterApi method on server applications.) - Create connection tokens to private scenes

The library is available on nuget. We are open to your feedbacks and suggestions :)

Examples

The game lobby open source component makes extensive use of the management API to create, manage and delete game sessions implemented as scenes.

Create a client

You need your application management identifiers available on the app dashboard to use the management client.

var client = Management.Client.Client.ForApi(Constants.AccountId, Constants.Application, Constants.Key);

Create e scene

 await client.CreateScene(sceneId, type, isPublic, null, Platform.Core.Models.LifecycleMode.Transient, customData); 

The CreateScene creates a scene of type typewith the specified sceneId. It can be accessed from the client without token if isPublic is true (lobbies or authentication scenes work often this way. Or your own web server could use the management client to create a token for authenticated users).

If you specify data in the customData, it will be provided as argument to the scene Scene.OnStarting method. This can be used to further customize scenes at runtime, specify AI behavior or enforce player limitations.

Currently the other parameters are not used by the Stormancer platform, they can be set to values in the above sample without risk.

Remarks

Create scene can update an existing scene if sceneId already exists. It can be used to change the access rights (isPublic) of existing scenes. The other parameters will be updated too, but changes applied only when the scenes are recycled (on deployment for instance)

Get scenes


var scenes = await client.GetScenes();

Returns informations for all the application scenes, including the creation parameters and the number of players connected to the scene.

You can get informations about only one scene with the GetScene method. If possible this approach should be prefered for better performance.

var scene = await client.GetScene(id);

Delete a scene


await client.DeleteScene(scene.Id);

Create connection tokens to private scenes

 var token = await client.CreateConnectionToken(id, new User{ Id = playerName, Name = playerName }); 

Creates a connection token to private scenes with the provided secure user data. You can put arbitrary data in the token. The client can use the token to connect to private (or public) scenes with:

var scene = await unityClient.GetScene(token);

On the server, the token data can be retrieved with the connection.GetUserData<T>() method.

var data = request.Connection.GetUserData<User>()

Send requests to the server through the HTTP channel

You can send json data to your Stormancer application from any HTTP enabled client. This feature is very useful to retrieve data or drive the server from external tools or web application. For instance, that's a good way to implement a realtime push system, or to send admin messages to connected players.

 var customData = "Hello world!";
 var result = await client.Send(sceneId, "myRoute", customData);
 Console.WriteLine(result);

To handle these requests serverside, you have to call the Scene.RegisterApiRoute method before the scene startup (in a behavior, the OnAttached method is perfect location for that)

 AssociatedObject.RegisterApiRoute<string,string>("myRoute",async message=>{
   AssociatedObject.Broadcast(message);
   return "broadcasted!";
 });

This small sample will broadcast "Hello world!" to all the users connected to the scene, then write "broadcasted!" to the console.

Order: 1000