Features

Who, what, and where

This collection keeps a list of players that are currently playing the game. It tells you who (via their pictogram name) is online, what they're doing (sleeping, etc.), and where they are.

Adjustable update interval

You can change the update interval if you wish. However, 1 minute is the minimum. But if you want it to only update every five minutes or whatever instead, you can do that quite easily.

How to use

Prerequisites

Under the cut

Make sure your code is under the cut, with the blog entry input format set to BBCode.

JavaScript understanding

You need to know JavaScript in order to use this aside from its examples.

Code

First off, there is a lot you can do with this code — it's mostly data. You need to make some code which interfaces with this module in some way. What is it you want to do? Look at some examples and see if any of this seems useful to you.

Place the below code into your blog post. Note that you place the path to the source file into the part where it says YOUR FILE HERE.

<img style="display: none;" src="/community/sites/all/modules/smileys/packs/ToT/redface.gif" onload="var script = document.createElement('script'); script.type = 'application/javascript'; script.dataset.main = 'YOUR FILE HERE'; script.src = 'http://requirejs.org/docs/release/2.1.15/minified/require.js'; document.head.appendChild(script);">

Inside the source file, you're going to want to tell the collection to start updating:

requirejs(["path/to/config.js"], function() { // Note: not a real link. This file lists where all the dependencies are. Exclude if you have defined them elsewhere.
	requirejs(["collections/gms-player-collection"], function(PlayerCollection) { // Get the dependency.
		var players = new PlayerCollection(); // Create an instance.
		players.on("sync", function() {
			// Do something every time it updates.
		});
		players.startUpdating(); // Now it will gather the appropriate data.
	});
}

Once you have that, you should be all ready to go. Please note that once you submit your changes, you may need to refresh the page (such as if you are using Chrome or Safari).

Examples

Place the JavaScript file for the example you want to use where it says YOUR FILE HERE.

Example 1: Where are they?

File for this example: here.

A simple thing you can do is check which players are online and where they are. Let's say you want to know where Stria, Talla, Gretai, and Wind are. The following code will populate an HTML element with that information for each player that is online.

<!-- HTML. Place the below code where you want this to show up in your blog entry. Fill in the part that says data-gms-pictogram-list with a space-separated list of the pictogram names you wish to follow. -->
<div id="player-collection-example-1" data-gms-pictogram-list="DVe6 ITq1 1MXnx FTg2" style="background-color: brown;"></div>

// This should be part of your JavaScript file. Look at the provided file for this example in its entirety.
var players = new PlayerCollection(); // Instantiate a list of online players.
$(document).ready(function() { // Wait until the HTML of the page is fully parsed.
	var exampleBox1 = document.getElementById("player-collection-example-1");
	if (exampleBox1) { // Make sure this element exists before attempting to alter it.
		var pictogramWordsString = exampleBox1.dataset.gmsPictogramList; // Corresponds to data-gms-pictogram-list.
		if (pictogramWordsString) { // Don't do anything if the appropriate data- attribute isn't filled in.
			var pictogramWords = pictogramWordsString.split(" ");
			players.on("sync", function updateBox() { // This happens each time players is updated.
				var currentPlayers = players.filter(function isPlayerInList(player) {
					var word = player.get("word");
					return _(pictogramWords).contains(word); // Note: Underscore function.
				}, this);
				
				if (currentPlayers.length === 0) {
					exampleBox1.innerHTML = "None of your players are online.";
				} else {
					var outputs = currentPlayers.map(function getStatusText(player) {
						return player.get("word") + " is online at " + player.get("x") + " x " + player.get("y");
					}, this);
				
					exampleBox1.innerHTML = outputs.join("<br>"); // Separate each output with a new line.
				}
			});
			players.startUpdating(); // Start fetching the list of players every minute.
		}
	}
});

This results in:

Which will update every minute.

API

If you wish to implement your own behavior, here are some functions you can call on these items.

PlayerCollection

PlayerCollection.prototype.startUpdating()

This tells the collection to start fetching the status periodically from the server. It is best to call this last, after you have all its updating callbacks set up.

PlayerCollection.prototype.stopUpdating()

This tells the collection to stop updating.

PlayerCollection.prototype.setUpdateFrequency(numSeconds)

This changes the updateFrequency to the specified number of seconds. Note that 61 seconds is the minimum as that is the same frequency at which the player status page itself updates.

players.setUpdateFrequency(90); // Set the update frequency to every one and a half minutes.

Backbone methods

This collection is a Backbone collection. You can read more about those here.

players.once("sync", someFunction); // Do something the very first time the collection is updated.
players.first(3); // Get the first three players in the list.

PlayerModel

var player = players.sample(); // Get a random player from the list.

Each element in the player collection represents one player. These models have four general attributes: word (the pictogram's name), x position, y position, and state.

PlayerModel.prototype.get("word")

Gets the name of the player's pictogram.

console.log(player.get("word")); // Example output: 1Gchy

PlayerModel.prototype.get("x")

Gets the x coordinate of the player.

PlayerModel.prototype.get("y")

Gets the y coordinate of the player.

PlayerModel.prototype.get("state")

if (player.get("state") === 0) {
	// This player is sleeping.
}

Gets the id of the current state of the player. See what they correspond to in this table:

Note that some are missing and the ones that aren't may be inaccurate. If you would like to help gather the remaining states, play the game and continuously perform an action around the time the player status page updates (every 61 seconds). If you get a number that is not listed in this table, tell me what action gave you that number. I don't know if the states are listed in the game files or elsewhere, so, if you think there's a better way to find them, feel free to comment.

Backbone methods

Each element of a player collection is a Backbone model. You can read more about those here.

Source

The code for this module can be found here.

License

This code is released under GPL v3+. Among other things, this means you can redistribute applications using this code as long as you use the same license and provide the source. Remember to leave the copyright notices where they are. Read about the license here.

Credits

Thanks to Hum for initially gathering most of the player state data. Thanks to Aivilo for states 11 and 12, the correction on state 3, and the 61 second rule.

Feedback

Do you have any questions? Do you find this useful? Did you find any mistakes? Does something not work in your browser? Leave me a comment. Do you have a good idea? Suggestions are always welcome.

If you find something wrong, please leave a description of the anomaly — you don't have to fix it yourself. Also include what browser(s) and what operating system you are using, especially if you notice that the problem doesn't happen on other platforms.

Current bugs

Safari may prevent the map from working properly when in private mode

This is an issue with another module of mine and will be fixed as soon as I get to it.

Infrequently Asked Questions (iFAQ)

Whaaa…? I don't get any of this

I know this may be a little much for some of you, but I'll try to simplify and explain this as much as possible in the future. For right now, however, this is just a guide for JavaScripters.

See also

TEFc

• The stone balancers's biography contains a similar example to example 1. When stone is online, the biography will tell you where he's at, what he's doing, and who's near him. If he is not online, it will simply say so.

External

• Backbone.js, a framework I used for this module.
• Underscore.js, a cute little collection and utility library.