Networked-Aframe

Multi-user VR on the Web

A framework for writing multi-user VR apps in HTML and JS.

Built on top of A-Frame.

Features

• Support for WebRTC and/or WebSocket connections.
• Voice chat. Audio streaming to let your users talk in-app (WebRTC only).
• Video chat. See video streams in-app.
• Bandwidth sensitive. Only send network updates when things change.
• Cross-platform. Works on all modern Desktop and Mobile browsers. Oculus Rift, Oculus Quest, HTC Vive and Google Cardboard.
• Extendable. Sync any A-Frame component, including your own, without changing the component code at all.

Release notes

You can read the release notes to know what changed in the latest releases.

Getting Started

Follow the NAF Getting Started tutorial to build your own example from scratch, including setting up a local server.

To run the examples on your own PC:

git clone https://github.com/networked-aframe/networked-aframe.git  # Clone the repository.
cd networked-aframe
npm install  # Install dependencies.
npm run dev  # Start the local development server.

With the server running, browse the examples at https://localhost:8080. Open another browser tab and point it to the same URL to see the other client.

For info on how to host your experience on the internet, see the NAF Hosting Guide.

Basic Example

  
    <title>My Networked-Aframe Scene</title>
    
    
    
    
  
  
    
      
        <template id="avatar-template">
           
        </template>
      
      
      
    
  

More Examples

Open in two tabs if nobody else is online, or remix the code examples yourself.

• Basic
• Basic with 4 clients
• Dance Club
• Google Blocks
• Tracked Controllers
• Positional Audio
• Nametags (not updated to latest version)
• Dynamic Room Name (not updated to latest version)
• Form to set room and username (not updated to latest version)
• More...

Made something awesome with Networked-Aframe? Let us know and we'll include it here.

Documentation

Overview

Networked-Aframe works by syncing entities and their components to connected users. To connect to a room you need to add the networked-scene component to the a-scene element. For an entity to be synced, add the networked component to it. By default the position and rotation components are synced, but if you want to sync other components or child components you need to define a schema. For more advanced control over the network messages see the sections on Broadcasting Custom Messages and Options.

Scene component

Required on the A-Frame `` component.

  ...

Property	Description	Default Value
serverURL	Choose where the WebSocket / signalling server is located.	/
app	Unique app name. Spaces are not allowed.	default
room	Unique room name. Can be multiple per app. Spaces are not allowed. There can be multiple rooms per app and clients can only connect to clients in the same app & room.	default
connectOnLoad	Connect to the server as soon as the webpage loads.	true
onConnect	Function to be called when client has successfully connected to the server.	onConnect
adapter	The network service that you wish to use, see adapters.	wseasyrtc
audio	Turn on / off microphone audio streaming for your app. Only works if the chosen adapter supports it.	false
video	Turn on / off video streaming for your app. Only works if the chosen adapter supports it.	false
debug	Turn on / off Networked-Aframe debug logs.	false

Connecting

By default, networked-scene will connect to your server automatically. To prevent this and instead have control over when to connect, set connectOnLoad to false in networked-scene. When you are ready to connect emit the connect event on the a-scene element.

AFRAME.scenes[0].emit('connect');

Disconnecting

To disconnect simply remove the networked-scene component from the a-scene element.

AFRAME.scenes[0].removeAttribute('networked-scene');

Completely removing a-scene from your page will also handle cleanly disconnecting.

Creating Networked Entities

  <template id="my-template">
    
      
    
  </template>

Create an instance of a template to be synced across clients. The position and rotation will be synced by default. The buffered-interpolation is added to allow for less network updates while keeping smooth motion.

Templates must only have one root element. When attachTemplateToLocal is set to true, the attributes on this element will be copied to the local entity and the children will be appended to the local entity. Remotely instantiated entities will be a copy of the root element of the template with the networked component added to it.

Example attachTemplateToLocal=true

Example attachTemplateToLocal=false

Parameter	Description	Default
template	A css selector to a template tag stored in ``	''
attachTemplateToLocal	Does not attach the template for the local user when set to false. This is useful when there is different behavior locally and remotely.	true
persistent	On remote creator (not owner) disconnect, attempts to take ownership of persistent entities rather than delete them	false

Deleting Networked Entities

Currently only the creator of a network entity can delete it. To delete, simply delete the element from the HTML using regular DOM APIs and Networked-Aframe will handle the syncing automatically.

Syncing Custom Components

By default, the position and rotation components on the root entity are synced.

To sync other components and components of child entities you need to define a schema per template. Here's how to define and add a schema:

