Network & peer-to-peer

Networking is non-blocking: start a request, then poll from c8b.update. On the console it goes through the ESP32 Wi-Fi bridge; on the emulator through host sockets. Several functions exist on only one platform — check Availability.

Conventions on every page: Availability says whether a symbol exists on the console BIOS, the emulator, or both. c8b and C8B are the same table.

Contents#

• Status
  • c8b.net.connected
  • c8b.net.wifi_status
  • c8b.net.localip
• HTTP (c8b.net.http) — non-blocking, one request at a time
  • c8b.net.http.get
  • c8b.net.http.post
  • c8b.net.http.status
  • c8b.net.http.response
  • c8b.net.http.busy
  • c8b.net.http.cancel
  • c8b.net.http.download
  • c8b.net.http.downloadProgress
  • c8b.net.http.downloadStatus
  • c8b.net.http.downloadSize
  • c8b.net.http.queue_size
• UDP (c8b.net.udp)
  • c8b.net.udp.open
  • c8b.net.udp.send
  • c8b.net.udp.recv
  • c8b.net.udp.close
  • c8b.net.udp.available
  • c8b.net.udp.sendBlob
  • c8b.net.udp.onBlob
  • c8b.net.udp.blobReset
  • c8b.net.udp.port
  • c8b.net.udp.is_open
• Peer-to-peer multiplayer (c8b.net)
  • c8b.net.host
  • c8b.net.rooms
  • c8b.net.join
  • c8b.net.joinCode
  • c8b.net.status
  • c8b.net.slot
  • c8b.net.send
  • c8b.net.recv
  • c8b.net.close
  • c8b.net.code
  • c8b.net.mode
  • c8b.net.players
  • c8b.net.error
• STV video streaming (c8b.stv)
  • c8b.stv.startEncoder
  • c8b.stv.sendFrame
  • c8b.stv.sendAudio
  • c8b.stv.stopEncoder
  • c8b.stv.getStats
  • c8b.stv.startDecoder
  • c8b.stv.stopDecoder
  • c8b.stv.pollDecoder
  • c8b.stv.getDecStats
  • c8b.stv.setQuality
  • c8b.stv.poll
  • c8b.stv.decodeFrame
  • c8b.stv.playAudio
  • c8b.stv.getInfo

Status#

c8b.net.connected#

c8b.net.connected()

Whether Wi-Fi is connected (console: ESP32 bridge; emulator: host network).

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.wifi_status#

c8b.net.wifi_status()

Human-readable Wi-Fi status string.

• Returns: string
• Availability: Console (BIOS) and emulator

c8b.net.localip#

c8b.net.localip()

Local IP address.

• Returns: string
• Availability: Console (BIOS) and emulator

HTTP (c8b.net.http) — non-blocking, one request at a time#

c8b.net.http.get#

c8b.net.http.get(url)

Starts a GET request. Poll busy()/status() and read response().

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.http.get("https://example.com/hi.json")
-- later, in update:
if not c8b.net.http.busy() and c8b.net.http.status() == 200 then
  local data = json.decode(c8b.net.http.response())
end

c8b.net.http.post#

c8b.net.http.post(url, [body=""], [contentType="json"])

Starts a POST request.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.http.status#

c8b.net.http.status()

HTTP status of the last request (0 while pending, negative on error).

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.net.http.response#

c8b.net.http.response()

Body of the last completed request.

• Returns: string
• Availability: Console (BIOS) and emulator

c8b.net.http.busy#

c8b.net.http.busy()

Whether a request is in flight.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.http.cancel#

c8b.net.http.cancel()

Cancels the current request.

• Availability: Console (BIOS) and emulator

c8b.net.http.download#

c8b.net.http.download(url, path, [callback])

Streams a GET response into a file (relative to the game folder).

• Returns: boolean
• Availability: Console (BIOS) and emulator
• Note: The completion callback(success, bytesWritten, httpCode) is called only on the console; the emulator takes only url and path.

c8b.net.http.downloadProgress#

c8b.net.http.downloadProgress()

Bytes written so far.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.net.http.downloadStatus#

c8b.net.http.downloadStatus()

0 while downloading, HTTP code when finished, -1 when idle (console).

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.net.http.downloadSize#

c8b.net.http.downloadSize()

Content-Length of the current download (0 if unknown).

• Returns: integer
• Availability: Console (BIOS) only

c8b.net.http.queue_size#

c8b.net.http.queue_size()

1 if a request is waiting for a retry after HTTP 503, else 0.

• Returns: integer
• Availability: Console (BIOS) only

UDP (c8b.net.udp)#

c8b.net.udp.open#

c8b.net.udp.open([port=0])

Opens the UDP socket (0 = any port).

• Returns: port (integer)
• Availability: Console (BIOS) and emulator

c8b.net.udp.send#

c8b.net.udp.send(ip, port, data)

Sends a datagram.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.udp.recv#

c8b.net.udp.recv()

Next datagram, or nil when none is queued.

• Returns: ip, port, data
• Availability: Console (BIOS) and emulator

