Modem

Overview

The Modem is the standard NCS/e communications peripheral.

Programs use the Modem to communicate with avatars and objects within the current region, send instant messages across the grid, access remote HTTP services, and send and receive Internet email.

Modem operations use the NET namespace and are divided into four facilities:

  • NET.LOCAL — Communications within the current region.
  • NET.GRID — Communications across the grid.
  • NET.HTTP — HTTP requests.
  • NET.EMAIL — Internet email.

A basic local broadcast consists of:

NET.LOCAL.SEND 42 "Hello, world!"

Programs may listen for incoming local messages:

NET.LOCAL.LISTEN 42
NET.LOCAL.ARECV s0 r0 s1 s2

The Modem can also communicate with remote HTTP services:

NET.HTTP.GET r0 s0 "https://example.com/"

A new program instance begins with a fresh Modem state. Active local listens, queued local messages, email filters, configured HTTP headers, and pending receive operations from the previous instance are cleared.

Local communications

Local communications provide immediate messaging within the current region.

Programs may broadcast messages on channels, send directly to a specific avatar or object, and listen for incoming channel traffic.

Incoming messages are retained by the Modem until retrieved.

Each received message contains:

  1. Message body.
  2. Channel.
  3. Sender name.
  4. Sender UUID.

Messages are retrieved in the order they were received.

NET.LOCAL.LISTEN — Listen on Channel

NET.LOCAL.LISTEN <channel>

Begins listening for messages on a channel.

Messages received on listened channels become available through NET.LOCAL.RECV and NET.LOCAL.ARECV.

Operands

Position Name Type Description
1 channel Integer value Channel to listen on.

Modified registers

This operation does not modify any registers.

Examples

-- Listen for messages on channel 42.
NET.LOCAL.LISTEN 42

A program may begin listening before waiting for a message:

NET.LOCAL.LISTEN 42
NET.LOCAL.ARECV s0

Notes

  • Received messages remain available until retrieved.
  • Message metadata is preserved with each received message.
  • Multiple messages may be waiting at the same time.
  • Listening on a channel that is already active has no additional effect.

NET.LOCAL.UNLISTEN — Stop Listening

NET.LOCAL.UNLISTEN <channel>

Stops listening for messages on a channel.

Operands

Position Name Type Description
1 channel Integer value Channel to stop listening on.

Modified registers

This operation does not modify any registers.

Examples

NET.LOCAL.LISTEN 42

-- Stop listening on channel 42.
NET.LOCAL.UNLISTEN 42

Notes

  • Messages already received remain available until retrieved.
  • Stopping a channel that is not currently being listened to has no effect.

NET.LOCAL.UNLISTENALL — Stop All Listening

NET.LOCAL.UNLISTENALL

Stops listening on all local channels.

Operands

This operation takes no operands.

Modified registers

This operation does not modify any registers.

Examples

Stop all existing listens:

NET.LOCAL.UNLISTENALL

A program may use NET.LOCAL.UNLISTENALL to establish a known listening state before configuring its own channels:

NET.LOCAL.UNLISTENALL
NET.LOCAL.LISTEN 42
NET.LOCAL.LISTEN 100

Notes

  • All active local channel listens are removed.
  • Messages already received remain available until retrieved.

NET.LOCAL.SEND — Broadcast Message

NET.LOCAL.SEND <channel> <body>

Broadcasts a message on a channel.

Messages sent on non-zero channels are available throughout the current region.

Channel 0 sends to public chat instead.

Operands

Position Name Type Description
1 channel Integer value Channel to send on.
2 body String value Message to send.

Modified registers

This operation does not modify any registers.

Examples

Broadcast a message throughout the current region:

NET.LOCAL.SEND 42 "Hello, network!"

Channel 0 may be used to send to public chat:

NET.LOCAL.SEND 0 "Hello, world!"

Notes

  • Non-zero channels are region-wide.
  • Channel 0 uses normal public chat range.
  • Use NET.LOCAL.MSG to communicate directly with a specific avatar or object.

NET.LOCAL.MSG — Send Targeted Message

NET.LOCAL.MSG <channel> <uuid> <body>

Sends a message directly to a specified avatar or object within the current region.

Unlike NET.LOCAL.SEND, the message is sent only to the specified target.

Operands

Position Name Type Description
1 channel Integer value Channel to send on.
2 uuid String value UUID of the target avatar or object.
3 body String value Message to send.

