OASIS Learn/Module 10
Intermediate ⏱ 30 min WEB4

ONET & P2P Networking

ONET is the OASIS peer-to-peer mesh network — the layer that lets avatars, nodes and OAPPs talk directly to each other without a centralised server. This module shows you how to discover peers, send messages, and build real-time collaborative features.

What you'll learn

  • What ONET is and how it differs from a traditional WebSocket server
  • Discover peers on the ONET mesh by avatar ID or node ID
  • Send direct messages and broadcast to groups
  • Subscribe to real-time ONET events in your app
  • Query ONODE network status and connected peer counts
  • Use ONET routing for resilient multi-hop message delivery
📦
npm & API reference

Uses @oasisomniverse/web4-api. Full reference: ONET-API.md ↗ and ONODE-API.md ↗.

What is ONET?

ONET (OASIS Network) is a decentralised peer mesh that underpins the OASIS Omniverse. Every ONODE — the server process running the WEB4 API — is also an ONET node. Nodes discover each other automatically and form a resilient routing mesh. Your app can use ONET to:

ONET topology
Your App  ←→  ONODE-A  ←→  ONODE-B  ←→  ONODE-C
                  ↕               ↕
              ONODE-D  ←→  ONODE-E
                          (mesh routing — no single point of failure)

Discovering Peers

discover-peers.js
import { oasis } from './oasis.js';

// Get all currently online nodes in the ONET mesh
const { result: nodes } = await oasis.onet.getOnlineNodes();
console.log('Online nodes:', nodes.length);
nodes.forEach(n => console.log(`  ${n.nodeId}  latency=${n.latencyMs}ms  peers=${n.peerCount}`));

// Find a specific avatar's node (useful for direct messaging)
const { result: peerInfo } = await oasis.onet.findAvatarNode({ avatarId: 'target-avatar-id' });
console.log('Avatar is on node:', peerInfo.nodeId, 'online:', peerInfo.isOnline);

Sending Messages

Direct messages are encrypted end-to-end using the recipient avatar's public key and delivered via the shortest ONET path.

send-message.js
// Send a direct message to another avatar
const { result, isError } = await oasis.onet.sendMessage({
  toAvatarId: 'recipient-avatar-id',
  subject:    'Key drop',
  message:    'I left a red key in the corridor — check your inventory',
  metadata:   { itemType: 'key', colour: 'red' },
});

if (!isError) console.log('Delivered via node:', result.routedThroughNodeId);

// Broadcast to a group (all avatars with a given tag or in a mission)
await oasis.onet.broadcastMessage({
  groupTag: 'mission-42-participants',
  subject:  'Boss spawned',
  message:  'The final boss has appeared at GeoHotSpot 7!',
});

Subscribing to Real-Time Events

Use the ONET event stream to receive push notifications — no polling required.

subscribe-events.js
// Subscribe to all ONET events for this avatar
const unsub = oasis.onet.subscribe({
  events: ['message', 'karma', 'nft_received', 'node_state_change'],
  onEvent: (event) => {
    switch (event.type) {
      case 'message':
        console.log('New message from', event.fromAvatarId, ':', event.subject);
        break;
      case 'karma':
        console.log('Karma awarded:', event.amount, 'new total:', event.newTotal);
        break;
      case 'nft_received':
        console.log('NFT received:', event.nftId, event.nftTitle);
        break;
    }
  }
});

// Later: clean up
unsub();

Querying ONODE Network Status

node-status.js
const { result: status } = await oasis.onode.getNodeStatus();
console.log('Node ID:',      status.nodeId);
console.log('Version:',      status.version);
console.log('Uptime:',       status.uptimeSeconds, 's');
console.log('Connected peers:', status.connectedPeers);
console.log('Active providers:', status.activeProviders);
💡
Use ONET events for cross-game features

ODOOM and OQuake both use ONET to share inventory state across games in real time — when you pick up a key in OQuake it appears in your ODOOM inventory within milliseconds. See the ODOOM case study and OQuake case study for implementation details.

Next steps