BN# Developer Guide

Note: This documentation was retrieved from an archive of the JinxBot source files. The original site where this information was hosted is no longer available. The instruction is up to date for the release of BNSharp.dll available on this site, however BNSharp is no longer compatible with StarCraft. In order to use BN# you will need to modify the instruction code to instead use Diablo 2 or WarCraft 3.

BN# is designed so that developers can quickly use it to create a functioning binary client for Battle.net. (A binary client is one that connects using a binary protocol instead of the out-of-date CHAT protocol). It does so by providing a neatly-packaged programming library that makes the process relatively straightforward, hiding most of the mundane details from the programmer.

Please note: in order to complete this tutorial, you will need a basic understanding of the C# or Visual Basic .NET programming languages, and already have a development environment, such as Visual Studio, Visual C# Express, or #develop configured. It will familiarize you with the concepts of programming BN# and will present a rudimentary console-based client.

Although BN# is developed so that it is compatible with the Microsoft .NET Framework 2.0, this sample uses C# 3.0-only features only found in the .NET Framework 3.5 compiler.

How to: Develop a Battle.net Client in 10 Minutes

  1. Create a new Console Application project.
  2. Right-click on the References folder, and choose “Add Reference…”. In the “Browse” tab, navigate to the directory where you have unzipped BNSharp.dll. Choose BNSharp.dll.
  3. Implement the IBattleNetSettings interface. To do so, right-click on your project and choose “Add Class”, and call it ClientSettings. 
    using System;
using System.Collections.Generic;
using System.Text;
using BNSharp;
using BNSharp.BattleNet;


namespace BnsDemoClient
{
    class ClientSettings : IBattleNetSettings
    {
        #region IBattleNetSettings Members

        public string CdKey1
        {
            get;
            set;
        }

        public string CdKey2
        {
            get;
            set;
        }

        public string CdKeyOwner
        {
            get { return "BNSharp"; }
            set { }
        }

        public string Client
        {
            get { return Product.StarcraftRetail.ProductCode; }
            set { }
        }

        public string GameExe
        {
            get { return @"c:\GameFiles\STAR\Starcraft.exe"; }
            set { }
        }

        public string GameFile2
        {
            get { return @"c:\GameFiles\STAR\storm.dll"; }
            set { }
        }

        public string GameFile3
        {
            get { return @"c:\GameFiles\STAR\battle.snp"; }
            set { }
        }

        public string HomeChannel
        {
            get;
            set;
        }

        public string ImageFile
        {
            get { return @"c:\GameFiles\STAR\star.bin"; }
            set { }
        }

        public string Password
        {
            get;
            set;
        }

        public BNSharp.BattleNet.PingType PingMethod
        {
            get { return PingType.Normal; }
            set { }
        }

        public int Port
        {
            get { return 6112; }
            set { }
        }

        public string Server
        {
            get { return "useast.battle.net"; }
            set { }
        }

        public string Username
        {
            get;
            set;
        }

        public int VersionByte
        {
            get { return 0xd1; }
            set { }
        }

        #endregion
    }
}

    This code assumes that you have located the revision check files in a folder called c:\GameFiles\STAR.

    This code does not automatically create an account, and it only connects to US East. There are a number of additions that could be easily added to someone willing to put in the work.

  4. Create the client. Within the code’s entry point, you’ll need to prompt the user for information required to connect, such as CD key, account name, and password. 
    static void Main(string[] args)
{
      string userName, password, key;
      Console.WriteLine("Specify username: ");
      userName = Console.ReadLine();
      Console.WriteLine("Specify password: ");
      password = Console.ReadLine();
      Console.WriteLine("Specify CD key for Starcraft:");
      key = Console.ReadLine();

      ClientSettings settings = new ClientSettings
      {
           CdKey1 = key,
           Username = userName,
           Password = password
      };

      BattleNetClient client = new BattleNetClient(settings);
}
  5. Wire up event handlers. You can add event handlers inline, and they can be more elaborate than shown here. But here are sample event handlers, that can be added immediately after you declare the client: 
    client.Connected += delegate
{
       Console.WriteLine("Connected.");
};
client.EnteredChat += delegate(object sender, EnteredChatEventArgs e)
{
      Console.WriteLine("Entered chat as {0}", e.UniqueUsername);
};
client.JoinedChannel += delegate(object sender, ServerChatEventArgs e)
{
      Console.WriteLine("Joined Channel: {0}", e.Text);
};
client.UserJoined += delegate(object sender, UserEventArgs e)
{
      Console.WriteLine("User Joined: {0} ({1})", e.User.Username, e.User.Stats.Product.Name);
};
client.UserLeft += delegate(object sender, UserEventArgs e)
{
      Console.WriteLine("User left: {0}", e.User.Username);
};
client.UserShown += delegate(object sender, UserEventArgs e)
{
      Console.WriteLine("User Joined: {0} ({1})", e.User.Username, e.User.Stats.Product.Name);
};
client.UserSpoke += delegate(object sender, ChatMessageEventArgs e)
{
      Console.WriteLine("<{0}>: {1}", e.Username, e.Text);
};
client.UserEmoted += delegate(object sender, ChatMessageEventArgs e)
{
      Console.WriteLine("<{0} {1}>", e.Username, e.Text);
};
client.WhisperSent += delegate(object sender, ChatMessageEventArgs e)
{
      Console.WriteLine("You whisper to {0}: {1}", e.Username, e.Text);
};
client.WhisperReceived += delegate(object sender, ChatMessageEventArgs e)
{
      Console.WriteLine("{0} whispers: {1}", e.Username, e.Text);
};
client.LoginFailed += delegate(object sender, LoginFailedEventArgs e)
{
      Console.WriteLine("Login failed: {0}", e.Reason);
};
  6. Create the chat loop. This loop will keep the program running, waiting for user input, until the user types /quit and presses enter. It also will handle delaying connection until the user is ready, and will wait until the user presses enter before quitting entirely: 
    Console.WriteLine("Press <enter> to connect or Ctrl+C to quit.");
