Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Elitriare/ByteNet-Max/llms.txt

Use this file to discover all available pages before exploring further.

defineQuery defines a request/response network channel — the ByteNet Max equivalent of a Roblox RemoteFunction. The client calls invoke with a typed request payload; the server’s listen callback receives it, processes it, and returns a typed response. The client thread yields until the response arrives, making it synchronous from the caller’s perspective while remaining non-blocking for other threads.

​
Signature

ByteNetMax.defineQuery(props: queryProperties<Req, Res>) -> QueryDef<Req, Res>

​
Parameters

​
props
queryProperties
required
A configuration table describing the query’s request and response shapes.

​
Return value

A QueryDef object. The methods available depend on the run context.

​
Client-only methods

​
invoke(request) -> response
function
Sends request to the server and yields the calling thread until the server’s listener callback returns. The return value is the typed response. If no server listener is registered, the client will yield indefinitely.

​
Shared methods

​
listen(callback) -> () -> ()
function
Registers a callback that fires when a request arrives. The callback must return a value matching the response data type — ByteNet Max serializes and sends it back to the invoking client automatically. Returns a disconnect function.The callback signature is (request: Req, player: Player?) -> Res. On the server, player is the requesting client. On the client, player is nil.
​
listenOnce(callback) -> () -> ()
function
Same as listen, but the callback fires only once before automatically disconnecting. Returns a disconnect function if you need to cancel it before it fires.
​
disconnectAll()
function
Removes every listener registered on this query. After calling this, any in-flight invoke calls will yield indefinitely — disconnect all listeners only when you are certain no clients are waiting for a response.
​
wait()
function
Yields the current thread until the next request arrives, then returns the request data and the requesting player. Internally uses a one-shot listener.

​
Example

-- Shared/Network.luau (ModuleScript)
local ByteNetMax = require(path.to.ByteNetMax)

return ByteNetMax.defineNamespace("PlayerData", function()
    return {
        queries = {
            GetCoins = ByteNetMax.defineQuery({
                request = ByteNetMax.struct({
                    message = ByteNetMax.string,
                }),
                response = ByteNetMax.struct({
                    coins = ByteNetMax.uint8,
                }),
            }),
        },
    }
end)

-- Server Script
local Network = require(path.to.Network)

Network.queries.GetCoins.listen(function(data, player)
    print(data.message) -- "How many coins do I have?"
    return { coins = player.leaderstats.Coins.Value }
end)

-- LocalScript
local Network = require(path.to.Network)

local result = Network.queries.GetCoins.invoke({
    message = "How many coins do I have?",
})

print("Coins:", result.coins)

​
Disconnecting a query listener

Assign the return value of listen to a variable to disconnect it later. 
-- Server Script
local Network = require(path.to.Network)
local disconnect

disconnect = Network.queries.GetCoins.listen(function(data, player)
    print(data.message)
    return { coins = player.leaderstats.Coins.Value }
end)

-- Remove this listener when no longer needed:
disconnect()
invoke yields the calling client thread until the server returns a response. From the caller’s perspective it is synchronous — execution resumes on the next line with the response value. Other threads in the same LocalScript continue running normally while the invoking thread waits.
invoke is client-only. Calling it from a server Script throws an error. Additionally, the listen callback for a query must be set up on the server — if the server has no listener when a client invokes, the client thread will yield indefinitely with no timeout.
Incoming query requests pass through the same server-side rate limiter as packets. Each client is allowed up to 8,192 bytes per second by default. Requests that exceed this budget are dropped and a warning is printed. The limit can be configured via the MAX_BUFFER_SIZE attribute on the ByteNet Max module instance.

Build docs developers (and LLMs) love

Get started for freeTalk to us