Emblems

Emblems, first introduced in Halo 2, are small designs that are associated with a Character Profile and used to represent a player's identity in multiplayer games and online play. They consist of a two-colored design or pattern overlaid upon a background (typically a geometric shape), with a user-selected color scheme applied to the result. The feature was later carried on into Halo 3, Halo 3: ODST, and Halo: Reach.

Bungie.net (B.net) similarly displays emblems selected by each player (in-game) and associates them with the player's linked B.net account profile. The site utilizes an emblem generator to produce the image for each unique emblem.

Emblem Generator

Bungie's emblem generator consists of the following base URL and query string:

http://www.bungie.net/Stats/emblem.ashx?s=value&0=value&1=value&2=value&3=value&fi=value&bi=value&fl=value&m=value

Each red "value" represents a value for each of the corresponding query string fields. Each field and value pair represent a specific property of the final rendered emblem image, from a background or foreground of the emblem design to the colors themselves. Below is a table showing the field name and the properties of the emblem that they represent:

Field Name	Emblem Property
s	Dimensions (in pixels)
0	Primary armor color
1	Secondary armor color
2	Primary emblem color
3	Secondary emblem color
fi	Emblem design ("fi" = foreground index)
bi	Background design ("bi" = background index)
fl	Emblem toggle state
m	Specifies which Halo game your emblem is from

Most of the fields should be pretty easy to understand, with a couple of exceptions:

• The "m" field can have a value from 0 to 3. A value of "0" corresponds to Halo 2 emblems, "1" to Halo 3 emblems, "2" to Halo 3: ODST emblems, and "3" to Halo: Reach emblems. Seeing as how this is a Halo: Reach Stats API, the "m" field in the query string must contain a value of "3". In other words, the query string must end with "&m=3".

• The "fl" field (emblem toggle state property) can have a value from 0 to 1. In the current API build, a value of "0" corresponds to the presence of the secondary part of the emblem (toggled on) while a value of "1" corresponds to the absence of this part (toggled off). This is currently the opposite of what the "fl" value represents on B.net ("0" = toggled off and "1" = toggled on). A simple fix is to add 1 to the value obtained by the API (0 -> 1 and 1 -> 2) to switch the "fl" value. In this case, an "fl" value of "2" is treated as "0" so the fix can successfully work.

• The "s" field can have a value from 1 to 120. A value of "1" (min) will represent a 1x1 pixel image, while a value of "120" (max) will make a 120x120 pixel image.

Example URL

The following URL is an example of valid URL for use with the Halo: Reach Stats API:

http://www.bungie.net/Stats/emblem.ashx?s=100&0=16&1=15&2=0&3=28&fi=26&bi=29&fl=0&m=3

Emblem Data Format

The endpoints return the emblem data in the following way: the emblem colors are returned in an array called "change_colors", the emblem toggle state is under "flags", and the emblem design and background design come down under "foreground_index" and "background_index" respectively. The table below shows the mapping:

Field Name	Emblem Property
change_colors[0]	Primary armor color
change_colors[1]	Secondary armor color
change_colors[2]	Primary emblem color
change_colors[3]	Secondary emblem color
foreground_index	Emblem design
background_index	Background design
flags	Emblem toggle state

Examples

The following code implementations take the emblem data and return the full emblem URL.

C#

// Works for either the SOAP or JSON endpoints.
public string GenerateEmblemUrl(ReachEmblem emblem, int size)
{
  return(string.Format(@"http://www.bungie.net/Stats/emblem.ashx?s={0}&0={1}&1={2}&2={3}&3={4}&fi={5}&bi={6}&fl={7}&m=3", 
    size, 
    emblem.change_colors[0], 
    emblem.change_colors[1], 
    emblem.change_colors[2], 
    emblem.change_colors[3], 
    emblem.foreground_index, 
    emblem.background_index, 
    ((emblem.flags == 1) ? 0 : 1)));
}

PHP

// Using JSON Endpoint
function generateEmblem($array, $size){
 $bi = $array['background_index'];
 $fi = $array['foreground_index'];
 $fl = $array['flags'] ? 0 : 1;
 list($c0, $c1, $c2, $c3) = $array['change_colors'];
 
 return "http://www.bungie.net/Stats/emblem.ashx?s=$size&0=$c0&1=$c1&2=$c2&3=$c3&fi=$fi&bi=$bi&fl=$fl&m=3";
}

Two quick ways to fix the flag problem in PHP over using the ternary operation above are:

// Equivalent to the ternary operation $flag = ($flag == 1) ? 0 : 1;.
if ($flag) {
    $flag = 0;
} else {
    $flag = 1;
}

// This operation replaces the string in an already formatted Emblem URL.
$emblem_url = str_replace(array('fl=1', 'fl=0'), array('fl=0', 'fl=1'), $emblem_url);

Color Values and their Hexadecimal Equivalents

Below is a table of the hexadecimal color equivalents of the change_colors color values.

These hexadecimal codes do not hold to be true for change_colors[1] if change_colors[1] and change_colors[3] have identical values.

Value	Color	Hexadecimal	Value	Color	Hexadecimal	Value	Color	Hexadecimal
0		#383838	10		#386D46	20		#8884C4
1		#747474	11		#5A8760	21		#671A1A
2		#D7D7D7	12		#225C59	22		#A7373D
3		#5A4738	13		#337A79	23		#B87F87
4		#796051	14		#6AB8B5	24		#B3572B
5		#A88B7A	15		#344F6C	25		#EC7D42
6		#4A4F38	16		#597292	26		#EBAC88
7		#6C774F	17		#7D9BC0	27		#B1832F
8		#9EAE79	18		#4C4A71	28		#DEC34F
9		#25512E	19		#6C699E	29		#F0EB7B

Indexed Color to Hexidecial Color Code Functions

It is possible to build a function to translate a change_colors value to its corresponding hexadecimal equivalent (for use in customizing display based on player attributes, for example):

C# Function

public string ColorIndexToHexColor(int index)
{
  string colorvalues = "#262626,#727272,#d4d4d4,#584334,#775e4d,#a48778,#464b34,#6a754c,#9aac78,#224d2a,#336b43,#58835f,#205a57,#2f7877,#68b6b3,#304b6a,#57708e,#7c98be,#48466f,#6b679a,#8580c2,#651818,#a33339,#b67d83,#b15529,#e97b40,#e7aa85,#af7e2c,#dac14e,#ece77c";
  string[] colors = colorvalues.Split(',');
 
  if (index >= colors.Length)
  {
    throw new IndexOutOfRangeException("There is no color associated with this index");
  }
 
  return (colors[index]);
}

PHP Function

function parseColor($id) {
	$colors = array("#262626", "#727272", "#d4d4d4", "#584334", "#775e4d", "#a48778", "#464b34", "#6a754c", "#9aac78", "#224d2a", "#336b43", "#58835f", "#205a57", "#2f7877", "#68b6b3", "#304b6a", "#57708e", "#7c98be", "#48466f", "#6b679a", "#8580c2", "#651818", "#a33339", "#b67d83", "#b15529", "#e97b40", "#e7aa85", "#af7e2c", "#dac14e", "#ece77c");
 
	return $colors[$id];
}