The ''accountURL'' accepts a hashed user name + password + Battle.net user name and returns "1" if the account was successfully created, "0" if it was not. This query is used to bind a Battle.net account to an account on your web site. Whether you permit multiple Battle.net accounts per league account is up to you. There must only be one instance of each Battle.net account name per league.\n\nSee also [[Queries]].
Once all this is done, you must go through the ''approval process''. Contact Blizzard and provide your [[league.ini]] file, the [[artwork|Artwork]], and the email address for [[game results|Game Results]]. Your [[web site|Web Site]] must also be fully operational. Blizzard will review this material and, when everything is in order, create a signed mopaq file. Blizzard of course reserves the right to require changes to artwork for appropriateness, style, etc. Once you have the signed file, you can begin operating your league by providing the [[league mopaq|League Mopaq]] to your players. \n\nSubmitted artwork should be appropriate for a "Teen" (or equivalent) audience. See the guidelines published by the appropriate game rating boards which correspond to the regions where your players play (e.g. North American [[Entertainment Software Rating Board]], Korean [[Game Rating Board]], etc.). Your artwork must remain consistent with ~StarCraft's look and feel.\n\nWhen all is well, Blizzard will issue you a unique [[League ID]] for your organization, digitally sign your league mopaq, and return it to you. Once signed, this mopaq file cannot be edited. ~StarCraft will not load a modified league mopaq file. If you must make changes, resubmit the modified files to Blizzard, increment your [[league's version number|League Version Number]], and provide the new mopaq to your players.\n\nPlease contact [[sc-tourneyinfo@blizzard.com|mailto:sc-tourneyinfo@blizzard.com]] for more information.
[[League providers|League Provider]] must create five unique pieces of league-specific ''artwork'' in a ~StarCraft compatible format to be displayed in-game: four icons and one background image.\n\n1. A player icon ({{{player.pcx}}}) which is displayed next to a player's name in the Battle.net chat room to indicate that that player is part of the current user's currently selected [[league|League]] and is logged in.\n\n2. A logged-out player icon ({{{loggedout.pcx}}}) which is the same as the player icon, but displayed when the player is not logged in.\n\n3. An admin icon ({{{admin.pcx}}}) which is used identically as the player icon but denotes users who are specially flagged as referees or administrators of that league.\n\n4. A map icon ({{{map.pcx}}}) which is used when displaying a map whose digital signature matches that of the current user's currently selected league.\n\n5. A profile background image ({{{profile.pcx}}}) onto which a user's league statistics will be composited. Because text will be laid over this image, care should be taken to ensure that the center of the image is free of white or light-colored pixels. For an example of this, see the image displayed during Battle.net login. You must ensure that your image is created such that white text laid over it will be readable.\n\nAll artwork must be in [[PCX]] ([[PaintShop Pro]]) format using a [[specific 8-bit palette|Color Table]]. Icons must be 28x14 pixels and the profile background must be 270x200 pixels (width by height). When creating your player icons, keep in mind whether your league wants to display ranking information to the users. Ranking values returned by the [[statQueryURL|StatQueryURL]] are displayed, left-justified and in a yellow-orange color, on the player icons. Your design for the player icon should leave sufficient blank space for this number to appear if you use this feature. Leagues which do not wish to display rankings can use the entire area for art.\n\nFor detailed information on creating artwork for a ~StarCraft league, please see the attached document ''~StarCraftArtCreation.pdf'' and the included example artwork. You may also need the included PhotoShop palette file, ''~StarCraftColorTable.act'' file.
~StarCraft uses a specific 8-bit palettized ''color table''. Any [[artwork|Artwork]] generated for ~StarCraft must adhere to this table -- the colors you use must use the same RGB values, and these ~RGBs must appear at the same indices in the table. Once you've completed your artwork in [[PhotoShop]] (or other program) and need to rectify the palette, see the ~StarCraftColorTable.act file included in the [[LDK|League Development Kit]].
The ''customQueryURL'' is used to provide extensibility. Anywhere in the game users may enter {{{/stats <username>}}} to get stats, they may also enter {{{/league <message>}}} to send a custom message. That string is passed, verbatim, to the customQueryURL which may respond as it sees fit. Implement your own protocol here. The response text will be displayed verbatim to the user, within the limits of the chat system.\n\nSee also [[Queries]].
Each [[league provider's|League Provider]] [[web site|Web Site]] will need a ''database'' to store user names, passwords, the associated Battle.net account name, and that player's statistics. How you store and access your users' accounts and statistics is entirely up to you. However, Blizzard does have some stipulations. First, Battle.net accounts must be tied to no more than one user account in your [[league|League]]. Second, you should strongly, strongly, strongly encourage your players to use an account name different from their Battle.net user name and to never, never, never use the same password. Blizzard has the good fortune of a fairly secure data center. Our league providers might not. We do not want a situation where a compromised league provider site could cost users their Battle.net accounts.\n\nAn extremely minimal database is provided as ~LeagueServer/playerdatabase.txt.
[[League Development Kit]]\n
The ''Entertainment Software Rating Board'' is responsible for assigning ratings to computer games in the United States and Canada. There are other ratings boards in other regions of the world. More information is available at http://www.esrb.org/.
A ''GUID'' is a globally unique identifier. It is a 16-byte value generated randomly. For our purposes one is used to identify the player of a particular game at a particular point in time.
The ''Game Rating Board'' is responsible for assigning ratings to computer games in the Korea. There are other ratings boards in other regions of the world. More information is available from http://www.grb.or.kr/ (Korean) or http://www.grb.or.kr/gita/english.htm (English).
Once a [[league|League]] game is completed, the Battle.net game servers will assemble the official ''game results'', and the [[GUID]]s from each player, and email an XML file to an address specified by your league. You must provider Blizzard with an email address that does not change for the lifetime of your league and you must write code that parses the game results email and uses it to update the statistics of your players. How you do this is entirely up to you.\n\nA game result might look like this:\n\n{{{\n<game program="SEXP" gateway="BLZ" league="WGT" start="Wed, 06 Apr 2005 23:02:55 GMT" elapsed="1170" version="203" ladder="0" players="2">\n <map>Lost Temple</map>\n <player name="Player1" address="111.111.111.111" elapsed="1166" result="Loss" guid="123456789">\n <race>Protoss</race>\n <time>1164</time>\n <score overall="650" units="200" structures="400" resources="50"/>\n <units score="200" produced="4" killed="0" lost="0"/>\n <structures score="400" constructed="1" razed="0" lost="0"/>\n <resources score="50" gas="0" minerals="50" spent="0"/>\n </player>\n <player name="Player2" address="111.111.111.111" elapsed="1170" result="Win" guid="987654321">\n <race>Zerg</race>\n <time>1169</time>\n <score overall="650" units="300" structures="300" resources="50"/>\n <units score="300" produced="5" killed="0" lost="0"/>\n <structures score="300" constructed="1" razed="0" lost="0"/>\n <resources score="50" gas="0" minerals="50" spent="0"/>\n </player>\n</game>\n}}}\n\nNote that the location and actual format of the GUID attribute is under discussion and MAY CHANGE.\n
The ''~InfoQueryURL'' is used to fetch from your web site the current [[version|League Version Number]] and all the other [[query|Queries]] [[URL]]s. This URL cannot change once your mopaq is signed, so choose one which can remain unchanged for the lifetime of your league. An ~InfoQueryURL in the [[league.ini]] file might look like this:\n\n{{{\ninfoQueryURL=http://yourwebsite.org/League/info.php\n}}}\n\nThis query returns a blob of text which contains the name of your league, the [[version|League Version Number]] of your league (see below), and the other queries' [[URL]]s. It might look like this:\n\n{{{\nname=Example ~StarCraft League\nversion=1\naccountURL=http://yourwebsite.org/League/newaccount.php?hash=%s\nlogonURL=http://yourwebsite.org/League/login.php?hash=%s\nlogoutURL=http://yourwebsite.org/League/logout.php?hash=%s\nstatQueryURL=http://yourwebsite.org/League/playerstats.php?players=%s\ncustomQueryURL=http://yourwebsite.org/League/custom.php?query=%s\nreplayUploadURL=http://yourwebsite.org/League/sendresult.php\n}}}\n\nThe ~URLs should look like {{{sprintf()}}} masks -- actually they are. The "%s"s will be replaced by ~StarCraft to form the queries. This gives you more latitude in the construction of your forms. We've used [[PHP]] for these examples, but you could use any technology. Note that you can use any URL, any page, and any file names you like, so long as the correct number of string replacements occurs and in the same order.\n\nSee also [[Queries]].
A ~StarCraft ''league'' is a 3rd-party operated, but officially sanctioned organization which operates a system for tracking the wins, losses, and statistics of a group of ~StarCraft players. Each ~StarCraft player can sign up for as many leagues as he or she wishes, or none at all. Each league tracks stats for players in games with only other players from the same league. For these players, it tracks wins, losses, and disconnections only while playing that league's games with other players in that league. These ''statistics'' will be viewable on the player's profile page, just as the Battle.net stats are when not logged in. Leagues can also rank their players and provided that information back to ~StarCraft as a one- to four-digit numbers. If this number is returned in a stats query, then it is displayed on the player's icon in the chat room. Leagues are responsible for updating their players' stats within a reasonable time after each game.
Players must be able to create a ''league account'' on your [[web site|Web Site]]. Account names must be between 1 and 30 characters in length. Passwords must be between 6 and 20 characters in length. Using ~StarCraft, players will associate a Battle.net account with this league account. You must be able to flag a league accounts as a [[referee|Referee]].
All materials (C) Copyright 1997-2007 Blizzard Entertainment, Inc.\n\nThe ~StarCraft ''League Development Kit'' (LDK) is a set of tools and documentation to instruct third-party [[league providers|League Provider]] (that's you) to create and operate a sanctioned ~StarCraft [[league|League]]. In this document you'll find the information necessary to create your league web site, database, submit a league to Blizzard for approval, and operate your league on a daily basis.\n\n''Documentation Format''\nThis documentation is presented to you as a single-file wiki using [[TiddlyWiki]]. Like a typical, server-based wiki (e.g. [[Wikipedia|http://en.wikipedia.org/]]), clicking on hyperlinks takes you to additional information about that topic. Hover your mouse cursor over a topic (a "tiddler") to see the menu above where you can close topics. There is also a search field in the upper right.\n\n''Getting Started''\nLet's get started. A league provider wishing to operate their own ~StarCraft league needs to complete the following steps:\n# Read this documentation\n# Create a [[database|Database]] to track your players' accounts, passwords, and statistics\n# Create a [[web site|Web Site]] which responds to the required [[queries|Queries]]\n# Create the necessary [[artwork|Artwork]]\n# Provide to [[Blizzard]] the information to create and [[approve|Approval Process]] a [[league mopaq|League Mopaq]]\n# Distribute that signed league mopaq (plus any signed [[league maps|League Map]]) to their players\n\n''How it Works''\nOnce the league mopaq is installed on a user's computer, ~StarCraft will offer that user the ability to log into the league web site, play games, and have reliable statistics and game replays uploaded to the league's web site. Other users in game can see these stats, much as the old, official ladder worked. Players will see your icons in-game, will be able to query your players' stats in-game, and will have their own automatically created chat channels.\n\n''League Development Kit contents'':\n* ~LeagueFlowchart.pdf -- sequential description of user experience\n* ~BattleNetChat.png -- shot of new league button in Battle.net chat screen\n* ~LeagueSelection.png -- shot of league screen with an installed league mopaq\n* ~LeagueCreateAccount.png -- shot of league account creation screen\n* ~LeagueFolderStructure.png -- folder structure for storing league mopaqs\n* ~StarCraftArtCreation.pdf -- how to create [[artwork|Artwork]] for ~StarCraft\n* ~StarCraftColorTable.act -- [[PhotoShop]] [[color table|Color Table]] for ~StarCraft\n* ~LeagueMopaq/league.ini -- example [[league.ini]] file describing a league\n* ~LeagueMopaq/admin.pcx -- example icon for registered league [[Referee]]s\n* ~LeagueMopaq/player.pcx -- example icon for registered, logged in league players\n* ~LeagueMopaq/loggedout.pcx -- example icon for registered, logged out league players\n* ~LeagueMopaq/map.pcx -- example icon for digitally signed maps for this league\n* ~LeagueMopaq/profile.pcx -- example art displayed behind player statistics\n* ~LeagueServer/*.php -- minimalist league server implementation in [[PHP]]\n* ~LeagueServer/playerdatabase.txt -- minimalist league player [[database|Database]]\n\n
Each [[league|League]] will have its own unique ''league ID'' assigned by Blizzard. This ID is specified in the [[league.ini]] file on as the {{{id=}}} line. Once assigned, league ~IDs cannot change.
a ''league mopaq'' is the file containing the information which defines your [[league|League]]. This file's contents are assembled by the [[league provider|League Provider]], sent to [[Blizzard]] for [[approval|Approval Process]], signed, and then the file is provided to players. Players must have league X's league mopaq to play in league X.\n\n''Contents''\nA mopaq file is like a ZIP file in that it contains others. The file in a league mopaq are as follows. See the specific file's topic for instructions on creating it.\n* [[league.ini]]\n* [[player.pcx|Artwork]]\n* [[loggedout.pcx|Artwork]]\n* [[admin.pcx|Artwork]]\n* [[map.pcx|Artwork]]\n* [[profile.pcx|Artwork]]\n\n''Location''\nOnce the file is created, signed, and ready to go, you must provide it to players and players must install it. Installation works very much like //World of Warcraft//'s addons. Within the ~StarCraft directory there is a ''leagues'' folder. Within that, create a folder for your league, and within that place the league mopaq. The folder name and league mopaq name must be the same (except for the .MPQ extension). So if you are running the "Starbowl" league your users would need:\n\n{{{\nStarcraft\n leagues\n Starbowl\n Starbowl.MPQ\n}}}\n\nWhether your instruct them to do this or write an installer is entirely up to you.
The ''league provider'' is //you//. The people creating and operating the [[League]].
''League version numbers'' are used by [[league provider|League Providers]] to invalidate existing versions of their [[league mopaqs|League Mopaq]]. Version numbers of the same league are incompatible with previous versions. ~StarCraft will check the league version specified in the league mopaq against the number reported by the [[InfoQueryURL]]. If they do not match, the user is notified to get the correct version of the mopaq. League providers cannot operate two versions of the same league at the same time. Users cannot join leagues while using an out-of-date league mopaq. This feature may be used to force users to update their league mopaqs, when it is necessary to change [[URL]]s, icons, or artwork.
The ''logonURL'' query also accepts a hashed league user name + password + Battle.net user name and returns "1" if the hash matches an entry within your database, "0" if it does not. We're working to ensure that this particular query is relatively secure and of the technology described in this preview, this is the most likely to change before release.\n\nWhen the client selects a league, enters the corresponding account and password, and clicks login, the client will issue a HTTP GET request like the following. The Battle.net account name is sent in clear text, and the league login/password is hashed using an algorithm TBD, probably a salted [[SHA1]].\n\nYou may specify the structure of this URL in your [[InfoQueryURL]] response. It might look like this:\n{{{\nhttp://yourleague.org/login.php?hash=HASHEDNAMEANDPASSWORDbattlenetname\n}}}\nSee also [[Queries]].\n\n
The ''logoutURL'' query is sent by the game when the player logs out of the league or of Battle.net. It accepts a hashed league user name + password + Battle.net user name and it returns nothing to the user.\n\nYou may specify the structure of this URL in your [[InfoQueryURL]] response. It might look like this, though:\n{{{\nhttp://yourleague.org/logout.php?hash=HASHEDNAMEANDPASSWORDbattlenetname\n}}}\n\nSee also [[Queries]].
[[Home|League Development Kit]]\n[[Database]]\n[[Web Site]]\n[[Queries]]\n[[Artwork]]\n[[Approval|Approval Process]]\n[[Maintenance]]
Now your league is out there, people are playing, and things are going well. Trouble is, you need to change something.\n\n''Q'': Our query ~URLs need to change.\n''A'': You can do this on your own. Just change your [[infoQueryURL|InfoQueryURL]] response to point to the new queries.\n\n''Q'': Our site URL needs to change for hosting reasons or our logo changed and we need to update the artwork. \n''A'': Your users will need a new, signed league mopaq. Contact Blizzard and provide the new files. Blizzard will again review these, sign them, and provide them back to you. Once you have them in hand, change your infoQuery response to increment your league's version. When your players log in, ~StarCraft will then inform them their league mopaq is out of date and they need to contact you for a new one -- which you now have. Once they get this, they'll have the new URL or artwork.\n\n''Q'': We want to restart our league with fresh stats.\n''A'': Okay. Just purge your stats database. Easy! Blizzard doesn't even need to be involved.\n\n''Q'': How can players uninstall a league?\n''A'': Just remove the [[league mopaq|League Mopaq]] file. See [[Uninstall]].
''PCX'' is an antiquated, 8-bit per pixel, RLE image format used by [[PaintShop Pro]] and ~StarCraft. All artwork for ~StarCraft must be in this format and adhere to the correct [[color table|Color Table]].
''PHP'' is a programming language commonly used for coding web pages. More information is available from http://www.php.net/.
~PaintShop Pro was a very popular graphics editor suite back in the early 90s. Its ~RLE-compressed 8-bit per pixel image format, [[PCX]], was used by ~StarCraft for all internal art resources. Though ~PaintShop Pro is no longer available or used, most modern professional image editing tools support this format, including Adobe [[PhotoShop]] and the GNU Image Manupulation Program ([[The GIMP]]).
''PhotoShop'' is a commercial image manipulation program which supports the [[PCX]] image format. More information is available from http://www.adobe.com/products/photoshop/.
The [[league provider|League Provider]]'s [[web site|Web Site]] must implement responses to several ''queries'' to, for example, log in, request statistics, or upload a replay file. These are submitted to the site via HTTP GET and POST. Using HTTP to implement the protocol between ~StarCraft and the league allow for rapid development among league providers who may not have hard-core programmers available. It also offers the ability to use a wide range of technology to implement the league provider's side.\n\nThe queries you must implement are:\n* [[InfoQueryURL]]\n* [[AccountURL]]\n* [[LogonURL]]\n* [[LogoutURL]]\n* [[StatQueryURL]]\n* [[CustomQueryURL]]\n* [[ReplayUploadURL]]
The ''replayUploadURL'' is used to send an HTTP POST request which includes the league game replay (.REP) file. These files are typically between 100 and 250 ~KiB in size, and your site will receive one copy from each player in each league game directly from the user.What you do with these replay files is entirely up to you. We suggest that they may be useful in detecting hackers and mediating disputes among your players. Each POST will also include a couple of additional parameters:\n* hash - The same login/password hash used in the [[LogonURL]] when logging into the league\n* gameResult - an XML formatted string containing game result information, including winners/losers, player names, map name, race, and scores.\n\nSee also [[Queries]].
''SHA1'' is an algorithm used to encrypt or hash a stream of bytes to create an essentially unique, 160-bit number. For our purposes, this algorithm is used to create a one-way hash of players' user names and passwords.\n\n* [[PHP]]: There is a free implementation at http://us3.php.net/sha1.\n* [[Ruby|http://www.ruby-lang.org/]]: Use the built-in {{{Digest::SHA1}}} module\n* [[C#|http://msdn.microsoft.com/vcsharp/]]: Use the built-in {{{System.Security.Cryptography.SHA1}}} class.\n* [[Java|http://java.sun.com/]]: Use the free security extension at http://java.sun.com/products/jce/jce122_providers.htm
version 0.9.2 (19 April 2007)
~StarCraft League Development Kit
The ''statQueryURL'' is used when ~StarCraft needs to generate a profile image like the one shown at Battle.net login, but using your custom profile background image and that user's [[league|League]] stats. It is also used to fetch the stats of other league players in the current chat room. This query must accept one or multiple Battle.net user names and return stats for each. Names are escaped for HTTP and separated with a comma character. There may be as many as forty player names in each query. Stats should come back in the following format. If there were multiple user names in the request, separate their stats with a '\sn' character. \n\n{{{\n<username>-<wins>-<losses>-<disconnects>-<ranking>\n}}}\n\nSee also [[Queries]].
''The GIMP'' is an open-source image manipulation program which supports the [[PCX]] format. More information is available from http://www.gimp.org/.
This documentation was written with ''~TiddlyWiki''. More information is available at http://www.tiddlywiki.com/.
Acronym for Universal Resource Locators. These are strings often of the form:\n{{{\nhttp://some.host.name/some/file/name.html\n}}}
''~UTF-8'' is a Unicode text format which supports variable-length encoding for glyphs of all languages. More information is available at http://en.wikipedia.org/wiki/UTF-8.
Users may wish to ''uninstall'' a [[league mopaq|League Mopaq]]. They only need to delete the folder containing the league mopaq.
Each [[league provider|League Provider]] must implement a ''web site''. At a minimum, that web site must implement responses to a number of HTTP [[queries|Queries]], allow users to create [[league accounts|League Account]] with passwords, provide downloads for their league's [[league mopaq|League Mopaq]], and a [[database|Database]] to store names, passwords, and statistics. How you implement your web site and what technology(-ies) you use are entirely up to you, so long as you meet the requirements specified in the [[LDK|League Development Kit]].
The league.ini file is part of the [[League Mopaq]] provided to users. It contains the name of the league, its [[League ID]], the [[league version number|League Version Number]], the [[chat channel prefix|Chat Channel Prefix]], the URL for human visitors, and the [[InfoQueryURL]] which the game will use to determine all the other query strings. This file is stored in the League Mopaq and digitally signed to ensure it cannot be altered and remain valid.\n\nHere's an example league.ini file. Keys are case-insensitive. Lines beginning with a '#' are ignored. The file format is UTF-8.\n\n<<<\nname=Star Bowl\nid=1\nversion=1\nchatPrefix=SB\nmainURL=http://starbowl.org/\ninfoQueryURL=http://starbowl.org/League/info.php\nuploadFailure="Your replay upload failed. Please visit our web site to upload it manually."\n<<<