Configuration Guide

Rafał Niewiński edited this page May 25, 2016 · 25 revisions

This guide will help you configuring your instance of SteamBot through the settings.json file. This file is located in the same place as the SteamBot.exe executable. A file named settings-template.json is available to use as a go-by.

Build SteamBot

See the Installation Guide for details on building the SteamBot project.

Configure the Bot

In order to run SteamBot you need to configure your bots properties. This is done by creating a settings.json file located in the same place as the SteamBot executable or by renaming the settings-template.json.

The settings file is formatted using JavaScript Object Notation (JSON) and must adhere to the syntactic structure of the language. Therefore it is advised to base your configuration off of the provided template file.

Here is a copy of the template file. This guide will describe each configuration option in the following sections.

{
"Admins":["234567"],
"ApiKey":"Steam API Key goes here!",
"mainLog": "syslog.log",
"UseSeparateProcesses": "false",
"AutoStartAllBots": "true",
"Bots": [
        {
            "Username":"BOT USERNAME",
            "Password":"BOT PASSWORD",
            "ApiKey":"Bot specific apiKey",
            "DisplayName":"TestBot",
            "ChatResponse":"Hi there bro",
            "logFile": "TestBot.log",
            "BotControlClass": "SteamBot.SimpleUserHandler",
            "MaximumTradeTime":180,
            "MaximumActionGap":30,
            "DisplayNamePrefix":"[AutomatedBot] ",
            "TradePollingInterval":800,
            "TradeOfferPollingIntervalSecs":30,
            "ConsoleLogLevel":"Success",
            "FileLogLevel":"Info",
            "AutoStart": "true",
            "SchemaLang":"en"
        }
    ]
}

Main Configuration Options

These configuration options are global to the entire SteamBot application as opposed to the per-bot options in the next section.

Admins: An array of Steam Profile IDs (64 bit IDs) of the users that are an Admin of your bot(s). Each Profile ID should be a string in quotes and separated by a comma. These admins are global to all bots listed in the Bots array.

ApiKey: The API key you have been assigned by Valve. If you do not have one, it can be requested from Valve at their Web API Key page. This is required and the bot(s) will not work without an API Key. The API Key should be a string in quotes.

mainLog: The log containing runtime information for all bots. This is independent of the logs for each Bot.

UseSeparateProcesses: Determines whether or not bot manager opens each bot in its own process. Default is false.

AutoStartAllBots: If set to true, all of the configured bots in the Bots array will be started when the program starts. If set to false the embedded per-bot option will dictate whether the bot will be started.

Bot Configuration Array

The Bots object is an array of JSON objects containing information about each individual bot you will be running. You can run multiple bots at the same time by having multiple elements in the Bots array. Each bot object must be separated by a comma.