Modified registers

This operation does not modify any registers.

Examples

Send directly to a target on channel 42:

NET.LOCAL.MSG 42 s0 "Hello!"

Channel 0 is also valid:

NET.LOCAL.MSG 0 s0 "Hello!"

Notes

  • The target must be an avatar or object within the current region.
  • Channel 0 remains targeted and does not become a public broadcast.
  • NET.LOCAL.MSG is immediate and does not make the Modem busy afterward.
  • Use NET.GRID.IM to send to an avatar outside the current region.

NET.LOCAL.RECV — Receive Message

NET.LOCAL.RECV <body> [channel] [name] [uuid]

Retrieves the oldest waiting local message.

If no message is available, the body destination is set to an empty string and execution continues immediately.

Additional destinations may optionally receive metadata about the message.

Operands

Position Name Type Description
1 body String register Destination for the message body.
2 channel Integer register Optional destination for the channel.
3 name String register Optional destination for the sender name.
4 uuid String register Optional destination for the sender UUID.

Modified registers

Register Description
body Received message, or an empty string if none is available.
channel Received channel, if specified.
name Sender name, if specified.
uuid Sender UUID, if specified.

Examples

Retrieve only the message body:

NET.LOCAL.RECV s0

Retrieve the body and channel:

NET.LOCAL.RECV s0 r0

Retrieve the message and all available metadata:

NET.LOCAL.RECV s0 r0 s1 s2

A program may test the body to determine whether a message was available:

NET.LOCAL.RECV s0
BSEQ $empty s0 ""

-- Process message here.

Notes

  • NET.LOCAL.RECV never waits for a message.
  • An empty body indicates that no message was available.
  • Empty messages are not received.
  • Retrieving a message removes it from the receive queue.
  • Metadata destinations are optional.

NET.LOCAL.ARECV — Await Message

NET.LOCAL.ARECV <body> [channel] [name] [uuid]

Waits until a local message is available, then retrieves the oldest waiting message.

NET.LOCAL.ARECV returns the same information as NET.LOCAL.RECV, but waits when no message is available instead of returning an empty result.

Operands

Position Name Type Description
1 body String register Destination for the message body.
2 channel Integer register Optional destination for the channel.
3 name String register Optional destination for the sender name.
4 uuid String register Optional destination for the sender UUID.

Modified registers

Register Description
body Received message.
channel Received channel, if specified.
name Sender name, if specified.
uuid Sender UUID, if specified.

Examples

Wait for a message:

NET.LOCAL.LISTEN 42
NET.LOCAL.ARECV s0

Wait for a message and retrieve its metadata:

NET.LOCAL.ARECV s0 r0 s1 s2

Notes

  • Execution waits while no message is available.
  • A message already waiting in the receive queue is returned immediately.
  • Retrieving a message removes it from the receive queue.
  • Metadata destinations are optional.
  • The A prefix indicates that the operation awaits input.

Grid communications

Grid communications provide direct communication beyond the current region.

The Modem can send instant messages to avatars anywhere on the grid, allowing programs to communicate with users regardless of their current location.

NET.GRID.IM s0 "Hello from NCS/e!"

Unlike local communications, the destination does not need to be within the same region.

Grid communication is outbound only.

NET.GRID.IM — Send Instant Message

NET.GRID.IM <uuid> <body>

Sends a grid-wide instant message to an avatar.

Unlike NET.LOCAL.MSG, the destination does not need to be within the current region.

Operands

Position Name Type Description
1 uuid String value UUID of the destination avatar.
2 body String value Message to send.

Modified registers

This operation does not modify any registers.

Examples

NET.GRID.IM s0 "Hello from NCS/e!"

Notes

  • NET.GRID.IM targets avatars, not objects.
  • The destination avatar may be anywhere on the grid.
  • The CPU is released once the Modem accepts the operation.
  • The Modem remains busy for approximately 2 seconds after accepting the operation.
  • Requests sent to the Modem during this period may be delayed.

HTTP requests

The Modem can communicate with remote HTTP services using GET, POST, PUT, and DELETE.

Each request returns an HTTP response code and response body.

HTTP redirects

GET requests automatically follow redirects. POST, PUT, and DELETE requests do not; redirect responses are returned directly to the program.