Console.ReadLine();

client.Connect();

string input = null;
do
{
       input = Console.ReadLine();
       if (input != "/quit")
            client.SendMessage(input);
} while (input != "/quit");

client.Close();
Console.WriteLine("Disconnected.  Press <enter> to quit.");
Console.ReadLine();
  7. You’re finished! Press F5 to build and run; assuming you don’t have any typing errors, you should be able to run immediately.

    Entered chat as DarkTemplar~AoA
    Joined Channel: StarCraft USA-1
    User Joined: mclarenf1 (Starcraft (Retail))
    User Joined: JESUS_is_LORD (Starcraft (Retail))
    User Joined: destroyer-x1 (Starcraft (Retail))
    User Joined: pnut (Starcraft (Retail))
    User Joined: dravenxx (Starcraft (Retail))
    User Joined: Suspect45 (Starcraft (Retail))
    User Joined: IAMAHAZARD (Starcraft (Retail))
    User Joined: bh12345 (Starcraft (Retail))
    User Joined: Olgarn (Starcraft (Retail))
    User Joined: T.J.T.E.R.R.A.N (Starcraft (Retail))
    User Joined: chaneyy (Starcraft (Retail))
    User Joined: lukeduke152 (Starcraft (Retail))
    User Joined: 843ilikeeggs (Starcraft (Retail))
    User Joined: MagicMurder (Starcraft (Retail))
    User Joined: DDKush (Starcraft (Retail))
    User Joined: CLAW(GG) (Starcraft (Retail))
    User Joined: soccerballa77 (Starcraft (Retail))
    User Joined: HRZ1 (Starcraft (Retail))
    User Joined: sbatten2 (Starcraft (Retail))
    User Joined: HandofArtanis (Starcraft (Retail))
    User Joined: ulostme[fun] (Starcraft (Retail))
    User Joined: ModdedLawnMower (Starcraft (Retail))
    User Joined: tyler_howe (Starcraft (Retail))
    User Joined: RODIMUS (Starcraft (Retail))
    User Joined: sidler (Starcraft (Retail))
    User Joined: staal18 (Starcraft (Retail))
    User Joined: m3driven (Starcraft (Retail))
    User Joined: devinlacross (Starcraft (Retail))
    User Joined: hbsblows (Starcraft (Retail))
    User Joined: Dazzler007 (Starcraft (Retail))
    User Joined: nano0 (Starcraft (Retail))
    User Joined: Robomarine (Starcraft (Retail))
    Hi everyone
    User Joined: fkuc (Starcraft (Retail))
    User Joined: E3S (Starcraft (Retail))
    User Joined: ShRoOmS_NukkA (Starcraft (Retail))
    User Joined: rushrushrush2 (Starcraft (Retail))
    User Joined: ChaosDivElite (Starcraft (Retail))
    User Joined: DarkTemplar~AoA (Starcraft (Retail))
    User Joined: dirkacat (Starcraft (Retail))
    User left: E3S <ulostme[fun]>: go to clan op xfun-
    User Joined: dimwitt (Starcraft (Retail))
    User left: m3driven
    User left: fkuc <ulostme[fun]>: on west
    User Joined: ogima (Starcraft (Retail))
    User left: tyler_howe
    User Joined: E3S (Starcraft (Retail))
    User Joined: m3driven (Starcraft (Retail)) <ulostme[fun]>: hi
    User left: Robomarine
    User Joined: fkuc (Starcraft (Retail))
    User left: hbsblows
    /quit
    Disconnected. Press to quit.</ulostme[fun]></ulostme[fun]></ulostme[fun]>