Each entry in the Bots array consists of the following string-values pairs:

  • Username: REQUIRED The Steam user name for this bot. It should be a string in quotes.

  • Password: REQUIRED The password for the Steam user associated with this bot. It should be a string in quotes.

  • ApiKey: REQUIRED for trade offers Specific API key that is registered to this particular account. If not set, the bot will use the global API key.

  • DisplayName: REQUIRED The name the bot will present on Steam. It should be a string in quotes.

  • ChatResponse: REQUIRED This is the response the bot will provide when a user chats with it via Steam Friends. It should be a string in quotes.

  • logFile: REQUIRED The log file for this specific bot. It should be a string in quotes. This file must be unique for each bot.

  • BotControlClass: REQUIRED The fully qualified class name that controls how this specific bot will behave. It must be the fully qualified class (ie. SteamBot.SimpleUserHandler`). Generally, this type is in a separate file like SimpleUserHandler.cs. It should be a string in quotes.

    Currently the SteamBot provides two default classes that can be used as a bot control class, SteamBot.SimpleUserHandler and SteamBot.AdminUserHandler. These classes can be extended or used as a basis for creating a new user handler class. See the next section for details on creating User Handlers.

  • Admins: Additional admins, specific to this bot. 64-bit Steam IDs (optional)

  • MaximumTradeTime: Maximum length of time for a trade session (in seconds). It should be a numeric value. Defaults to 180 seconds. (optional)

  • MaximumActionGap: Length of time the bot will allow the user to remain inactive. It should be a numeric value. Defaults to 30 seconds. (optional)

  • DisplayNamePrefix: A prefix to display in front of the DisplayName. It should be a string enclosed by quotes. Defaults to an empty string. (optional)

  • TradePollingInterval: Length of time, in milliseconds, between polling events. Higher values reduce CPU usage at the cost of a slower trading session. It should be a numeric value. Default is 800 ms. Lowest value is 100 ms. (optional)

  • TradeOfferPollingIntervalSecs: Length of time, in seconds, between polling active trade offers for bot Steam Account. Higher values reduce count of API calls to Steam at the cost of a higher trade offers waiting time. Default is 30 s. We do not recommend values lower than 5 s. (optional)

  • ConsoleLogLevel: Detail level of bot's console log. In order from most verbose to least verbose, valid options are:

    • Debug: Information that is helpful in performing diagnostics.
    • Info: Generally useful information such as start/stop, polling events, etc. (default)
    • Success: Events that have completed in an expected manner.
    • Warn: Potential application problems, but which have been automatically handled.
    • Error: Event that prevents the bot from continuing to function without corrective action.
    • Interface: Events that require user interaction, such as entering a Steam Guard code to complete a login.
    • Nothing: A log level that suppresses all previous levels. (not recommended)
  • FileLogLevel: Same as ConsoleLogLevel but for the file log.

  • AutoStart: When the above AutoStartAllBots is false this can be set to true to make this individual bot start. This value is not required and will default to true when not present.

  • SchemaLang: Schema language used by the bot. If not set, schema language will be generic.

Full Customization With UserHandlers

You can edit the files SimpleUserHandler.cs or AdminUserHandler.cs as they contain examples of most everything you need to fully customize your bot. Alternatively, you can create a new user handler to control bot behavior.

To create a custom User Handler you are going to create a class that inherits from SteamBot.UserHandler. UserHandler is an abstract base class that provides several methods that must be overridden in order to work. When you override them in your custom class you can provide any implementation you want in order to fully customize your bot's responses to trades, responses to chat messages, item validation, etc.

The UserHandler methods are mostly reactionary in nature, i.e. what to do when the bot has been proposed a trade or sent a message. These methods are explained in UserHandler.cs code comments but here is a basic run-down of what's available to your subclass if you decide to do this:

If you create your own handler, remember to modify the BotControlClass setting in your configuration.

If you are importing a preexisting handler, it needs to be added to the same project as the SimpleUserHandler.cs or AdminUserHandler.cs files (by default, this is ExampleBot). To add an item to the existing project, follow these directions when using Visual Studio. Once its added, rebuild the source and the preexisting handler should be available to use in your SteamBot.

Note: This repository is for SteamBot and not custom handlers. If you are using one of the example handlers available in other repositories and have issues you will need to file support requests on those repositories.

Inherited Properties

The following are some variables and properties that are inherited from UserHandler.cs and are available to you when you subclass your custom user handler. See the source for more information.

UserHandler.IsAdmin

Returns true if the other user interacting with the bot is one of the configured Admins. See settings.json format above.

UserHandler.Log

The Log class for the Bot that you can use this to output important information to the console you see on the screen.

UserHandler.Bot

The Bot instance for the bot the user handler is running for. You can use this to access some advanced features of the Bot like the Steam Friends system and the Trade system below.

  • UserHandler.Bot.SteamFriends.SendChatMessage(SteamID target, EChatEntryType type, string message): Send a chat message to the specified user (by profile id).
  • UserHandler.Bot.SteamFriends.AddFriend(SteamID steamId): Add a friend (by profile id).
  • UserHandler.Bot.SteamFriends.RemoveFriend(SteamID steamId): Remove a friend (by profile id).

Trade Support

Most of the trade interaction will occur through the abstract methods that you will have to implement as a subclass. These are mostly Trade events that happened outside of the Bot. For example OnTradeAddItem is called when the other user adds an item to the trade window. In this function your class could add equal, lesser, or greater value items (or send the user a nasty message about low-balling). To do this you will have to interact with the trade via the UserHandler.Trade object described below.

  • UserHandler.Trade.AddItem(ulong itemid) Add an item by its id property into the next available slot in the trade window.
  • UserHandler.Trade.AddItemByDefindex(int defindex) Same as AddItem, but you specify the defindex of the item instead of the id.
  • UserHandler.Trade.RemoveItem(ulong itemid) Removes the specified item from the trade window.
  • UserHandler.Trade.SetReady(bool ready) Sets the trade ready-status depending on the ready parameter. true to set the bot's status to ready.
  • UserHandler.Trade.AcceptTrade() Calling this method accepts the trade. It's the second step after both parties ready-up.
  • UserHandler.Trade.SendMessage(string msg) Sends a message to the other user over trade chat.

Methods to Override

These abstract methods need to be overridden in your customized UserHandler. They are called when certain events occur.

  • OnGroupAdd: Called when the bot is invited to a Steam group. SHOULD RETURN bool: Whether to accept.
  • OnChatRoomMessage: Called when a chat room message is sent in a group chat.
  • OnFriendAdd: Called when the user adds the bot as a friend. SHOULD RETURN bool: Whether to accept.
  • OnFriendRemove: Called when the user removes the bot as a friend.
  • OnLoginCompleted: Called when the bot finishes logging into the Steam network.
  • OnMessage: Called when a message is received via Steam Chat.
  • OnTradeOfferUpdated: Called when a trade offer is updated, including the first time it is seen. WARN: When the bot is restarted, this might get called again for trade offers it's been previously called on.
  • OnTradeRequest: Called when a user sends the bot a trade request.
  • OnTradeError: Called if an error occurs during trading.
  • OnTradeTimeout: Called if MaximumTradeTime or MaximumActionGap is exceeded.
  • OnTradeAwaitingConfirmation: Called when created trade waits for additional confirmation.
  • OnTradeInit: Called when a trade is initiated (occurs after OnTradeRequest).
  • OnTradeAddItem: Called when an item is added to the trade.
  • OnTradeRemoveItem: Called when an item is removed from the trade.
  • OnTradeMessage: Called when a message is received in Trade Chat (not to be confused with OnMessage, which is for Steam Chat).
  • OnTradeReady: Called when user changes their Ready Status.
  • OnTradeAccept: Called when the user accepts the trade.

Methods you CAN Override

These virtual methods can to be overridden in your customized UserHandler. They are called when certain events occur.

  • OnChatRoomMessage: Called when a chat message is sent in a chatroom.
  • OnBotCommand: Called when an 'exec' command is given via botmanager.
  • OnTradeRequestReply: Called when user accepts or denies bot's trade request.
  • OnTradeClose: Called when user close active trade.