Request headers may be configured before making a request. Configured headers persist across requests until explicitly cleared.

Response headers are not available to programs.

The Modem handles network-specific restrictions on request headers automatically. Programs may work with ordinary HTTP header names without needing to account for the underlying transport.

Incoming HTTP requests are not supported.

NET.HTTP.NEW — Clear Request Headers

NET.HTTP.NEW

Clears all configured HTTP request headers.

Operands

This operation takes no operands.

Modified registers

This operation does not modify any registers.

Examples

NET.HTTP.NEW

A fresh header set may then be constructed:

NET.HTTP.NEW
NET.HTTP.HEAD "Content-Type" "application/json"
NET.HTTP.HEAD "Authorization" s0

Notes

  • Existing request headers are discarded.
  • HTTP requests do not automatically clear configured headers.
  • Headers remain configured until changed, removed, cleared, or a new program instance begins.

NET.HTTP.HEAD — Set Request Header

NET.HTTP.HEAD <name> <value>

Adds, replaces, or removes an HTTP request header.

Header names are case-insensitive.

Passing an empty value removes the configured header.

Operands

Position Name Type Description
1 name String value Header name.
2 value String value Header value, or an empty string to remove the header.

Modified registers

This operation does not modify any registers.

Examples

Set the content type for subsequent requests:

NET.HTTP.HEAD "Content-Type" "application/json"

Multiple headers may be configured:

NET.HTTP.NEW
NET.HTTP.HEAD "Authorization" s0
NET.HTTP.HEAD "Content-Type" "application/json"
NET.HTTP.HEAD "Accept" "application/json"

Configured headers may then be reused across multiple requests:

NET.HTTP.GET r0 s1 "https://example.com/first"
NET.HTTP.GET r0 s1 "https://example.com/second"

Remove a configured header:

NET.HTTP.HEAD "Authorization" ""

Notes

  • Header names are case-insensitive.
  • Headers persist across HTTP requests.
  • Setting an existing header replaces its previous value.
  • Passing an empty value removes the header.
  • Use NET.HTTP.NEW to clear all configured request headers.
  • Headers reserved or controlled by the network may be ignored.
  • Some standard headers are translated automatically to the corresponding network request parameters.

NET.HTTP.GET — HTTP GET Request

NET.HTTP.GET <code> <body> <url>

Performs an HTTP GET request.

Redirects are followed automatically.

Operands

Position Name Type Description
1 code Integer register Destination for the HTTP response code.
2 body String register Destination for the response body.
3 url String value URL to request.

Modified registers

Register Description
code HTTP response code.
body HTTP response body.
er Set on request error or throttling.

Examples

NET.HTTP.GET r0 s0 "https://example.com/"

Configured request headers are included automatically:

NET.HTTP.NEW
NET.HTTP.HEAD "Authorization" s0
NET.HTTP.GET r0 s1 "https://example.com/api"

Notes

  • Configured request headers are preserved after the request.
  • Redirects are followed automatically.
  • The response code and body correspond to the final response after any redirects.
  • Response headers are not available.
  • er is set to HTTP_ERROR if the request cannot be completed.
  • er is set to HTTP_THROTTLED when the service returns HTTP status 429.

NET.HTTP.POST — HTTP POST Request

NET.HTTP.POST <code> <body> <url> <data>

Performs an HTTP POST request.

Redirects are not followed automatically.

Operands

Position Name Type Description
1 code Integer register Destination for the HTTP response code.
2 body String register Destination for the response body.
3 url String value URL to request.
4 data String value Request body.

Modified registers

Register Description
code HTTP response code.
body HTTP response body.
er Set on request error or throttling.

Examples

NET.HTTP.NEW
NET.HTTP.HEAD "Content-Type" "application/json"

NET.HTTP.POST r0 s0 "https://example.com/api" "{\"value\":42}"

Notes

  • Configured request headers are preserved after the request.
  • Redirects are returned directly to the program.
  • The destination of a redirect cannot be determined because response headers are not available.
  • er is set to HTTP_ERROR if the request cannot be completed.
  • er is set to HTTP_THROTTLED when the service returns HTTP status 429.

NET.HTTP.PUT — HTTP PUT Request

NET.HTTP.PUT <code> <body> <url> <data>

Performs an HTTP PUT request.

Redirects are not followed automatically.

Operands

