Content API

It's great to see that you want to find out more about implementing user-generated content in your games! Platogo has a strong focus on user-generated content and community gaming, so we especially love games that take advantage of Platogo's unique features. Hang on and you'll notice that working with the Platogo LevelService is a breeze.

Game settings

You can go right ahead, and save and load levels in your game using the methods described later on. However, if you'd like each level to have its own scoreboard or to be able to categorize levels you might want to continue reading this section. There are a couple of settings that can be changed in the Level Settings on the Edit Game page.

Level categories

Levels can be tagged by users on the website. However, there might be occasions where you as a developer want to categorize levels at creation time. This is what level categories are there for. To give you an example: we defined categories in Picross in order to mark the board size of the created puzzle, which allows users to search for puzzles in their favorite size on the website or in the game. If you wish to use categories, you have must put them into the Categories text field as a list of comma-separated values (you'll need to do this before using them in your code.) Users will not be able to tag levels with these categories by themselves (if they try, they'll get a nice error message.)

Level scoreboard

Check this box if you want the levels to have a scoreboard. Level scoreboards behave almost the same as game scoreboards (please refer to the High Scores article for more information.) One difference is that there's no scoreboard name and no key: there can only be one scoreboard per level, so there's no need for keys to distinguish between different scoreboards. Furthermore, only the all-time best score entries are saved (i.e. there are no monthy, weekly or daily scores for level scoreboards.) Submission of level scores is done with PlatogoAPI.highscoreService.submitLevelScore(), as explained in more detail later.

Manage Levels

Under the menu item Manage Levels you can find a list of all levels created for your games that are currently in development. As long as your game has not been published, you can manually delete levels and level scores on this page. This might be useful if you create some not-so-pretty test levels, or keep changing the structure of the level data during development. Once the game has been published, however, you will no longer be able to remove levels. In published games, users can flag levels they feel are inappropriate, which – if justified – will be removed by our moderators.

Saving levels

The Platogo API provides the function PlatogoAPI.levelService.createLevel() to create new levels. Although it requires quite a lot of parameters, most of them should be pretty self-explanatory. Here's an example that should give you a rough idea of how to use the function. Some parameters are discussed in more detail below.

// generate level data object
var levelData : Object = new Object();

levelData.playerPos = new Object();
levelData.playerPos.x = 3.5;
levelData.playerPos.y = 5;

levelData.enemies = [ "Ninja", "Pirate", "Mother-in-Law" ];

// generate thumbnail; previewImage is a DisplayObject that is a graphical representation of the level
var thumbnail : BitmapData = new BitmapData( previewImage.width, previewImage.height );
thumbnail.draw( previewImage );

PlatogoAPI.levelService.createLevel( "Test", "For my Mother-in-Law.", LevelStatus.PUBLIC, levelData, ["big"], thumbnail, createLevelHandler );

function createLevelHandler( response : PlatogoResponse ) : void
{
	switch( response.status )
	{
		case PlatogoStatus.OK:
			trace( "The level has been successfully created." );
			var level : Level = response.data as Level;
			trace( level.name ); // "Test"
			break;

		case PlatogoStatus.NOT_LOGGED_IN:
			trace( "The user was not logged in and therefore the level could not be created." );
			break;

		case PlatogoStatus.ERROR:
			trace( "Something went wrong. This should never happen." );
			break;
	}
}

Since the sending of the data to Platogo might take a second or two, we advise showing an loading indicator upon calling PlatogoAPI.levelService.createLevel(). The callback is invoked as soon as the creation is complete.

Level data

We do not impose any particular structure for your level data: you can pass any of the following types or combination thereof: Boolean, Number, Object, Array and String. It is perfectly valid to store multiple nested arrays or objects with dynamic properties (have a look at the example above.)

Level status

A level has a particular LevelStatus which effectively determines the visibility of the level for different users. There are currently two values available:

• PUBLIC
• PRIVATE

LevelStatus.PUBLIC will by far be the most common. Use this status if you'd like to publish the level for the whole world to enjoy.

LevelStatus.PRIVATE s the most restrictive status and means that the level is only available for its creator: it will therefore never show up in the level list on the website. This might be useful if your level editor is more elaborate. You could provide means to allow users to save their creations, and to work on them later on before publishing them.

