Starcraft 2 Rank Badge on Desktop – Geektool

UPDATE: This hasn’t been update to any new standards.

StarCraft is awesome. Growing up I used up so many smoggy summers playing the original release, and after SCII came out I got reattached to it. Further more I actually have a machine with top line graphics and memory, so I can max out the visuals and really enjoy the game for all it’s glory.

Around the same time I got into StarCraft, I also begun fiddling with GeekTools – and thought it would be interesting to write my first Geeklet: display Starcraft ranking badge on desktop.

Starcraft Ranking on Desktop

Download on Github:

> » Download via


  • Mac OSX (Lion, Mavericks, Yosemite)
  • Your StarCraft II character name and ID
  • GeekTools installed (setup to launch on startup)
  • 10-15 minutes

1) Download and Unzip

After unzipping the file, rename the folder from /davidsword-sc2geeklet-#######/ to just /starcraft/ then place the /starcraft/ folder in your home directory. Our working directory will simply be: /starcraft/. Delete the .zip. (We’re going to hide this folder from Finder in the last step, so don’t worry about it being in such an obtrusive location).~

2) Edit The request.php File

Open /starcraft/request.php in a plain text editor, if you don’t have one use but make sure you’re in plain text format, so there’s no nasty encoding. Edit the first few lines to match your information, highlighted below

If you don’t know your $user_ID head over to, log in, and retrive it from the URL as highlighted below. Note: it’s the >6 character profile ID in the URL – not the 3 digit character code listed under your username within the website.

Get BattleNet ID From URL

Then save and close.

3) Add The Request To Geek Tools:

Add Request To Geektools

What we do now is make the request execute/output in a loop with GeekTools. Mac OSX has PHP pre-installed on all it’s machines, so all we’re going to do is create a new SHELL Geeklet to run the .php file via command line.

  • Open up GeekTools
  • Drag a new “Shell” to the desktop, and click on the box made revealing the properties
  • In the inspector/properties under “Command” write: php ~/starcraft/request.php
  • Set it to refresh every hour  by entering 3600

for the refresh rate. (1/hour to not overwhelm the API key, as it’s not mine it’s the original parsers)

  • Play around with the font so it matches your desktop: I recommend Inconsolata or any other monospaced font.

Now this file will executes every hour, retrieving your info and generating your current badge for your chosen bracket.

4) Add image badge to GeekTool

Add Badge to GeekTools

In addition to outputing your stats, The request.php file is saving the output in a .txt file (incase you’re offline) as well as updating a image file named ~/.starcraft/current_rank.png which relates to your current ranking – so we’ll add this image path to a new Geeklet and set the refresh rate to the same interval.

  • Open Geektools again
  • Drag the “Image” Geeklet to the desktop
  • Under image path, write:


where “%your_username%” is replaced with your Mac’s username.

You should now have everything working!

5) Hide the /starcraft/ folder

As a finishing step, we’ll hide our working folder from Finder since everything runs in the background and shouldn’t need changes. Open and the code below. To unhide the folder if updating or moving in the future, use “unhidden” instead of “hidden“.

chflags hidden ~/starcraft/


I’m seeing: “ERROR: unable to fetch your character”

> The API is a little flaky in my opinion, it doesn’t return results for every query. Be sure you’re region is correct (default to “us” – again this info in found when you log into If this issue persists, please contact with your display name and ID.

I’m seeing: “ERROR: Firewall (like Little Snitch) is preventing Geeklet from accessing API”

> This error is triggered when your local machine tries to use PHP’s filegetcontents() function.. this may be because of a firewall on your Mac like Little, or perhaps your PHP has allowurlfopen set to OFF

Why is there an asterisk before my user name?

> This is a simple indicator that the Geeklet was unable to connect to the API, likly from not having an internet connection, or the connecting is block. The geeklet will use the last saved information – or if never loaded before, will show an error.

Of all languages for a desktop tool – why use PHP?

> Because I’m a PHP developer 😉

Change Log

  • 0.1 – July 18th 2013 – Initial Release

Road Map

  • Add support for user portraits

Alpha Support / Acknowledgement

This is a alpha-level project, I haven’t invested too much time into it, and haven’t figured out all the issues to it. If you have any bugs, contributions, screenshots of your desktop, questions, ect – please leave a comment below, or send tweet to @hndsmfx. Please remember this is a alpha project – bugs are expected, please be patient.


  1. Awesome stuff man! It was pretty simple to follow I’m sure it worked once. Gave it a try anyway on ElCap and the shell doesn’t work. Good stuff though!

Leave a Reply

%d bloggers like this: