SCPLib doc

From OpenTTD
Jump to: navigation, search

This page provides documentation of the public interface of SCPLib.

Contents

SCPLib - Main class

Note that you must create an instance of SCPLib and use that to call the member functions.

Content.png

Warning
The interface documentation of the main class is auto-generated using the build-docs.py command of the library. Do not edit the interface documentation of this class manually. Instead make suggestions on the tracker or submit a patch on main.nut: http://dev.openttdcoop.org/projects/scriptlib-scp

constructor SCPLib(s_name, s_version, aicall=null)

Initalize the Script Communication Protocol library. You must construct this class prior to using any library function.

s_name a string with short name of your script
s_version a string with the version of your script
aicall a callback function that is called when an AIAI-protocol message is received
result instance

SCPLib::AddCommand(_Name, _CommandSet, self, _loopback=null)

Add a command. AI & GS.

_Name a string with the name of the command
_CommandSet a string with the name of the command set
self optional pointer to an instance of the class where the callback function belongs to. In most cases you'll probably pass 'this' as this parameter.
_loopback pointer to callback function
result void

SCPLib::QueryServer(_usingCommand, _usingSet, ...)

Send a query to the server. AI ONLY.

_usingCommand string with the command to send
_usingSet a string with the command set where the command using_command belongs to
... data to send to the receiver of the command. The data will end up in the order as it is sent in the Data member of the message structure that the receiver callback function get.
result

SCPLib::TellServer(_usingCommand, _usingSet, ...)

Send a query to the server. AI ONLY. By using Tell* instead of Query*, we tell the receiver of this message that we are not expecting to get an answer.

_usingCommand string with the command to send
_usingSet a string with the command set where the command using_command belongs to
... data to send to the receiver of the command. The data will end up in the order as it is sent in the Data member of the message structure that the receiver callback function get.
result

SCPLib::QueryAI(_CompanyID, ...)

Send a query to another AI controlling _CompanyID. AI ONLY.

_CompanyID company ID of the company to send the command to
... data to send to the receiver of the command. The data will end up in the order as it is sent in the Data member of the message structure that the receiver callback function get.
result

SCPLib::TellAI(_CompanyID, ...)

Tell something to another AI controlling _CompanyID. AI ONLY. By using Tell* instead of Query*, we tell the receiver of this message that we are not expecting to get an answer.

_usingCommand string with the command to send
_usingSet a string with the command set where the command using_command belongs to
_CompanyID company ID of the company to send the command to
... data to send to the receiver of the command. The data will end up in the order as it is sent in the Data member of the message structure that the receiver callback function get.
result

SCPLib::QueryCompany(_usingCommand, _usingSet, _CompanyID, ...)

Send a query to a companyID. GS ONLY.

_usingCommand string with the command to send
_usingSet a string with the command set where the command using_command belongs to
_CompanyID company ID of the company to send the command to
... data to send to the receiver of the command. The data will end up in the order as it is sent in the Data member of the message structure that the receiver callback function get.
result

SCPLib::TellCompany(_usingCommand, _usingSet, _CompanyID, ...)

Tell something a companyID. GS ONLY. By using Tell* instead of Query*, we tell the receiver of this message that we are not expecting to get an answer.

_usingCommand string with the command to send
_usingSet a string with the command set where the command using_command belongs to
_CompanyID company ID of the company to send the command to
... data to send to the receiver of the command. The data will end up in the order as it is sent in the Data member of the message structure that the receiver callback function get.
result

SCPLib::Answer(message, ...)

Send an answer to a previous query, it will be sent to who has made the query to you (the server or an AI). AI & GS.

message pass the message instance that you got as parameter to your callback function
... data to be sent along with the command. The data end up as Data[0], Data[1], .. etc. on the receiver end.
result

SCPLib::CanSpeakWith(companyID = 16)

companyID ID of company to speak with. Defaults to 16 (Game Script). AI & GS.
result true if we could speak with that company ID, otherwise false