Level image

Level images make the level display a lot more interesting visually, and usually give the users a clue as to what the level is about. Levels with images in the level overview on Platogo's game site are therefore more likely to be clicked and played. While the image is an optional parameter, we highly encourage you to make use of it. The image must be a BitmapData instance with an optimal size of 440x330 pixels. If the image provided is larger, it will be proportionally scaled to fit the constraints. Smaller images are left untouched.

Level categories

If you'd like to assign one or more categories to the created level, you have to pass an array filled with the desired category values. Passing null or an empty array will associate no category with the level. The categories need to be specified in the Level Settings on the Edit Game page before you can use them.

Updating levels

An existing level can be updated using PlatogoAPI.levelService.updateLevel(), as long as the level has still a status of LevelStatus.PRIVATE. You can change the same properties that are available when creating a level: name, level data, status, description, image and categories. Once the level status has been set to LevelStatus.PUBLIC, it cannot be updated anymore. We do not want to allow changes then since it might make the level easier or harder which renders existing scoreboard entries meaningless and might upset users.

Deleting levels

As long as the level has a status of LevelStatus.PRIVATE, it is allowed to be deleted using PlatogoAPI.levelService.deleteLevel(). As soon as the level has been made available for friends or the world, there's no way for the developer to delete it: a level can then only be removed by our moderators should it be flagged by users (and subsequently confirmed by our moderators) as being inappropriate.

Loading levels

Retrieving a list of created levels

Getting a list of available levels is done using PlatogoAPI.levelService.findLevels() (we provide an example on how to use this function in the API documentation.)

Since we want to make things as easy as possible for developers, we develop components for the most common tasks concerning Platogo integration. We created a component that takes care of the chore of displaying available levels: it requires (almost) no code whatsoever and can easily be skinned to make it match the look and feel of your game. The component is open-source and is an ideal starting point for your own implementation if the need ever arises.

To display a level selection dialog, you simply have to drop the component onto the stage. A callback will be invoked by the component once the user clicks on a level. You can react upon the callback, start loading the level data, and start playing the level from that moment. More information on the component can be found in our Components article

Loading level data

PlatogoAPI.levelService.findLevels() returns a list of level instances that do NOT include their respective level data. Since we do not impose a limit of the level data's size (in bytes) it would be a huge waste of bandwidth to transmit it everytime you want to display a list of created levels. To load the level data you have to call PlatogoAPI.levelService.loadLevelData(). After the data have been loaded, they are passed back to the callback function and will be in the exactly the same format as you provided it during PlatogoAPI.levelService.createLevel() or PlatogoAPI.levelService.updateLevel().

Adding spit and polish

Tracking level plays

Contrary to game plays, level plays are not increased automatically. It is up to you – the developer – to invoke PlatogoAPI.levelService.playLevel() in order to increase the level's play count. This function should be called each time the user starts a level over. Failure to implement this feature is guaranteed to upset users who create levels in your game, as there's no other indication as to how often their level has been played.

Website level play callback

On your game page on Platogo there's an area dedicated to displaying levels. Users can use this to comfortably search and filter for levels they're interested in. If the user decides to play the level from the website, a callback is triggered so that you can start the desired level.

It's good practice to register for this callback using PlatogoAPI.registerPlayLevelCallback(). Ideally, you would display a dialog that asks if the user wants to stop his or her current activity in the game and really wants to play the level. If the user decides to play the level, you can then go ahead and load the level data and start the level. To get an idea how this can be done, just have a look at our game Picross.

Submitting level scores

Submitting levels scores is a simple process that is achieved by calling PlatogoAPI.highscoreService.submitLevelScore(). You can read more about high scores in our High Score API article

Rating and favoring levels

Providing means to rate and favor levels in your game is not really mandatory since users can always rely on the website for that. However, it might be more comfortable to be able to rate a level in-game directly after playing it. Fear not, as we're providing components to do just that, thereby removing the burden of implementing that functionality all by yourself.

Keeping level data low

Okay, this one is obvious. We do not impose any limit on the data size but you should try to not go overboard – users will appreciate it.

This work is licensed under a Creative Commons License.