This page provides documentation of the public interface of SCPLib.
SCPLib - Main class
Note that you must create an instance of SCPLib and use that to call the member functions.
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)
- Note that you can not use this inside your callback. Instead use the self parameter as a this-pointer.
- 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 |