SCPLib::Check()

You must include a call to this function in the main loop. This function scans for incoming communication signs and if there is any incoming messages the registered callback functions are called. Check() has been designed so that when one task such as handling a incoming message has been done, it returns. If there is more work to do (eg. incoming messages), it will return true to indicate this, otherwise false. So if you have time and prioritize quick responses on SCP communication, you should do something like this: while(my_scp.Check()) { }. AI & GS.

result true if there are more tasks for the lib to do, otherwise false

SCPLib::SetEventHandling(enable)

Enable or disable the handling of events by the lib (defaults to disabled). AI & GS. If enabled, the library will read and discard events from OpenTTD by itself when you call Check(). This is recommended if you don't call [AI/GS]EventController.GetNextEvent(). If this setting is disabled, the library will get informed about events automagically when you call [AI/GS]EventController.GetNextEvent().

enable true to enable handling of events by the lib, false if your script handle events itself

SCPLib::GetAIAIProtocol(_CompanyID)

result true if AIAI protocol is enabled for that company, otherwise false. AI & GS.

SCPLib::SCPLogging_Error(enable)

enable true to enable SCP loggin error only in console. AI & GS.

SCPLib::SCPLogging_Info(enable)

If you wish help us debugging what's going on, enabling this one should help us, your console will get more noise. This also force error logging if enabled. AI & GS.

enable true to enable SCP loggin info in console

SCPLib::SCPGetCommunicationTile()

The communication tile is where the signs used to communicate are placed. You can use this function to ignore all signs on this tile if you use signs for some other purposes. AI & GS.

result the tile that is use as the Communication Tile

Callback function

Several functions accept a callback function which is called when a command is received from a remote AI/Game Script. The callback function should follow this specification:

MyClass.MyCallback(message, self)

  1. Note that you can not use this inside your callback. Instead use the self parameter as a this-pointer.
  2. If you wish to respond to the sender, you can do that by calling SCPLib.Answer.
message a Message instance. Here you find information about command, data, sender etc.
self the instance that you registered together with the callback function
result void


Message

The Message class contains several useful variables. While in general you should not need to read member variables of SCP, the Message class is an exception. All members can be regarded as public although you should not change them yourself, only read them.

Message also contains a few helper functions. These are used to ease access of Data entries without having to check for all possible things that could go wrong yourself.

The variables are listened here:

Member variable Description
PoolID internal use only
MessageID internal use only
Command a string with the command that was received
CommandSet a string with the command set that the command belongs to
SenderID the company ID of the sender. If the sender is the GameScript, the sender ID is 16.
ReceiverID the company ID of the receiver. If the receiver is the GameScript, the receiver ID is 16.
Type internal use only
Data A list with the data that was sent by the sender. First data is found at Data[0], second at Data[1], etc.

Message::GetData(index)

Get data at the index position in Data. If Data doesn't exist or the index is invalid, null is returned.

index position in the Data array to grab
result Data[index] if it exist, otherwise null

Message::GetIntData(index)

Get integer data at the index position in Data. If Data doesn't exist or the index is invalid, null is returned. If data exist, but is not of the type integer, null will be returned.

index position in the Data array to grab
result Data[index] if it exist and is of the type integer, otherwise null

Message::GetStringData(index)

Get string data at the index position in Data. If Data doesn't exist or the index is invalid, null is returned. If data exist, but is not of the type string, null will be returned.

index position in the Data array to grab
result Data[index] if it exist and is of the type integer, otherwise null

Message::GetBoolData(index)

Get bool data at the index position in Data. If Data doesn't exist or the index is invalid, null is returned. If data exist, but is not of the type integer, null will be returned. Yes, it is not a typo. Bools are transmitted as integers, however this function does check that the received integer is 0 or 1, otherwise null is returned as well.

index position in the Data array to grab
result Data[index] if it exist and is of the type integer and is 0 or 1, otherwise null
Personal tools