API Basics

This tutorial will give you a initial look into developing with the SandBoxd backend. If you are not interested in utilizing the features of SandBoxd then feel free to upload your game as-is. There are no requirements for publishing your game.

1. Setup a Workspace

First you will want to setup a workspace to put all your files in for the development process. So create a new workspace in your favorite JavaScript IDE or just create a new directory. I'm going to call this workspace MyFirstSandBoxdGame. For the rest of this tutorial I will make no assumptions about your development IDE and will assume you are just working with the files on your hard drive.

Next create a file in your newly created workspace called index.html. This will be the entry point into your new SandBoxd HTML5 game. Open this file and paste in this very simple boilerplate code:

<!DOCTYPE html>
<html>
<head>
	<meta charset='utf-8' />
	<meta name='viewport' content='width = device-width, initial-scale=1, maximum-scale=1, user-scalable=no' />
	<script src='https://ajax.googleapis.com/ajax/libs/jquery/1.8.2/jquery.min.js'></script>
	<script src='https://sdk.sandboxd.com/js/20140305-2.0.51/sandboxd.js'></script>
	<script>
		
	</script>
</head>
<body>
	<pre id="log"></pre>
</body>
</html>

I will skip over explaining most of the code above since this isn't an introduction to HTML tutorial. One thing to notice is that we are including the SandBoxd JavaScript library via the line <script src='//sdk.sandboxd.com/js/20140305-2.0.51/sandboxd.js'></script>. Let's take a minute to go over the versioning. The versioning works as follows: {SERVER API VERSION}-{CLIENT LIBRARY VERSION}.

The {SERVER API VERSION} is the date that this version of the SandBoxd API was authored. This date will only change if a major breaking change is introduced such as adding/removing a feature.

The {CLIENT LIBRARY VERSION} is broken down into 3 further versions: {MAJOR}.{MINOR}.{BUILD NUMBER}. The build number changes most frequently and you don't need to worry about your code breaking when switching build versions. Usually a build number change indicates a bug fix. A minor version change indicates that existing code may break. Likewise with the major version, but it is reserved for more drastic changes.

You should also take note of the <pre id="log"></pre> line. This is where we output to show what's going on behind the scenes. All of our subsequent game logic will go in between the currently empty script lines.

2. Write the Game Code

Now that you have a working template you can begin coding your game. In this example we will not be really making a "game" per se; instead we will be exploring some basic functionality of the SandBoxd API. Copy the following code into your empty script tag to get started:

$(function () {
	//Log functions to make strings appear on the dom
	function log (str) {
		$("#log").append(str + "\n");
	}
	function logObject (name, obj) {
		log("---Printing properties of " + name + "---");
		if (obj != null) {
			for (i in obj) {
				log(i + " -> " + obj[i]);
			}
		}
		log("---End Print---");
	}
	
	//Let's load all the current user's profile information
	sandboxd.getUser(function (err, data) {
		if (err == null) {
			//A null err value indicates there was no problem with query
			logObject("user", data);
		} else {
			//An error occurred
			//We can print the contents of err to see what the error was
			console.error(err);
		}
	});
});

The above code should be easy enough to read for anyone resonably versed in JavaScript and jQuery. The top two functions log and logObject are just used to output strings to the body of the document so we can see what is going on. The interesting part is below when we start using the SandBoxd API.

Using the sandboxd.getUser() query we can retrieve information about any user on SandBoxd. If no user id is supplied then the library will get the user info of the current user. The current user is determined based on the value of the "uid" query parameter passed in the URL. SandBoxd will automatically fill these values in when a user plays your game. For testing you can fill these values in manually.

3. Test the Game Locally

To run this game locally you can simply drag and drop the index.html into your favorite browser. When you run the game you should see a property dump of the user object returned from sandboxd.getUser(). Take note of the name. When the user's uid is not available then the default behaviour is to treat the current user as a Guest account. Feel free to play around with this by adding ?uid=2 to the end of the URL.

4. Upload the Game to SandBoxd.com

Now that you have a working game you can upload it to SandBoxd.com for others to play. Read getting started if this is your first time uploading a game to SandBoxd.

Notice that when you play your game the information displayed comes from your account.

5. Next Steps

Now that you have gotten your first taste for using the SandBoxd API you can move on to more advanced topics in the tutorials section. Alternatively you can jump right into the JavaScript API reference and start coding for your own game.

One thing to keep in mind is that this tutorial was written for using the JavaScript version. If you are interested in programming in another language we do offer SandBoxd SDKs in various other popular languages. Check out the SDK section for a list of available SDKs.