This document describes how the Hark the Sound site discovers games to list, launches them, and communicates with them. For complete example of how to integrate your game into the hark site, see the tic-tac-toe sample on GitHub. It respects installs two difficulty levels (3x3 and 5x5) in the hark game catalog and respects user preferences set on the hark site at runtime.
The owner of the hark site (i.e., Gary) installs your game from a hark.json file you include with your game. For example, the JSON below shows the installer for the tic-tac-toe game:
{ "identifier" : "url", "items" : [ { "url" : "tictactoe#3x3", "label" : { "en-us" : "Tic-tac-toe" }, "tags" : { "en-us" : "grid, classic, multiplayer" }, "description" : { "en-us" : "The classic game of tic-tac-toe on a 3x3 board." }, "media" : { "icon" : "tictactoe/info/icon.png", "screenshots" : ['tictactoe/info/screenshot3x3.png'] }, "attribution" : "tictactoe/info/attribution.json" }, { "url" : "tictactoe#5x5", "label" : { "en-us" : "Tic-tac-toe" }, "tags" : { "en-us" : "grid, classic, expert, multiplayer" }, "description" : { "en-us" : "A harder game of tic-tac-toe on a 5x5 board." }, "media" : { "icon" : "tictactoe/info/icon.png", "screenshots" : ['tictactoe/info/screenshot5x5.png'] }, "attribution" : "tictactoe/info/attribution.json" } ] }
The url field is the unique, relative URL of the game under http://harkthesound.org/. The URL can contain a hash symbol indicating additional information the game can use to configure itself upon launch.
In the example above, the first game entry includes an app defined hash of 3x3. The tic-tac-toe game might use dojo.hash() to retrieve this value when launched to configure the size of the board. Other similar entries with hashes of 4x4, 10x10, etc. might get registered in the database for more or less challenging instances of the game if desired.
These three fields are for human consumption. The label is the human readable title of the game. The description is a longer explanation of the game. The tags are categories in which the game is listed for keyboard+audio users of the hark site.
All three are objects with strings stored under standard language identifiers. The home page uses dojo.locale to determine which to display and falls back on en-us if there is no appropriate translation.
The media object contains the URL of a 96x96 pixel icon representing the game on the home page. It also includes an array of 320x240 pixel screenshots of the game which may be featured on the hark site.
The attribution string can be empty or may reference another JSON file containing attribution info for the game code and 3rd party resources (e.g., Creative Commons licensed images, sounds, and music). The top level object in this JSON file is an array. It contains further objects in the following form:
{ "name" : "hvylas.wav", "license" : "Creative Commons Sampling Plus 1.0 License", "creator" : "inferno", "year" : "2006", "url" : "http://www.freesound.org/samplesViewSingle.php?id=18382", "type" : "sound" }
The name, creator, and type fields are required. The type field should be one of image, sound, music, or code. All other fields are optional, but should be filled in if the information is known.
The game play page on the hark site loads your game in an iframe container. The play page sets the iframe src attribute to the exact url stored in the database for the game. Your game is free to do whatever it needs within the iframe and interpret its URL in any way.
A toolbar appears above, but outside, your game's iframe on the play page. The toolbar has buttons for quitting the game, configuring common preferences (e.g., volume, speech rate), and getting help. The game in the iframe need not be aware of these controls per se, only the events they generate (see next section).
The play page also registers some global hot keys that the game must not mask.
Hark games use dojo.subscribe to listen to events from the game container.
dojo.subscribe('/org/hark/pause', pauseCallback) → token
This invocation registers a callback function that will be notified whenever the user pauses the game to interact with the preferences or other game container controls. Your callback function must have the following signature:
function pauseCallback(paused) → undefined
where the paused parameter indicating if the game is now paused (true) or running (false).
dojo.subscribe('/org/hark/prefs/response', prefsCallback) → token
This invocation registers a callback function that will be notified whenever a user changes one of the preferences in the game container. Your callback function has the following signature:
function prefsCallback(prefs, which) → undefined
The prefs argument receives an object with the following properties:
The which argument receives the string name of the preference that changed or null if the preference that changed is indeterminate.
For example, if the user changes the speechRate using the slider in the preferences or the rate hot keys, the which parameter is speechRate and the game should adjust its audio to respect the new speechRate value on the prefs parameter. When the game publishes a /org/hark/prefs/request event (see below), the which parameter is null and the game should apply all of the values in the prefs object to its audio.
Hark games can also dojo.publish to request information from the game container.
dojo.publish('/org/hark/prefs/request') → token
This invocation sends a request for the current user preferences to the game container. The container responds with a /org/hark/prefs/response callback (see above).
Hark games should use this publish to get the initial preferences when the game first loads.