classDocs / Message

Message

classsharedsource

Object → Message

A named channel that sends data through hidden console commands, so it also works between the menu and the client states, where the net library doesn't.

The server sends to the client state of players, the client sends to the server or the menu, the menu sends to the client. The data is split into url-safe base64 packets of one console line each, paced by a per-frame byte budget, and is delivered to the handlers only when complete.

It is slow ( ~45 KiB/s with a 20 fps client ) and has no checksum, so prefer Network for large data between the server and the client.

Every realm must create the message with the same name to receive it, creating a message with the name of an existing one returns the existing object.

Messages to the same target are queued and sent in order.

Constructor

Message(name: string, can_receive: boolean?): Message

Fields

Name	Type	Description
`name`	`string`	The name of the message, read-only.
`receiver`	`boolean`	`true` if the message accepts incoming data, `false` by default.
`timeout`	`number`	The number of seconds without a packet after which an incomplete incoming transfer is dropped, `15` by default, at least `1`.
`limit`	`integer`	The maximum size of an incoming message in bytes, `256` KiB by default, `0` rejects everything.

Methods

`abort`	Cancels the outgoing transfers of this message to the target, the packets already sent are not recalled.
`attach`	Attaches a handler that is called when a message is fully received.
`await`	Waits for the next fully received message.
`clear`	Removes every receive handler.
`detach`	Detaches a previously attached receive handler.
`isReceiving`	Checks if the message is receiving data from the sender.
`isSending`	Checks if the message has queued outgoing packets to the target.
`once`	Attaches a handler that automatically detaches itself right before being invoked, so it only ever runs once.
`send`	Sends the data to the target.
`transmit`	Builds the data with a binary writer and sends it to the target.

#Message:abort

sharedsource

function Message:abort(target?: ( garrysmod.Player | Message.Realm )?): boolean

Cancels the outgoing transfers of this message to the target, the packets already sent are not recalled.

Parameters

Name	Type	Description
`target`optional	`( garrysmod.Player \| Message.Realm )?`	The target player on the server, the target realm on the client, ignored in the menu.

Returns

Type	Name	Description
`boolean`	`cancelled`	`true` if anything was cancelled.

#Message:attach

sharedsource

function Message:attach(handler: Message.ReceiveFn | Hook | Event)

Attaches a handler that is called when a message is fully received.

If the handler is already attached, it will not be attached twice.

Parameters

Name	Type	Description
`handler`	`Message.ReceiveFn \| Hook \| Event`	The callback or callable object.

#Message:await

sharedasyncsource

async function Message:await(): Message, BinaryReader, garrysmod.Player | nil, Message.Realm

Waits for the next fully received message.

Returns

Type	Name	Description
`Message`	`message`	The message.
`BinaryReader`	`reader`	The reader of the message.
`garrysmod.Player \| nil`	`sender`	The sender, `nil` on the client and menu.
`Message.Realm`	`realm`	The realm the message claims to come from.

#Message:clear

sharedsource

function Message:clear()

Removes every receive handler.

#Message:detach

sharedsource

function Message:detach(handler: Message.ReceiveFn | Hook | Event): boolean

Detaches a previously attached receive handler.

Parameters

Name	Type	Description
`handler`	`Message.ReceiveFn \| Hook \| Event`	The exact handler reference.

Returns

Type	Name	Description
`boolean`	`removed`	`true` if the handler was attached.

#Message:isReceiving

sharednodiscardsource

function Message:isReceiving(sender?: ( garrysmod.Player | Message.Realm )?): boolean

Checks if the message is receiving data from the sender.

Parameters

Name	Type	Description
`sender`optional	`( garrysmod.Player \| Message.Realm )?`	The sender player on the server, the sender realm on the client, ignored in the menu.

Returns

Type	Name	Description
`boolean`	`is_receiving`	`true` if an incomplete transfer from the sender is in progress.

#Message:isSending

sharednodiscardsource

function Message:isSending(target?: ( garrysmod.Player | Message.Realm )?): boolean

Checks if the message has queued outgoing packets to the target.

Parameters

Name	Type	Description
`target`optional	`( garrysmod.Player \| Message.Realm )?`	The target player on the server, the target realm on the client, ignored in the menu.

Returns

Type	Name	Description
`boolean`	`is_sending`	`true` if a transfer of this message to the target is queued.

#Message:once

sharedsource

function Message:once(handler: Message.ReceiveFn | Hook | Event)

Attaches a handler that automatically detaches itself right before being invoked, so it only ever runs once.

Parameters

Name	Type	Description
`handler`	`Message.ReceiveFn \| Hook \| Event`	The callback or callable object.

#Message:send

sharedsource

function Message:send(data: string, target?: ( garrysmod.Player | garrysmod.Player[] | Message.Realm )?, callback?: Message.FinishFn)

Sends the data to the target.

The data is split into console command packets that are paced over frames, the ~8 kb per frame console limit makes it slow ( ~45 kb/s with a 20 fps client ), so prefer Network for large data between the server and the client.

The server sends to the client state of the target players, the client sends to "server" ( default ) or "menu", the menu sends to the client.

Messages to the same target are queued and sent in order.

Parameters

Name	Type	Description
`data`	`string`	The data to send.
`target`optional	`( garrysmod.Player \| garrysmod.Player[] \| Message.Realm )?`	The target player(s) on the server, the target realm on the client, ignored in the menu.
`callback`optional	`Message.FinishFn`	The callback that is called when the last packet is handed to the engine, or the target left.

#Message:transmit

sharedsource

function Message:transmit(fn: fun( message: Message, writer: BinaryWriter ), target?: ( garrysmod.Player | garrysmod.Player[] | Message.Realm )?, callback?: Message.FinishFn)

Builds the data with a binary writer and sends it to the target.

Parameters

Name	Type	Description
`fn`	`fun( message: Message, writer: BinaryWriter )`	The function that writes the data.
`target`optional	`( garrysmod.Player \| garrysmod.Player[] \| Message.Realm )?`	The target player(s) on the server, the target realm on the client, ignored in the menu.
`callback`optional	`Message.FinishFn`	The callback that is called when the last packet is handed to the engine, or the target left.