NAF.schemas.add({
  template: '#avatar-template',
  components: [
    'position',
    'rotation',
    'scale',
    {
      selector: '.hairs',
      component: 'show-child'
    },
    {
      selector: '.head',
      component: 'material',
      property: 'color'
    },
  ]
});

Components of the root entity can be defined with the name of the component. Components of child entities can be defined with an object with both the selector field, which uses a standard CSS selector to be used by document.querySelector, and the component field which specifies the name of the component. To only sync one property of a multi-property component, add the property field with the name of the property.

Once you've defined the schema then add it to the list of schemas by calling NAF.schemas.add(YOUR_SCHEMA).

Component data is retrieved by the A-Frame Component data property. During the network tick each component's data is checked against its previous synced value; if the data object has changed at all it will be synced across the network.

Syncing nested templates - eg. hands

To sync nested templates setup your HTML nodes like so:

In this example the head/camera, left and right hands will spawn their own templates which will be networked independently of the root player. Note: this parent-child relationship only works between one level, ie. a child entity's direct parent must have the networked component.

Sending Custom Messages

NAF.connection.subscribeToDataChannel(dataType, callback)
NAF.connection.unsubscribeToDataChannel(dataType)

NAF.connection.broadcastData(dataType, data)
NAF.connection.broadcastDataGuaranteed(dataType, data)

NAF.connection.sendData(clientId, dataType, data)
NAF.connection.sendDataGuaranteed(clientId, dataType, data)

Subscribe and unsubscribe callbacks to network messages specified by dataType. Broadcast data to all clients in your room with the broadcastData functions. To send only to a specific client, use the sendData functions instead.

Parameter	Description
clientId	ClientId to send this data to
dataType	String to identify a network message. u is a reserved data type, don't use it pls
callback	Function to be called when message of type dataType is received. Parameters: function(senderId, dataType, data, targetId)
data	Object to be sent to all other clients

Transfer Entity Ownership

The owner of an entity is responsible for syncing its component data. When a user wants to modify another user's entity they must first take ownership of that entity. The ownership transfer example and the toggle-ownership component show how to take ownership of an entity and update it.

NAF.utils.takeOwnership(entityEl)

Take ownership of an entity.

NAF.utils.isMine(entityEl)

Check if you own the specified entity.

Events

Events are fired when certain things happen in NAF. To subscribe to these events follow this pattern:

document.body.addEventListener('clientConnected', function (evt) {
  console.error('clientConnected event. clientId =', evt.detail.clientId);
});

Events need to be subscribed after the document.body element has been created. This could be achieved by waiting for the document.body onLoad method, or by using NAF's onConnect function. Use the NAF Events Demo as an example.

List of events:

Event	Description	Values
clientConnected	Fired when another client connects to you	evt.detail.clientId - ClientId of connecting client
clientDisconnected	Fired when another client disconnects from you	evt.detail.clientId - ClientId of disconnecting client
entityCreated	Fired when a networked entity is created	evt.detail.el - new entity
entityRemoved	Fired when a networked entity is deleted	evt.detail.networkId - networkId of deleted entity

The following events are fired on the networked component. See the toggle-ownership component for examples.

List of ownership transfer events:

Event	Description	Values
ownership-gained	Fired when a networked entity's ownership is taken	evt.detail.el - the entity whose ownership was gained
		evt.detail.oldOwner - the clientId of the previous owner
ownership-lost	Fired when a networked entity's ownership is lost	evt.detail.el - the entity whose ownership was lost
		evt.detail.newOwner - the clientId of the new owner
ownership-changed	Fired when a networked entity's ownership is changed	evt.detail.el - the entity whose ownership was lost
		evt.detail.oldOwner - the clientId of the previous owner
		evt.detail.newOwner - the clientId of the new owner

Adapters

NAF can be used with multiple network libraries and services. An adapter is a class which adds support for a library to NAF. If you're just hacking on a small project or proof of concept you'll probably be fine with the default configuration and you can skip this section. Considerations you should make when evaluating different adapters are:

• How many concurrent users do you need to support in one room?
• Do you want to host your own server? Or would a "serverless" solution like Firebase do the job?
• Do you need audio (microphone) streaming?
• Do you need custom server-side logic?
• Do you want a WebSocket (client-server) network architecture or WebRTC (peer-to-peer)?

By default the wseasyrtc adapter is used, which does not support audio and uses a TCP connection. This is not ideal for production deployments however due to inherent connection issues with WebRTC we've set it as the default. To support audio via WebRTC be sure the server is using https and change the adapter to easyrtc (this uses UDP).

