Viewer messaging and interaction

← Back to docs · Architecture · Viewer compatibility

Status: complete (23 of 23 tasks, 3 phases). Change: openspec/changes/viewer-messaging/.

What was built

The viewer communication and interaction layer: ImprovedInstantMessage dispatch (20+ dialog types), ViewerEffect relay, UUID name and group lookups, avatar profiles, sitting, and script dialog replies. These are the primitives every multi-user viewer session depends on.

Source reference: OpenSim/Region/ClientStack/Linden/UDP/LLClientView.cs and OpenSim/Region/CoreModules/Avatar/InstantMessage/MessageTransferModule.cs.

PhaseAreaTasks
1Core IM: personal relay, typing, friendship, inventory offers, teleport lure1-9
2Group messaging: session create/join, group IM relay, notices, invitations10-15
3Identity and interaction: name lookups, profiles, ViewerEffect, sitting, ScriptDialogReply16-23

Architecture

All viewer messaging goes through the region server. Incoming packets are decoded once and dispatched by type.

ImprovedInstantMessage carries a Dialog field (u8) that selects from 20+ code paths. The handler is a single match statement, each arm calling into the appropriate service (friends, groups, entity transfer, presence). When the target agent is on a different region, the IM is forwarded via the ROBUST messaging service over HTTP.

ViewerEffect packets (typing indicators, look-at, point-at, beams) are relayed to every other agent in the region without server-side interpretation.

ComponentResponsibility
IM dispatchMatch on Dialog field, route to service (friends, groups, presence, transfer)
Offline storagePOST to ROBUST offline IM service when target is not online
Group sessionsTrack session membership in memory, relay messages to online participants
ViewerEffect relayBroadcast to all agents in region, no interpretation
UUIDNameRequestBatch name lookup against user accounts service, region-local LRU cache (5 min TTL)
UUIDGroupNameRequestGroup name lookup against groups service
AvatarPropertiesRequestQuery ROBUST profiles service, return full profile
SittingSit target resolution, position calculation, parent linkage, ObjectUpdate broadcast
ScriptDialogReplyFire chat event on the script's listen channel with the clicked button label

IM dialog dispatch

DialogNameAction
0MessageFromAgentOnline: relay. Offline: store via ROBUST
3GroupInvitationForward to groups service
4/5/6InventoryOffered/Accepted/DeclinedCreate pending offer, relay, handle response
17SessionGroupStartCreate or join group IM session
20SessionSendRelay to all online session participants
22/23/24GroupNotice variantsSend, retrieve, or accept notice inventory
32BusyAutoResponseRelay auto-reply text
38/39/40Friendship offered/accepted/declinedForward to friends service, notify both parties
41/42StartTyping/StopTypingRelay typing indicator
50RequestTeleportForward to entity transfer module

Unknown dialog types are logged and dropped.

Key decisions

  • D1: IM dispatch is a single match statement, not a chain of modules. Each arm calls into the appropriate service. This keeps routing visible in one place and matches OpenSim's approach.
  • D2: ViewerEffect is relay-only. The server never interprets effect data.
  • D3: Name cache is region-local, not global. Each region caches independently with a short TTL so name changes propagate within minutes.
  • D4: Sit position calculation copies OpenSim's logic from ScenePresence.HandleAgentRequestSit and SOPObject.GetSitTarget.

Commits

HashDescription
c6834aaPhase 1: ImprovedInstantMessage handler, dialog dispatch, personal IM, friendship, inventory offers
f1b98faPhase 2: group messaging, session management, group notices, invitations
afdecf9Phase 3: UUIDNameRequest, ViewerEffect relay, profiles, sitting, ScriptDialogReply