TradeWars Blog

TradeWars Blog

  • Category Archives Development
  • Working with Botlink Objects

    The core of Botlink is a set of objects that provide an interface to game data.  This includes not only data fields, but also methods to perform common functions.  Botlink provides an object for each of the data files used by the game, including the sector data, user data, ship data, etc.  In addition, there are many objects that represent categories of functionality, like the IO object.


    The list of objects currently supported by Botlink includes

    GAME – All game configuration settings commonly found in the TEDIT general editors, plus many general functions.  Current functions include createPlayer, createShip, createPlanet, createPort, createAlien, createCorp, plotCourse, showWarps and postEvent.

    USER – Player account data.  Current functions are Deactivate, Kill, Move, LandOnPlanet, LeavePlanet, LandOnPort, LeavePort and Transport.

    SHIP – Player ship data.  Current functions are Deactivate, Kill, Move and Claim.

    SECTOR – Game sector data.  Current functions are Claim, SetFighters, SetArmidMines, SetLimpetMines, ClearPort, PhotonWave and LockWarps.

    PORT – Trade port data.  Current functions are Deactivate, Kill and Move.

    PLANET – Planet data.  Current functions are Deactivate, Kill, Move and Claim.

    CORP – Corporation data.  The only function is Deactivate.

    ALIEN – Gold alien data.  Current functions are Deactivate, Kill, Move, LandOnPlanet, LeavePlanet, LandOnPort and LeavePort.

    ALIENCLASS – Gold alien race definitions.  No functions are yet defined for this object.

    BOSS – Data for the Feds, Pirates and other custom Boss characters.  Only the Move function is defined for this object.

    FACTION – Data defining the Federation, Pirate Syndicate and other custom Boss factions.  Current functions are addLongOath, delLongOath, addShortOath and delShortOath.

    TERRA – A special planet object that is associated with planet 1, Terra.  Through the static Terra record alias, special Terra-only fields can be accessed.  Only the Move and Claim functions are supported for Terra.

    CLASS0 – A special port object that is associated with the class zero ports.  Through the static Centauri, Rylos and Sol record aliases, special class0-only fields can be accessed.  There are no functions currently supported for this object.

    STARDOCK – A special port object that is associated with the class 9 port, StarDock.  Through the static StarDock record alias, special StarDock-only fields can be accessed.  Only the Move function is supported for this object.

    FED – A special boss object that is associated with the Fedpolice.  Through the static Clausewitz, Nelson and Zyrain record aliases, special Fed-only fields can be accessed.  Only the Move function is supported for this object.

    IO – This IO object encapsulates any settings or functions related to input and output control.  There are currently no fields defined by the IO object.  Functions include AddCommand, RemoveCommand and YesNo.

    Most objects are associated with game records.  In order to access the data for a given record, you will use the USE and DROP commands:

    USE Object Index AS Alias

    DROP Alias

    For example, to use player record 3, you would enter

    >USE User 3 as Me

    0 OK

    Once user record 3 is associated with the alias Me, use Me to access its data and call its functions.  For example

    >VIEW Me

    Active = True

    Alignment = 4

    BankBalance = 0

    BBSName = “John”

    Corp = 0

    Credits = 1000

    Experience = 4

    GameName = “John”

    ID = 3

    OnPlanet = 0

    OnPort = 0

    Password = “mypass”

    Sector = 926

    Ship = 3

    Turns = 1000

    0 OK


    SET Me.GameName = “Vid Kid”

    0 OK

    The commands for accessing record data are

    EXEC Alias.Function

    VIEW Alias

    GET Alias.Field

    SET Alias.Field = Value

    Because TradeWars is an interactive game, Botlink objects provide a number of tools for managing multiplayer-safe transactions.  These include

    LOCK  Alias1, Alias2…

    UNLOCK Alias1, Alias2…


    EDIT Alias

    COMMIT Alias

    ROLLBACK Alias

    With EDIT/COMMIT/ROLLBACK, you can open a record for editing (without locking it), then, later, either commit all changes made since the EDIT began, or throw out all changes.

    LOCK/UNLOCK allows you to control access to multiple records during a transaction.  When a record is locked, any attempt to access that record by another session will wait until it is released, up to 5 seconds before failing with an error.  You can lock multiple records at once by listing all aliases in a single LOCK command.

    As an example of how LOCK/UNLOCK is used, suppose you want to purchase 10 fighters from the Class 0 port for a player.  Assume you’ve created aliases of Port1, Player1 and Ship1.

    >LOCK Port1, Player1, Ship1

    0 OK

    >GET Ship1.fighters


    0 OK

    >GET Player1.credits


    0 OK

    >GET Port1.fighterCost


    0 OK

    >SET Player1.credits = 7850

    0 OK

    >SET Ship1.fighters = 1010

    0 OK


    The locked transaction is important because it guarantees that the state of the objects will not change during the transaction.  Without locking, the fighter count could change because of other sessions, for example.  Maybe the player is attacked at the same time the transaction is taking place.  TradeWars does this kind of transactional processing internally for all standard game functions, but these commands allow Botlink developers to maintain the same control over data access.

    Coming up next… Using FIND commands.

  • Botlink help commands

    To begin detailing the functionality of Botlink, I will list out the available help commands.



    This help command lists out all commands supported by Botlink.



    This command lists all objects available to Botlink.  Objects represent entities within the game along with their data fields and functionality.  For example, the Ship Object is used to create Ship records that can be used to view and modify a particular ship’s data.


    >SHOW FIELDS [FOR Object]

    This command will list out all fields supported for a particular object.  It will show the type of the field, its range if applicable, and whether the field is read-only.  For example, these are a few of object Sector’s fields:

    FighterMode : FighterMode

    FighterOwnerIndex : Number [0, 0]

    FighterOwnerType : OwnerType

    Fighters : Number [0, 2000000000]

    NavHaz : Number [0, 100]

    Nebulae : String[41]

    Warps : Array[index : Number] of Number


    FighterMode = {None, Defensive, Toll, Offensive}

    OwnerType = {Player, Corp, Federation, Rogue, Pirate, Ferrengi, AlienTrader, Abandoned, GoldRace}


    >SHOW RANGE FOR Object.field

    This command will show the allowed range for a numeric field.  For example,

    >SHOW RANGE FOR Sector.fighters

    Fighters : Number [0,  2000000000]

    It is also allowed to use a record alias with the SHOW RANGE command.  The range for a record may be different than the range  for an object.  For example, the Ship object has field ranges based on the size of the field (4 byte integer, 2 byte word), but a Ship record has field ranges based on the ship class.  Ship classes define ranges like max fighter count, max shield count, etc.



    This command lists out all available functions for an object.  For example,



    Kill(KillerType: KillerType = Admin; KillerIndex: Number = 0; Pod: Boolean = True; Silent: Boolean = True)

    Move(ToSector: Number)

    Claim(ClaimType: OwnerType;    ClaimIndex: Number = 0)


    Boolean = {False, True}

    KillerType = {Admin, Player, GoldRace}

    OwnerType = {Player, Corp, Federation, Rogue, Pirate, Ferrengi, AlienTrader, Abandoned, GoldRace}


    >SHOW RECORDS [FOR Object]

    This command lists out all aliases for open records, optionally for a specific Object.



    This command lists out a set of “find” commands.  These commands generate lists of record numbers that match a particular criteria.  For example, “>FIND ONLINE PLAYERS” will list out the player ID of every player in the game at that time.  Record IDs are used to open the associated records using an Object.



    This command provides information about how to add color to messages that are displayed in the game.


    Coming up next…  Working with Botlink objects

  • What is Botlink

    Over the years, many TradeWars gameops have requested the ability to write custom add-ons for TradeWars v3.  Earlier versions of TradeWars, especially TWv2, enjoyed an active 3rd party add-on scene.  But when TW became a multiplayer game with the release of v3, it became impossible to implement stable add-ons by working directly with game data.  It would be like writing a program to hack an active SQL database.  You might be able to do it, but with three or four clients interacting with the data, the result would be messy.  Data corruption would be common.  Because of this, I have rarely given anyone access to the details of TradeWars data files.

    Botlink is a tool that provides 3rd party developers access to TradeWars data through a controlled text-based command interface.  It has the same underlying transaction system that TradeWars uses to process player interactions, and in fact has access to all of the same code that TradeWars uses to process game activities.  By using runtime type information, I am able to expose the actual in-game objects directly to Botlink, so a field in, for example, a user record is automatically accessible through a Botlink user object.  These fields are bounded, making it impossible to assign invalid values.  Using a ship record as an example, if the ship class is set to 1, Merchant Cruiser, all fields on the ship record are given appropriate bounds.  If the ship only supports fighters from 0 to 1000, an assignment > 1000 is truncated to 1000.  Also, these fields are multiplayer safe, so setting a value on a user record will immediately update wherever the record is in use.  And in addition to fields, Botlink objects can also expose complex actions through functions.  Any function in the game can be easily exposed through Botlink, making it easy to expand as new functionality is requested.  These functions are multiplayer-safe transactions, locking all relevant records, then unlocking when completed.

    Botlink is being developed in three major phases.  The first phase, which is well underway, is the core data interface phase.  The goal is to provide all relevant fields and complex functions through a set of objects.

    Phase 2 is the event generation phase.  Once implemented, a Botlink controller will be able to express an interest in any event that is currently generated in the game, plus many more to be added.  Such events include “player enters sector”, “player deploys fighters”, “player lands on planet”, etc, but will eventually include any significant activity in the game.  Such events, if requested, will be output to Botlink where a controller can trigger on and respond to them.  In addition, I would like to support stored script blocks so that Botlink can process a block of script immediately on an event rather than waiting for the controller to tell it what to do.  This could be further extended by allowing events to return a boolean value to control what TradeWars does next.  Such events could control player access to ships, implement special code that overrides standard functionality, etc.

    Phase 3 is the player interaction phase.  The goal here is to provide a way for Botlink to capture a player’s session and directly handle IO in place of standard TradeWars IO.  Using this system, a Botlink controller could implement a new area of the game.  For example, you could add a new shop on StarDock.  Once the player enters the area, Botlink provides all screen output and handles all input directly until it releases the player back to the game.  Provide custom menus and create custom areas for players to visit, and new ways for them to interact.  Botlink will introduce a special in-game command system to support custom commands from any area of the game.  These commands would be designated by a “.”, followed by the command text.  So, for example, you could introduce a “.land” command in a sector where you have a custom planet, and in response to this command, the player is handed over to Botlink where you would handle the player’s interactions with this planet.

    That describes the basic functionality I have in mind for Botlink.  If you’re interested, you can see Botlink in action at the EIS beta site, telnet:// 2003 password “sandbox”, giving you admin access to game C, the sandbox game.  As I said, most of phase 1 is complete.  You can see the list of commands currently supported by sending a “>SHOW COMMANDS” command.  That’ll give you all the tools you need to start exploring the command interface.

    I have been posting details about Botlink functionality on the TW forum, but I am going to begin to use this blog for that purpose.  I’ll also copy the previous posts on the subject into this blog so anyone interested can catch up on what’s been done so far.

  • TWGS v2 is out!

    Posted on by John

    Wow, that took a LOT longer than I intended.  I started working on a new version of TWGS a little over a year ago.  I announced I was done sometime late last year.  Well, I’m finally done.  At least, I’m ready to release what I have.  I don’t think I’ll ever be “done” with this game :)

    My initial goals with this release were to enhance the functionality of TWGS, making it easier to manage games, and also to address all of the bugs reported for both the server and the game.  I have achieved those goals, but along the way I decided that it was necessary to rewrite some of the game’s core engine code to optimize the game and provide the mechanism for locking in the pace of gameplay.  TradeWars has always lacked an internal timer that determines the pace of actions in the game.  This is unusual, because most games run under strict timing.  Imagine if Pac Man was written to run at a particular CPU speed, without any time-based pacing.  If the game was run on today’s CPUs, the ghosts would be a blur on the screen.  It would be unplayable.  This is the case with TradeWars.  The game once crawled along at the pace of pre-386 CPUs and 2400 baud modems.  On today’s systems and Internet, a script-driven game can complete hundreds of commands per second.  Not only does this make the game unplayable for most (bots do well, but humans can’t compete), but it also allows a player to hog the server’s CPU by pushing the game to its limits.  By establishing timings for every action in the game, I hope to restore some sanity to the game, and to keep bots from bringing a server to its knees.

    In the process of adding these pace timings, I rewrote the way TradeWars processes events and input, making it much more efficient and responsive.  I also added two editor screens related to game timing.  One is an emulation screen where you can choose the speed of input and output bandwidth, as well as a connection latency (ping).  It defaults to 1 mbps broadband and a 150 ms ping, but you can set it to emulate old modem rates (as low as 1200 baud) and adjust the latency to get a feel for how the game might have run “back in the day”.  The other edit screen introduces a whole new set of delays to the game.  TWv3 (following the changes introduced by HVS for MBBS TWv2) provided delays for ship movement and attack that depends on the ship’s turns per warp.  The new options will allow gameops to explore new delays like ship transport, porting and departing, landing and taking off, planet movement, etc.  Most ways that you can interact with the game will have an optional delay that can be configured here.  If you’re frustrated by the insane pace of bot-driven games, the delay editor will greatly enhance your ability to restore balance to your games.  Rather than impose my own delays, I am leaving it up to capable gameops to explore these delays on their own.  Eventually, I plan to include some presets of popular settings so all gameops can benefit from the efforts of a few.

    I hope you enjoy this new version.  Let me know if you have any comments, questions or would like to learn more about the game’s history, current state, or future.

    You can download TWGS v2 at

  • dinamic_sidebar 4 none

©2022 Entries (RSS) and Comments (RSS)  Raindrops Theme