If you're interested in contributing to NAF a great opportunity is to add support for more adapters and send a pull request.

List of the supported adapters:

Adapter	Description	Supports Audio/Video	WebSockets or WebRTC	How to start
wseasyrtc	DEFAULT - Uses the open-easyrtc library	No	WebSockets	npm run dev
easyrtc	Uses the open-easyrtc library	Audio and Video (camera and screen share)	WebRTC	npm run dev
janus	Uses the Janus WebRTC server and janus-plugin-sfu	Audio and Video (camera OR screen share)	WebRTC	See naf-janus-adapter
socketio	SocketIO implementation without external library (work in progress, currently no maintainer)	No	WebSockets	npm run dev-socketio
webrtc	Native WebRTC implementation without external library (work in progress, currently no maintainer)	Audio	WebRTC	npm run dev-socketio
Firebase	Firebase for WebRTC signalling (currently no maintainer)	No	WebRTC	See naf-firebase-adapter
uWS	Implementation of uWebSockets (currently no maintainer)	No	WebSockets	See naf-uws-adapter

WebRTC in the table means that component updates is using WebRTC Datachannels (UDP) instead of the WebSocket (TCP). You still have a WebSocket for the signaling part.

See also the document NAF adapters comparison.

Audio

After adding audio: true to the networked-scene component (and using an adapter that supports it) you will not hear any audio by default. Though the audio will be streaming, it will not be audible until an entity with a networked-audio-source is created. The audio from the owner of this entity will be emitted in 3D space from that entity's position. The networked-audio-source component must be added to an entity (or a child of an entity) with the networked component.

To quickly get started, try the Glitch NAF Audio Example (not updated to latest version).

To mute/unmute the microphone, you can use the following API (easyrtc and janus adapters):

NAF.connection.adapter.enableMicrophone(enabled)

where enabled is true or false.

Video

After adding video: true (not needed for the janus adapter) to the networked-scene component (and using an adapter that supports it) you will not see any video by default. Though the video will be streaming, it will not be visible until an entity using a mesh (for example) with a `networked-video-source` is created. The video from the owner of this entity will be visible in 3D space from that entity's position. The `networked-video-source` component must be added to an child entity of an entity with the networked component.

This currently applies only to the easyrtc and janus adapters that supports the getMediaStream(clientId, type="video") API.

See the Video Streaming example that shows the user camera without audio.

To disable/reenable the camera, you can use the following API (easyrtc adapter only):

NAF.connection.adapter.enableCamera(enabled)

where enabled is true or false.

With the easyrtc adapter, you can add an additional video track like a screen share with the addLocalMediaStream and removeLocalMediaStream API:

navigator.mediaDevices.getDisplayMedia().then((stream) => {
  NAF.connection.adapter.addLocalMediaStream(stream, "screen");
});

NAF.connection.adapter.removeLocalMediaStream("screen");

See the Multi Streams example that uses a second plane with networked-video-source="streamName: screen" to show the screen share to the other participants. Be sure to look at the comments at the end of the html file of this example for known issues.

Misc

NAF.connection.isConnected()

Returns true if a connection has been established to the signalling server.

NAF.connection.getConnectedClients()

Returns the list of currently connected clients.

Options

NAF.options.updateRate

Frequency the network component sync function is called, per second. 10-20 is normal for most Social VR applications. Default is 15.

NAF.options.useLerp

By default when an entity is created the aframe-lerp-component is attached to smooth out position and rotation network updates. Set this to false if you don't want the lerp component to be attached on creation.

Stay in Touch

• Join the A-Frame Slack and add the #networked-aframe channel
• Follow changes on GitHub
• Let us know if you've made something with Networked-Aframe. We'd love to see it!

Help and More Information

• Getting started tutorial
• Edit live example on glitch.com
• Live demo site
• Networked-Aframe Adapters
• A-Frame
• WebXR
• Open EasyRTC WebRTC library
• Hayden Lee, NAF creator and previous maintainer
• Vincent Fretin is handling new contributions and releases since the version 0.8.0
• Bugs and requests can be filed on GitHub Issues

Folder Structure

• / (root)
  • Licenses and package information
• /dist/
  • Packaged source code for deployment
• /server/
  • Server code
• /examples/
  • Example experiences
• /src/
  • Client source code
• /tests/
  • Unit tests

Roadmap

• More examples!
• Add your suggestions

Interested in contributing? Open an issue or send a pull request.

License

This program is free software and is distributed under an MIT License.