classictw.com

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

or

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…

UNLOCK ALL

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

1000

0 OK

>GET Player1.credits

10000

0 OK

>GET Port1.fighterCost

215

0 OK

>SET Player1.credits = 7850

0 OK

>SET Ship1.fighters = 1010

0 OK

>UNLOCK ALL

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.

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

>SHOW COMMANDS

This help command lists out all commands supported by Botlink.

>SHOW OBJECTS

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.

>SHOW FUNCTIONS [FOR Object]

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

>SHOW FUNCTIONS FOR Ship

Deactivate()

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.

>SHOW FINDS

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.

>SHOW COLOR CODES

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

Coming up next…  Working with Botlink objects

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://twgs.classictw.com 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.