Position Name Type Description
1 code Integer register Destination for the HTTP response code.
2 body String register Destination for the response body.
3 url String value URL to request.
4 data String value Request body.

Modified registers

Register Description
code HTTP response code.
body HTTP response body.
er Set on request error or throttling.

Examples

NET.HTTP.PUT r0 s0 "https://example.com/resource" s1

Notes

  • Configured request headers are preserved after the request.
  • Redirects are returned directly to the program.
  • The destination of a redirect cannot be determined because response headers are not available.
  • er is set to HTTP_ERROR if the request cannot be completed.
  • er is set to HTTP_THROTTLED when the service returns HTTP status 429.

NET.HTTP.DELETE — HTTP DELETE Request

NET.HTTP.DELETE <code> <body> <url>

Performs an HTTP DELETE request.

Redirects are not followed automatically.

Operands

Position Name Type Description
1 code Integer register Destination for the HTTP response code.
2 body String register Destination for the response body.
3 url String value URL to request.

Modified registers

Register Description
code HTTP response code.
body HTTP response body.
er Set on request error or throttling.

Examples

NET.HTTP.DELETE r0 s0 "https://example.com/resource"

Notes

  • Configured request headers are preserved after the request.
  • Redirects are returned directly to the program.
  • The destination of a redirect cannot be determined because response headers are not available.
  • er is set to HTTP_ERROR if the request cannot be completed.
  • er is set to HTTP_THROTTLED when the service returns HTTP status 429.

Email

The Modem can send and receive Internet email.

Each Modem has its own email address, available through the #NET.EMAIL.ADDR constant.

SMOVE s0 #NET.EMAIL.ADDR

The address may be provided to external systems that need to send email to the Modem.

Email compatibility

Incoming Internet email is subject to compatibility limitations.

Some external mail providers may produce messages that are not delivered to the Modem. In particular, messages using quoted-printable transfer encoding have been observed to fail to arrive, including mail sent by Outlook and Hotmail.

Gmail and other providers using directly encoded plain-text messages are known to work. Email delivery from external services should not be assumed to be universally compatible.

Incoming email may optionally be filtered by sender address and subject using NET.EMAIL.FILTER.

Filters persist until changed or cleared. Both filters use case-insensitive exact matching.

NET.EMAIL.FILTER "player@example.com" "MAILCHESS"
NET.EMAIL.ARECV s0 s1 s2 s3

An empty filter matches any value.

-- Receive email from any sender with any subject.
NET.EMAIL.FILTER "" ""

Incoming Internet email line endings are normalized before being returned to programs.

Email sent directly between compatible NCS/e systems has its transport boilerplate removed before being returned to the program.

NET.EMAIL.FILTER — Set Receive Filter

NET.EMAIL.FILTER <address> <subject>

Sets the sender address and subject filters used when receiving email.

Only messages matching both configured filters are eligible to be received.

Matching is exact and case-insensitive.

An empty string matches any value for that field.

Operands

Position Name Type Description
1 address String value Sender email address to match, or an empty string for any sender.
2 subject String value Subject to match, or an empty string for any subject.

Modified registers

This operation does not modify any registers.

Examples

Receive only messages from a specific sender:

NET.EMAIL.FILTER "player@example.com" ""

Receive messages with a specific subject from any sender:

NET.EMAIL.FILTER "" "MAILCHESS"

Require both a specific sender and subject:

NET.EMAIL.FILTER "player@example.com" "MAILCHESS"

NET.EMAIL.RECV s0 s1 s2 s3

A program may first wait for a handshake from any sender:

NET.EMAIL.FILTER "" "MAILCHESS/HELLO"
NET.EMAIL.ARECV s0 s1 s2 s3

It may then restrict subsequent messages to the confirmed sender:

NET.EMAIL.FILTER s1 "MAILCHESS/MOVE"
NET.EMAIL.ARECV s0 s1 s2 s3

Clear all filtering:

NET.EMAIL.FILTER "" ""

Notes

  • Sender and subject matching is exact and case-insensitive.
  • Both filters persist until changed, cleared, or a new program instance begins.
  • An empty address matches any sender.
  • An empty subject matches any subject.
  • NET.EMAIL.FILTER "" "" disables all receive filtering.
  • Messages that do not match the configured filters remain available for later retrieval.

NET.EMAIL.SEND — Send Email

NET.EMAIL.SEND <address> <subject> <body>

