SpaiR / byond-message-client

Library for Java to send and receive messages from BYOND.

BYOND Message Client

About

Small library for Java, which provide simple way to send messages and receive responses from BYOND server.

Installation

Library is deployed and provided with Maven Central and JCenter repositories.

pom.xml:

<dependency>
    <groupId>io.github.spair</groupId>
    <artifactId>byond-message-client</artifactId>
    <version>${last.version}</version>
</dependency>

build.gradle:

compile 'io.github.spair:byond-message-client:${last.version}'

Usage

There are three main classes to use:

• ByondClient
• ByondMessage (with ServerAddress class)
• ByondResponse

Example:

ByondMessage message = new ByondMessage("bagil.game.tgstation13.org", 2337, "ping");
ByondResponse response = new ByondClient().sendMessage(message);

If you print response object you could see something like that:

ByondResponse(response=56.0, responseType=FLOAT_NUMBER)

Response data is an Object class, so manual class cast is needed.

Additional info:

• On BYOND side message should be handled in World/Topic() method. Look BYOND Ref for more info.
• If you want just to send message to BYOND and you don't care about response use sendCommand() method instead of sendMessage() or set expected response type in ByondMessage as ResponseType.NONE.
• To control response type from BYOND set ResponseType.FLOAT_NUMBER or ResponseType.STRING in ByondMessage instance. If actual response type is different exception UnexpectedResponseException will be thrown.

Also there are some exceptions I'll recommend to handle due to significant reasons.

1. HostUnavailableException It will be thrown if host you try to send message is currently offline. Restart moment, for example.
2. UnexpectedResponseException Exception will be thrown while two reasons: World/Topic() doesn't return any response on your message; moment between when server already restarted, but World didn't initialized. Little chance, but you can got in this situation.

Read more in JavaDoc.