c8b.net.udp.close#

c8b.net.udp.close()

Closes the socket.

• Availability: Console (BIOS) and emulator

c8b.net.udp.available#

c8b.net.udp.available()

Queued datagrams.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.net.udp.sendBlob#

c8b.net.udp.sendBlob(ip, port, data)

Sends a large payload in chunks.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.udp.onBlob#

c8b.net.udp.onBlob(fn | nil)

Callback for reassembled blobs.

• Availability: Console (BIOS) and emulator

c8b.net.udp.blobReset#

c8b.net.udp.blobReset()

Clears blob reassembly state.

• Availability: Console (BIOS) and emulator

c8b.net.udp.port#

c8b.net.udp.port()

Local port of the open socket.

• Returns: integer
• Availability: Console (BIOS) only

c8b.net.udp.is_open#

c8b.net.udp.is_open()

Whether the socket is open.

• Returns: boolean
• Availability: Console (BIOS) only

Peer-to-peer multiplayer (c8b.net)#

c8b.net.host#

c8b.net.host(game, [maxPlayers=2], [opts])

Creates a room (2-4 players). opts = {name, visibility="public", password, metadata}. Returns false unless idle.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.rooms#

c8b.net.rooms(game)

Non-blocking room listing: the first call starts the request, later calls return nil until the JSON list is ready.

• Returns: string (JSON) or nil
• Availability: Console (BIOS) and emulator

c8b.net.join#

c8b.net.join(roomId)

Joins a room by id.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.joinCode#

c8b.net.joinCode(code)

Joins a room by short code.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.status#

c8b.net.status()

"idle", "stun", "creating", "hosting", "listing", "joining", "punching", "connected", "relay" or "failed".

• Returns: string
• Availability: Console (BIOS) and emulator

c8b.net.slot#

c8b.net.slot()

This player's slot number.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.net.send#

c8b.net.send(data)

Sends a message to the peer(s).

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.net.recv#

c8b.net.recv()

Next message or nil.

• Returns: string or nil
• Availability: Console (BIOS) and emulator

c8b.net.close#

c8b.net.close()

Leaves the session.

• Availability: Console (BIOS) and emulator

c8b.net.code#

c8b.net.code()

Room join code.

• Returns: string
• Availability: Console (BIOS) and emulator

c8b.net.mode#

c8b.net.mode()

Transport mode (direct or relay).

• Returns: string
• Availability: Console (BIOS) and emulator

c8b.net.players#

c8b.net.players()

Players in the room.

• Returns: integer
• Availability: Console (BIOS) and emulator

c8b.net.error#

c8b.net.error()

Last error message.

• Returns: string
• Availability: Console (BIOS) and emulator

STV video streaming (c8b.stv)#

c8b.stv.startEncoder#

c8b.stv.startEncoder(host, port, [quality], [keyInterval])

Starts streaming the screen to host:port. Implementations differ between the console and the emulator.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.stv.sendFrame#

c8b.stv.sendFrame()

Encodes and sends the current frame. Implementations differ between the console and the emulator.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.stv.sendAudio#

c8b.stv.sendAudio(...)

Sends audio samples (console: two integers; emulator: pointer + count). Implementations differ between the console and the emulator.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.stv.stopEncoder#

c8b.stv.stopEncoder()

Stops the encoder. Implementations differ between the console and the emulator.

• Availability: Console (BIOS) and emulator

c8b.stv.getStats#

c8b.stv.getStats()

Encoder statistics table. Implementations differ between the console and the emulator.

• Returns: table
• Availability: Console (BIOS) and emulator

c8b.stv.startDecoder#

c8b.stv.startDecoder(port)

Starts receiving a stream. Implementations differ between the console and the emulator.

• Returns: boolean
• Availability: Console (BIOS) and emulator

c8b.stv.stopDecoder#

c8b.stv.stopDecoder()

Stops the decoder. Implementations differ between the console and the emulator.

• Availability: Console (BIOS) and emulator

c8b.stv.pollDecoder#

c8b.stv.pollDecoder()

Console: receives/decodes pending data.

• Returns: integer or nil
• Availability: Console (BIOS) only

c8b.stv.getDecStats#

c8b.stv.getDecStats()

Console: decoder statistics.

• Returns: table
• Availability: Console (BIOS) only

c8b.stv.setQuality#

c8b.stv.setQuality(q)

Emulator: encoder quality.

• Returns: integer
• Availability: Emulator only

c8b.stv.poll#

c8b.stv.poll()

Emulator: receives pending packets.

• Returns: boolean
• Availability: Emulator only

c8b.stv.decodeFrame#

c8b.stv.decodeFrame()

Emulator: decodes a received frame to the screen.

• Returns: boolean
• Availability: Emulator only

c8b.stv.playAudio#

c8b.stv.playAudio()

Emulator: plays received audio.

• Returns: integer
• Availability: Emulator only

c8b.stv.getInfo#

c8b.stv.getInfo()

Emulator: stream info table or nil.

• Returns: table
• Availability: Emulator only