Sends an email message to an Internet email address.

The CPU is released as soon as the Modem accepts the operation. The Modem remains busy for approximately 20 seconds afterward.

Operands

Position Name Type Description
1 address String value Destination email address.
2 subject String value Email subject.
3 body String value Email body.

Modified registers

This operation does not modify any registers.

Examples

NET.EMAIL.SEND "user@example.com" "NCS/e Test" "Hello from NCS/e!"

A Modem may send email to another Modem using its published address:

NET.EMAIL.SEND s0 "MAILCHESS" s1

Execution continues after the Modem accepts the message:

NET.EMAIL.SEND s0 "Report" s1

D.TXT "Email accepted.\n"
D.BLTN

Notes

  • The CPU does not wait for transmission to complete.
  • The Modem remains busy for approximately 20 seconds after accepting an email.
  • Programs should avoid issuing another Modem operation during this period.
  • Requests sent to the Modem while it remains busy may be delayed or, under sufficiently heavy peripheral traffic, lost.

NET.EMAIL.RECV — Receive Email

NET.EMAIL.RECV <body> [address] [subject] [time]

Retrieves the oldest waiting email that matches the configured sender and subject filters.

If no matching email is available, the body destination is set to an empty string and execution continues.

The Modem waits briefly for the email service to respond before determining that no matching message is available.

Additional destinations may optionally receive information about the message.

Operands

Position Name Type Description
1 body String register Destination for the message body.
2 address String register Optional destination for the sender email address.
3 subject String register Optional destination for the message subject.
4 time String register Optional destination for the message timestamp.

Modified registers

Register Description
body Received message, or an empty string if none is available.
address Sender email address, if specified.
subject Message subject, if specified.
time Message timestamp, if specified.

Examples

Retrieve only the message body:

NET.EMAIL.RECV s0

Retrieve the body, sender and subject:

NET.EMAIL.RECV s0 s1 s2

Retrieve all available information:

NET.EMAIL.RECV s0 s1 s2 s3

A program may test the body to determine whether a matching email was available:

NET.EMAIL.RECV s0
BSEQ $empty s0 ""

-- Process email here.

Filters may be configured before receiving:

NET.EMAIL.FILTER "player@example.com" "MAILCHESS"

NET.EMAIL.RECV s0 s1 s2 s3

Notes

  • NET.EMAIL.RECV waits only for the current receive attempt.
  • If no matching email is found, the operation returns with an empty body after approximately 5 seconds.
  • Sender and subject filters are applied before selecting a message.
  • An empty body indicates that no matching email was available.
  • Retrieving an email removes it from the incoming mailbox.
  • Emails that do not match the configured filters remain available.
  • Additional destinations are optional.

NET.EMAIL.ARECV — Await Email

NET.EMAIL.ARECV <body> [address] [subject] [time]

Waits until an email matching the configured sender and subject filters is available, then retrieves it.

NET.EMAIL.ARECV returns the same information as NET.EMAIL.RECV, but continues polling while no matching email is available instead of returning an empty result.

Operands

Position Name Type Description
1 body String register Destination for the message body.
2 address String register Optional destination for the sender email address.
3 subject String register Optional destination for the message subject.
4 time String register Optional destination for the message timestamp.

Modified registers

Register Description
body Received message.
address Sender email address, if specified.
subject Message subject, if specified.
time Message timestamp, if specified.

Examples

Wait for any incoming email:

NET.EMAIL.FILTER "" ""
NET.EMAIL.ARECV s0

Wait for a reply from a specific sender:

NET.EMAIL.FILTER "player@example.com" ""
NET.EMAIL.ARECV s0 s1 s2 s3

Wait for a specific application message:

NET.EMAIL.FILTER "player@example.com" "MAILCHESS"

NET.EMAIL.ARECV s0 s1 s2 s3

Notes

  • Execution waits while no matching email is available.
  • The Modem polls for matching email approximately every 5 seconds while waiting.
  • Sender and subject filters are applied while waiting.
  • Retrieving an email removes it from the incoming mailbox.
  • Emails that do not match the configured filters remain available.
  • Additional destinations are optional.
  • The A prefix indicates that the operation awaits input.
  • NET.EMAIL.ARECV is intended for programs that do not need to perform other work while waiting. Interactive programs should generally check for new mail periodically with NET.EMAIL.RECV instead.