Contents
Creating or editing a game event
Using the 3XH client in a game
Server side user reward system
General guidelines for game event creation
Silverlight high score and in game achievement system (code name 3XH) is a system that can be integrated into any Silverlight game in order to manage user game events such as high scores, achievements etc. 3XH is built on a client server architecture. The client side is integrated into a Silverlight game and the server side is a service running on dedicated 3XH servers.
The system is free to use, can be used on any web site and is built to simply the creation and management of high scores, achievements and other in game events.
To use 3XH you need 2 things:
1. A Mashooo user account.
2. A game hosted on Mashooo.
Once you have the prerequisites in place you can start using the 3XH system in your game.
Using 3XH is very simple and requires 2 easy steps:
1. Create a new game event through the developer interface (High score, achievement etc.)
2. Use the 3XH client from inside your game to send/retrieve events defined in step 1.
Note you can repeat steps 1 and 2 for as many events as you need in your game.
Before we proceed to create user game events let’s define what a user game event is:
1. User game events are events occurring in a game, during user interaction with the game.
Example: user achieved a high score, user completed a level, user killed all enemies in level, etc.
2. Game events are pertaining to a specific user and can normally be quantified.
Example: User X got 200 high score; user Y completed level in 20.5 sec.
Note that each game can define multiple events.
Example: A game that contains 3 levels of difficulty (easy/hard/insane) and 1 type of achievement (user did the monkey walk).
Creating and managing game events is done through the 3XH developer interface.
Follow the steps below to create a new game event:
1. Login into your developer account.
2. From the drop down list choose an application (game) that you want to create an event for and press the edit application button. This will create a new application or edit an existing one.
3. If you haven’t done so before type a new application secret and press the save changes button.
4. Press the create event button to create a new event or the edit button to edit an existing event. You will be taken to the edit event page where you can define the new event properties.
5. After you have finished defining the event press the save event button in the bottom of the page
To use 3XH in a game you need to follow 3 steps:
1. Download the 3XH developer kit and extract the zip file to a folder in your computer (Example: C:\Projects\3XHDevKit).
2. Add a reference to 3XH.dll and CPCSL.dll in the project you want to use the 3XH client (in the above example the DLL files will be found in C:\Projects\3XHDevKit).
3. Call the low level API or use the high score ctrl to show and submit high scores and other game events.
The best way to get started is to use the high score control. The high score control wraps the lower level API and provides the functionality needed to show/submit high scores, register/login users etc. In most cases it will probably be the best choice to use.
The high score control interface - IHighScoreCtrl is defined in 3XH.dll.
Below is an example of how to use the high score control to show a list of scores for an event type:
/// <summary>
/// A simple demo function that shows the high score control for an event type
/// </summary>
/// <param name="applicationKey">The application/game key assigned to the developer</param>
/// <param name="applicationSecret">The application/game secret chosen by the developer</param>
/// <param name="parentPanel">The parent canvas/grid that will host the high score control</param>
/// <param name="eventType">The event type to display in the high score control</param>
public static void showHighScoreCtrlDemo(string applicationKey, string applicationSecret, Panel parentPanel, string eventType)
{
// create the high score control
_3XH.IHighScoreCtrl highScoreCtrl = _3XH.API.Instance.createHighScoreCtrl();
// init the high score control with the application key and secret
highScoreCtrl.init(applicationKey, applicationSecret);
// add the high score control as a child of the panel
highScoreCtrl.show(parentPanel);
// set the event handler that will be called when the user closes the high score control
highScoreCtrl.setOnCloseHandler((sender, e) => { highScoreCtrl.hide(); });
// call get high score list
highScoreCtrl.getHighScoreList(eventType);
}
The next example shows how to submit using the high score control.
/// <summary>
/// A simple demo function that shows the high score control submit function
/// </summary>
/// <param name="applicationKey">The application/game key assigned to the developer</param>
/// <param name="applicationSecret">The application/game secret chosen by the developer</param>
/// <param name="parentPanel">The parent canvas/grid that will host the high score control</param>
/// <param name="eventType">The event type to display in the high score control</param>
/// <param name="highScoreValue">The high score value to submit</param>
public static void submitAndShowHighScoreCtrlDemo(string applicationKey, string applicationSecret, Panel parentPanel, string eventType, double highScoreValue)
{
// create the high score control
_3XH.IHighScoreCtrl highScoreCtrl = _3XH.API.Instance.createHighScoreCtrl();
// init the high score control with the application key and secret
highScoreCtrl.init(applicationKey, applicationSecret);
// add the high score control as a child of the panel
highScoreCtrl.show(parentPanel);
// set the event handler that will be called when the user closes the high score control
highScoreCtrl.setOnCloseHandler((sender, e) => { highScoreCtrl.hide(); });
// call submit score
highScoreCtrl.submitScore(highScoreValue, eventType);
}
The low level API of 3XH should be used only when the high score control does not offer the flexibility and control you need in your game/application.
Note that you can combine the usage of the high score control and the low level API in the same application/game.
The low level API can be accessed through the – IClient interface and is defined in 3XH.dll.
Below is low level API usage example of submitting an event without showing/using the high score control:
/// <summary>
/// A simple demo function that shows the low level API submit function
/// </summary>
/// <param name="applicationKey">The application/game key assigned to the developer</param>
/// <param name="applicationSecret">The application/game secret chosen by the developer</param>
/// <param name="eventType">The event type to submit</param>
/// <param name="highScoreValue">The high score value to submit</param>
/// <param name="userDefObject">Extra object to submit with high score - can be retrieved later</param>
public static void submitLowLevelAPIDemo(string applicationKey, string applicationSecret, string eventType, double highScoreValue, object userDefObject)
{
// create the 3XH client
_3XH.IClient esClient = _3XH.API.Instance.createClient();
// init the 3XH client with the application key and secret
esClient.init(applicationKey, applicationSecret);
// call submit score
esClient.submitEvent(highScoreValue, eventType, userDefObject);
}
Below is an example of retrieving events without showing/using the high score control:
/// <summary>
/// A simple demo function that shows the low level API get event list function
/// </summary>
/// <param name="applicationKey">The application/game key assigned to the developer</param>
/// <param name="applicationSecret">The application/game secret chosen by the developer</param>
/// <param name="eventType">The event type to retrieve</param>
/// <param name="onEventListReady">callback delegate that the system will call with event information </param>
public static void getEventListLowLevelAPIDemo(string applicationKey, string applicationSecret, string eventType, _3XH.OnEventListReady onEventListReady)
{
// create the 3XH client
_3XH.IClient esClient = _3XH.API.Instance.createClient();
// init the 3XH client with the application key and secret
esClient.init(applicationKey, applicationSecret);
// call get event list on all events of type eventType in the past 30 days
esClient.getEventList(eventType, new EventFilter(EventFilter.Type.AbsoluteValue, 30), onEventListReady);
}
public void onEventListReady(UserEventList eventList)
{
foreach (UserEvent evnt in eventList.EventList)
{
MessageBox.Show("User " + evnt.UserData.UserName + " scored " + evnt.EventData.NumericalValue.ToString() + " and user def object was " + evnt.EventData.UserDefinedData.ToString());
}
}
The next example shows how to get the current user information (the user who is currently playing the game):
/// <summary>
/// A simple demo function that shows the low level API get current user info function
/// </summary>
/// <param name="applicationKey">The application/game key assigned to the developer</param>
/// <param name="applicationSecret">The application/game secret chosen by the developer</param>
/// <param name="onCurrentUserInfoReady">callback delegate that the system will call with user information </param>
public static void getCurrentUserLowLevelAPIDemo(string applicationKey, string applicationSecret, _3XH.OnCurrentUserInfoReady onCurrentUserInfoReady)
{
// create the 3XH client
_3XH.IClient esClient = _3XH.API.Instance.createClient();
// init the 3XH client with the application key and secret
esClient.init(applicationKey, applicationSecret);
// call get current user information
esClient.getCurrentUserInfo(onCurrentUserInfoReady);
}
public void onCurrentUserInfoReady(User userInfo)
{
MessageBox.Show("Welcome " + userInfo.UserName);
}
Note that current user information can also be obtained using the high score control interface:
Example: highScoreCtrl.getCurrentUserInfo(onCurrentUserInfoReady);
The user game events you create will be given a value by the system. A user will be credited for each game event they generate/achieve. Example: When a user achieves a daily high score the system will automatically reward him with X points. The points will be translated to valuable prizes.
User game events should be created for each type of user achievement that you believe can add value to the game. The events should encourage users to compete, increase the replay value and make the games just more fun to play.
Example: In a game that has levels and a high score, you can create one event type for the high score and another event type for levels completed.
No system is hack proof but there are a couple of things you can do on the client side to make it a little harder on casual hackers to hack your game.
1. Encrypt or camouflage sensitive strings especially your API secret.
2. Use a code obfuscator if possible.
3. Change your API secret if you feel your game have been hacked.
Note that we will be monitoring and employing anti hacking techniques on the server side as well. But a combined client and server vigilance will make a much stronger defense against hackers.
To make it easier to test and integrate 3XH into your games we prepared a simple demo project.
It is a self contained visual studio solution with a Silverlight demo application and a web application to host it. You can find the instructions on how to use it below.
Demo Project Usage instructions:
1. Download the demo solution zip file at: http://www.mashooo.com/eventsvc/Downloads/3XHDemo.zip
2. Extract the zip file to a directory on your development machine.
3. Open the 3XHDemo solution inside visual studio and run it (the web project will run by default displaying the Silverlight demo application). *
4. You will see a simple user interface with several text boxes where you can enter your key, secret, event type and other information. Enter the information and press the various buttons to see the effects and test your event types.
· Note you must run the demo through a web project to be able to use the demo. If you run the Silverlight application stand alone it will not function properly. This is due to Silverlight design limitations that do not allow making web calls outside of web page.
Please feel free to send us any comments or suggestions you may have!