Difference between revisions of "Game Cloud"
| Line 98: | Line 98: | ||
The example above shows a simple data access example that limits the number of players that can be involved in some activity. When a user enters the room the <code>OnEnter</code> event fires. We check if the global application data contains a PlayerCount key/value pair, and if so, we increment it, otherwise we initialize it to 1. If there have reached the configured maximum number of players, we abort, otherwise we execute similar logic to keep track of how many times this particular player has played our game. We mark the player as "Playing" so that when they leave we can decrement the global PlayerCount. This code does not demonstrate working with account scoped data, but it works the same as the persona scoped data, except as explained above you use the the GetAccountData, SetAccountData, AccountDataExists, DeleteAccountData methods on [[ParticipantExtended]]. | The example above shows a simple data access example that limits the number of players that can be involved in some activity. When a user enters the room the <code>OnEnter</code> event fires. We check if the global application data contains a PlayerCount key/value pair, and if so, we increment it, otherwise we initialize it to 1. If there have reached the configured maximum number of players, we abort, otherwise we execute similar logic to keep track of how many times this particular player has played our game. We mark the player as "Playing" so that when they leave we can decrement the global PlayerCount. This code does not demonstrate working with account scoped data, but it works the same as the persona scoped data, except as explained above you use the the GetAccountData, SetAccountData, AccountDataExists, DeleteAccountData methods on [[ParticipantExtended]]. | ||
| + | |||
| + | ==== Debugging Data Storage ==== | ||
| + | You can view and manipulate stored data via the [[Admin Web]]. Application global data can be found on the <code>App Data</code> tab of your application in the Game Cloud Applications section of the admin. Account and Persona scoped data can be found by looking up the account or persona, and then selecting <code>Data Entries</code> from the <code>Game Cloud</code> tab-drop-down. | ||
=== Dependencies === | === Dependencies === | ||
Revision as of 15:53, 23 August 2019
The Game Cloud is a Layer Two component that extends your server to add many common massively multiplayer role playing game (MMORPG) features as well as a suite of server world scripting extensions that simplify game programming.
Contents
Game Cloud Scripting
The Game Cloud offers a large extension to the server JavaScript environment. The main API access points are through the two global objects Cloud and Bot. I will provide scripting examples throughout this document. For more information about writing scripts for use in the world see Scripts and the World Scripting Reference.
Game Cloud Applications
The Game Cloud groups configuration and data storage into containers called Applications. An application can be developed, configured, and tested on your development server, and then published to your live server when you're ready. All of the application's associated objects move with the application as a single unit when transferred.
Developing an Application
Game Cloud applications are created and configured mostly through the Admin Web. Expand Game Cloud on the left navigation menu, and select Applications. Create a test application to get started. See Identifiers and Scope below for advice on selecting a good identifier for your application.
Once created, you can begin creating other Game Cloud objects (features) that will become part of your application. The objects you create will then be available for your world scripts to interact with. More complete examples of how this works will be given below.
Identifiers and Scope
The Game Cloud makes heavy use Identifiers which are strings of text that uniquely identify some object within a scope. Your application will have an identifier, as will most of the things you create within your application.
Good identifiers should use namespacing to help ensure they are unique. Identifiers should not contain spaces. I recommend you use a format like this:
company.feature.name
For Example
- vww.quests.firstquest
This helps ensure that things created by different companies or teams don't interfere with each other.
Generally speaking, identifiers are global in scope. This means they should be unique across all applications on your server. This is because an application groups objects for transfer, but does not provide a naming container. This is so that scripts and features from one application can interact with scripts and features from another application.
Data Storage and Scope
The Game Cloud offers several ways for your scripts to store and retrieve data. These are explained in Metadata and Data Storage sections. Data storage is always associated with (scoped to) an application. When a script wants to work with application data, it must first set an application context like so:
Cloud.SetApplication("vww.apps.example");
Generally, application data is considered to be "server local". This means that your application's stored data is not transferred between servers with the application. This is because the data stored by your scripts represents the runtime state of your world. What is transferred is the ``configuration`` of your Game Cloud features and also any Metadata stored with your application.
Application Features
Metadata
Application Metadata is a simple way for you to set some key / value pairs in the admin that will be available to your script at run-time. These values cannot be changed by your scripts. You can think of these as configuration values. They are configured on your application's Summary tab.
Your scripts must first set their application context, and then can query these values like so:
Cloud.SetApplication("vww.apps.reference"); var message = Cloud.GetMetadata("StartupMessage"); Debug.Log("Starting up with message: " + message); Chat.GetLocalChannel().Broadcast(message);
The example above shows how the value of the StartupMessage metadata item can be retrieved and used to broadcast a chat message into the instance local chat. For more information see Cloud Global, Chat Global, ChatChannelExtended and Debug Global in the World Scripting Reference.
Data Storage
Application Data Storage allows your scripts to store and retrieve key / value pairs associated with different objects. There are three different stores of application data:
- Application Global Data: Stored globally for your entire application. Their keys must be unique within the scope of your entire application. Use the
DataExists,GetData,SetDataandDeleteDatamethods on the Cloud Global object. - Persona Scoped Data: Stored for each Persona (avatar). This allows you to store information on a specific character in the game world. Their keys must be unique withing the scope of a single persona. Use the
DataExists,GetData,SetDataandDeleteDatamethods on any ParticipantExtended object. - Account Scoped Data: Stored for each user account. This allows your application to store some value shared among all Personae (avatars) of a user, so no matter which avatar they're logged in as, these values will be available. Their keys must be unique withing the scope of a single user account. Use the
AccountDataExists,GetAccountData,SetAccountDataandDeleteAccountDatamethods on any ParticipantExtended object.
Your scripts must first set their application context, and then can work with these values like so:
Cloud.SetApplication("vww.apps.reference"); // set your application context var maxPlayers = Number(Cloud.GetMetadata("MaxPlayers")); Log.WriteDebug("Starting up. Maximum Players: " + maxPlayers); Instance.OnEnter = function(/*ParticipantExtended*/ part){ // A new participant has joined the scene if(Cloud.DataExists("PlayerCount")){ var count = Number(Cloud.GetData("PlayerCount")) + 1; if(count >= maxPlayers) { part.SendChatMessage("Sorry, only " + maxPlayers + " players allowed."); return; } Cloud.SetData("PlayerCount", String(count)); part.SendChatMessage("Welcome, there are " + count + " players."); }else{ Cloud.SetData("PlayerCount", "1"); part.SendChatMessage("Welcome, you are the only player."); } part.SetData("Playing", "true"); Chat.GetLocalChannel().Broadcast(part.Name + " joined the game!"); if(part.DataExists("PlayCount")){ var plays = Number(part.GetData("PlayCount")) + 1; part.SetData("PlayCount", String(plays)); part.SendChatMessage("You have played before."); }else{ part.SetData("PlayCount", "1"); part.SendChatMessage("This is your first play."); } }; Instance.OnLeave = function(/*ParticipantExtended*/ part){ if(!part.DataExists("Playing")) return; part.DeleteData("Playing"); Cloud.SetData("PlayerCount", String(Number(Cloud.GetData("PlayerCount")) - 1)); }
The example above shows a simple data access example that limits the number of players that can be involved in some activity. When a user enters the room the OnEnter event fires. We check if the global application data contains a PlayerCount key/value pair, and if so, we increment it, otherwise we initialize it to 1. If there have reached the configured maximum number of players, we abort, otherwise we execute similar logic to keep track of how many times this particular player has played our game. We mark the player as "Playing" so that when they leave we can decrement the global PlayerCount. This code does not demonstrate working with account scoped data, but it works the same as the persona scoped data, except as explained above you use the the GetAccountData, SetAccountData, AccountDataExists, DeleteAccountData methods on ParticipantExtended.
Debugging Data Storage
You can view and manipulate stored data via the Admin Web. Application global data can be found on the App Data tab of your application in the Game Cloud Applications section of the admin. Account and Persona scoped data can be found by looking up the account or persona, and then selecting Data Entries from the Game Cloud tab-drop-down.
