This is the online version of the mediatransport documentation.

We've discovered (created?) a few new spells. They facilitate direct communication between avatars and hexes; no more getting kicked for spam!

Some of the more data-oriented of us have decoded the format. The entire thing is byte-aligned and uses buffers for data transfer. (that means we have to remember to close them!)

Based on what we've seen, each iota starts with a single-byte type followed by zero or more bytes of data. All multibyte forms are big endian. (that's the default for the Buffer read methods)

The format in its entirety is described here: Iota Transport Protocol

Moreover, Nature doesn't take kindly to being asked to send megabytes of data at a time; to prevent such (ab)use, there is a system of so-called "sending power". It refills quite rapidly (under normal circumstances), and every transmission-related action consumes some.

When you run out of "sending power", trying to submit more iota will result in a mishap. To avoid running into the limit, Quota's Reflection can be useful.

{% include "mediatransport:mediatransport_shared.css.jinja" %}

Data sent via Submit Iota is sent to server_packets.transport_received, like so:

function server_packets.transport_received(data)
    data:close()
end

Data from other casters via Submit Iota II are sent to a different channel: server_packets.transport_external_received

function server_packets.transport_external_received(data)
    data:close()
end

Finally, to send data, use :sendPacket with "transport_send":

server_packets:sendPacket("transport_send", buffer)
buffer:close()

{% include "mediatransport:mediatransport_shared.css.jinja" %}

It seems that the avatar side of the communication isn't without complexity, either - due to a complete lack of wiki maintenance ...less than optimal bookkeeping practices, the only source of information about the systems to interact with Nature seem to be the built-in documentation, which leaves much to be desired.

(If one is curious about that, it seems to be available via the incantation /figura docs globals server_packets and its various branches.)

To act as reference material in the meantime, I have created this supplementary document, which should hopefully provide the reader with a reasonable understanding of how the API works.

Overview of server_packets

Internally called ServerPacketsAPI, server_packets functions very similarly to the much more familiar pings, with a few slight differences.

To receive data, use the function definition syntax you're probably familiar with:

function server_packets.packet_id(data)
  -- Handle data here!
end

Compared to pings, server_packets receivers always have exactly one parameter, through which a Buffer is passed containing the packet's data.

Make sure to close the Buffer you are given! If you don't, the buffer slot will continue to be considered "used" and you will eventually run out of buffers (from my research, most people are unaware there is a limit on buffer count at all, but it exists as part of the permissions system and this is one of the easiest ways to have latent bugs.)

The other main difference from pings is that sending data is explicit and not activated by calling the receiver function - that means calling server_packets.packet_id() does not send anything. To send packets, use server_packets:sendPacket(id, data), where id is a string and data is a Buffer.

Make sure to rewind the Buffer before sending it.

Quick Introduction to Buffers

The canonical documentation for Buffers is accessible via the incantation /figura docs globals data Buffer.

It's also available on FIGS or the Figura Wiki.

Buffers provide a convenient interface for reading structured data like the one Nature provides. It's almost like it's based on something else...

Creating new buffers: data:createBuffer()

To create a new buffer, use data:createBuffer(), which returns a new Buffer object.

You can also specify the initial allocated size by providing it as an argument to createBuffer, but this is not required unless you're working under really tight permissions constraints as Figura will auto-expand buffers by default.

Cleaning up after yourself: :close()

As mentioned in the warning callout above, there is a limit on the number of buffers you can have, and it's tied to the permission system.

• On Default, the limit is 4 buffers.
• On High, the limit is 16 buffers.
• On MAX, the limit is 32 buffers.

To free up a buffer, call close() on it. This will render the contents unusable.

local buf = data:createBuffer()
-- (later...)
buf:close()

Moving the cursor around: :setPosition(pos)

Buffers function with a 'cursor' that moves around the data as you read and write to it.

Each time data is read or written, that action is taken at the position of the cursor and the cursor is automatically advanced to the next byte. This makes it convenient to read or write many values in sequence.

However, it is still useful to be able to move the cursor around manually - notably, to read back the data written to a buffer, the cursor has to be moved ("rewound") back to position 0:

buf:writeByte(5)
buf:writeDouble(3.14159)
buf:setPosition(0) -- move back to the beginning

Writing Data

This section only discusses types that Nature cares about. Other types are supported by buffers - to see that, go to the canonical documentation.

There are methods to write data in various formats to a buffer. They all move the cursor to the end of the data written, so calling them multiple times in sequence will concatenate the data.

For things described as 'x-byte integers', use these names:

• :write(n): 1 byte, such as type, dir for patterns, and rows and cols for matrices.
• :writeInt(n): 4 bytes, which is primarily used to describe the length of things

For 'doubles', use:

• :writeDouble(n): 8 bytes, used for both the value of numbers and the x, y, and z of vectors.

Reading Data

Similar to writing data, Buffers are versatile in what they can read. Each read method also similarily moves the cursor to the end of the data read.

• :read(): 1 byte, such as type, dir for patterns, and rows and cols for matrices.
• :readShort(): 2 bytes - the protocol version
• :readInt(): 4 bytes, usually lengths but also quite a few configuration parameters
• :readDouble(): 8 bytes, used for both the value of numbers and the x, y, and z of vectors, as well as the sending power-related configuration values.

it looks like most of these errors only occur when sending (well, "submitting") data from within nature's domain. nature seems to be much more lenient in accepting bad data... in that it doesn't crash anything and instead outputs its favorite flavor of not-error: garbage!
unfortunately this makes it hard to determine why data isn't making it across the boundary. we've compiled a list of reasons to look out for:

- data is of a type (that's the first byte) that nature has no representation for
- the transmission is missing some data at the end
- the data is too large (seems like this could be different limit than the one going in the other direction...)
- a variant of the above: the same matrix size restrictions apply (though it's impossible to have too many rows or columns, the total area could still be too much)

also note that lists can also partially fail to transfer, leading to the entire decoder potentially derailing and interpreting types as data and vice versa. good luck!