The ugBASIC language is equipped with primitives capable of communicating
with an external server, called DOJO, which is a system for creating virtual
"game rooms" online. This guide contains information and tutorials to make the best use
of this feature, as well as a description of the DOJO protocol
Preparation
Services
Message Ports
In order to use the DOJO protocol features, it is necessary to connect the retrocomputer to a server that implements the protocol. Here you will find some summary instructions on how to do it.
The DOJO protocol provides a set of commands that are implemented as statements and functions on ugBASIC, and serve to model a set of services.
A mechanism for managing ports and messages is set up, and it can be used as elements of asynchronous communication between programs. They are very useful for allowing the management of multiplayer games. The instructions that are available in this mode are:
= PING(...)
- check if the connection is alive;= CREATE PORT()
- it allows to create a port;= [OPEN] PORT(...)
- it allows to open an existing port (or to create one);PUT [MESSAGE] ...
- it allows to send a message to a port;= PEEK [MESSAGE](...)
- it allows to check if a message is available;= GET [MESSAGE](...)
- it allows to retrieve any available message;
CREATE PORT()
functionOPEN PORT("")
function, with an empty string.portId = CREATE PORT( )
PRINT
,
to make it clear to the user. It is normally an 8 hexadecimal digit number:42abc000
[OPEN] PORT(...)
function, whose
syntax is as follows:portId = OPEN PORT("unique id")
portId = PORT("unique id")
0
) for one direction of communication and another (e.g. 1
)
for the other.
To put a message we can use the PUT [MESSAGE]
statement, with the
following syntaxes:
PUT [MESSAGE] portId[, channel], message
= PUT [MESSAGE]( portId[, channel], message )
channel
is missing, the default channel will be 0. Moreover,
if you use the first form, you are not interested to know if the message has
been posted; otherwise, you can check if everything is ok by verifying the
return value (TRUE
is ok, FALSE
otherwise).
Once you have created a port and sent a message, you may wait for a
message to arrive to you. As explained in the previous chapters,
the port is accessible to anyone who knows its identifier. Therefore,
many messages may arrive or none at all. The program that wants to wait
for the arrival can use the PEEK MESSAGE
command.
The syntax is as follows:
= PEEK [MESSAGE]( portId[, channel] )
channel
is missing, the default channel will be 0.
If it returns FALSE
, it means that the message port is empty; on
the contrary, if it returns TRUE
, it is possible to fetch the message
using the GET [MESSAGE]
command. The syntax is:= GET [MESSAGE]( portId[, channel] )
GET [MESSAGE] portId[, channel], variable
channel
is missing, the default channel will be 0.
The second form allows to retrieve any kind of data type, even arrays, up to 256 bytes.
Note that the message port behaves like a queue, that is, the first
message that is inserted is the first that is retrieved. Therefore,
if a program sends three messages in a row to the attention of the
channel of a port, the receiving program will receive the three messages
in the same order.
If you have found a problem, if you think there is a bug or, more
simply, you would like something to be improved, write a topic on the official forum, or open an issue on GitHub.
Thank you!