TradeWars Blog

TradeWars Blog

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


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



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.

  • dinamic_sidebar 4 none

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