Home

8 agora is platform where you can create and share virtual reality (VR) experiences. You can create and host your own VR world, explore other worlds, meet and connect with other users, attend or host live VR events and much more.

The 8 agora metaverse provides built-in social features, including avatar interactions, spatialized audio and interactive physics. Additionally, you have the ability to import any 3D object into your virtual environment. No matter where you go in 8 agora, you will always be able to interact with your environment, engage with your friends, and listen to conversations just like you would in real life.

What can I do?

You have the power to shape your VR experience in 8 agora.

  • EXPLORE by hopping between domains in the metaverse, attend events and check out what others are up to!
  • CREATE personal experiences by building avatars, domains, tablet apps, and more for you and others to enjoy.
  • SCRIPT and express your creativity by applying advanced scripting concepts to entities and avatars in the metaverse.
  • HOST and make immersive experiences to educate, entertain, and connect with your audience.

Home

8 agora is a platform where you can create and share virtual reality (VR) experiences. You can create and host your own VR world, explore other worlds, meet and connect with other users, attend or host live VR events and much more.

The 8 agora metaverse provides built-in social features, including avatar interactions, spatialized audio and interactive physics. Additionally, you have the ability to import any 3D object into your virtual environment. No matter where you go in 8 agora, you will always be able to interact with your environment, engage with your friends, and listen to conversations just like you would in real life.

What can I do?

You have the power to shape your VR experience in 8 agora.

  • EXPLORE by hopping between domains in the metaverse, attend events and check out what others are up to!
  • CREATE personal experiences by building avatars, domains, tablet apps, and more for you and others to enjoy.
  • SCRIPT and express your creativity by applying advanced scripting concepts to entities and avatars in the metaverse.
  • HOST and make immersive experiences to educate, entertain, and connect with your audience.

Explore

8 agora is a metaverse where you can connect and create with others. We invite you to explore VR worlds created in 8 agora and interact with other users. You can visit your friend’s VR world, meet people, attend events and even go for a class on avatar creation. It’s an immersive and interactive experience with realistic visuals and audio.

If its your first time using 8 agora, you’ll start your journey a local space by yourself, where you can experiment with the controls and learn about the product. When you are ready, try exploring other domains using the GoTo and socialize with people around the metaverse. If you’ve visited 8 agora before, you will return to the location where you last visited.

Throughout this chapter, learn how to make the most of your exploration:

Get Started with 8 agora

We know that getting started with a new application can be difficult: installing the software and learning the controls is never any fun. Hopefully, this section will help you become familiar with our application, so that you can begin making friends and exploring the metaverse.

In This Section

Install 8 agora

8 agora Client Installer comes with everything you need to view and interact with 8 agora’s content and users.

On This Page

Minimum System Requirements

In order to run 8 agora in either VR or Desktop mode, ensure that your computer meets these minimum system requirements:

  • Windows 10, 64-bit or MacOS High Sierra (10.13)
  • 8GB+ RAM i5
  • A wide range of Nvidia, AMD, and Intel graphics cards are supported

In addition, your network must have enough internet bandwidth to run 8 agora:

  • If you are using Interface only to explore the metaverse, then you must have internet speeds of at least 10 Mbps download/2 Mbps upload.
  • If you are hosting a domain on your Sandbox, you need to add 10 Mbps upload for each user you want to concurrently visit your domain.

Note

We also run on Linux devices; however, we do not publish an installer for Linux machines. To use 8 agora on Linux, you will need to build the application from our code base. For more information, see our Linux Build Guide.

Download 8 agora Installer

You can download 8 agora through Oculus store, Steam, or 8 agora’s website:

If you intend to use 8 agora in VR mode with a HMD, ensure that Steam VR is also installed on your system before launching 8 agora.

Install 8 agora

Once you’ve downloaded the installer, you’re ready to install 8 agora. The process will be different based on your operating system:

Windows Install

To install on Windows, simply double-click on the downloaded installer file to open it. Run through the prompts on the installer. Once you finish the install process, Interface will open, and you will be able to log in and begin exploring the metaverse.

Mac Install

At this time, the 8 agora installer for Mac is unsigned, so you will need give the OS permission to install and the application.

  1. Open the downloaded installer dmg file.
  2. Agree to the License Agreement.
  3. Drag 8 agora to the Applications folder.
  4. Open System Preferences > General.
  5. Next to the warning indicating that Interface is blocked, click ‘Open Anyway’.
  6. Confirm that you want to open the application.

At this point, Interface will open and you will be able to log in and begin exploring the metaverse.

Upgrade 8 agora

8 agora is always changing, as we work to improve performance and add features that will enhance your experience in the metaverse. If a new version has been released, you will be prompted to upgrade your installation the next time you run 8 agora. At any time, you can also download the latest release from our website.

You cannot upgrade if Sandbox or the Console is running in the background of your computer. Be sure to quit these applications before upgrading.

  • For Windows, locate the 8 agora app in your system tray. Right-click on the icon and select ‘Quit’. Alternatively, end the ‘server-console’ background process using the Task Manager.
  • For OS X, locate the 8 agora icon in the menu bar. Click on the icon and select ‘Quit’.
Perform a Clean Install

If you’re facing problems when you load Interface and Sandbox, you can try performing a clean install. A clean install removes multiple files and settings that you may need once you install 8 agora again.

Note

Ensure that you back up the following files before a clean install: Favorites, Wearables, Sandbox, and Entities. These settings will be deleted during the clean install.

Windows Clean Install
  1. Click on the Start menu and type “Add or Remove Programs” in your Windows search bar.
  2. Uninstall any versions of 8 agora that are visible (Including any Steam installs).
  3. Once 8 agora is uninstalled, browse to your %Program Files% directory. Delete all folders related to 8 agora. If you installed through Steam, these folders will be located at C:/Program Files(x86)/Steam/steamapps/common.

Warning

The next 3 steps will permanently delete your Sandbox content. If you wish to keep this content, copy %AppData%/Local/8 agora/assignment-client to another location on your computer before proceeding. Repeat for %AppData%/Roaming/8 agora/assignment-client.

  1. Browse to your local %AppData% folder (usually C:/Users/<your_username>/AppData/Local). If you do not see the folder, make sure you can view hidden folders. In File Explorer, click View and make sure “Hidden Items” is checked. Delete all folders related to 8 agora.
  2. Browse to your roaming %AppData% folder (usually C:/Users/<your_username>/AppData/Roaming). Delete all folders related to 8 agora.
  3. Re-install 8 agora using the steps above. To restore your Sandbox content, copy the assignment-client folders you backed up back to their respective locations.
Mac Clean Install
  1. Open your Applications folder and delete the 8 agora folder.
  2. Open the <username>/.config folder. This is a hidden folder than is accessible by going to Go > Home. Press the keyboard shortcut Command + Shift + . (period).
  3. Delete the 8agora.com folder.
  4. Open the ~/Library folder by holding the Option key and clicking the ‘Go’ menu while in the Finder. The Library option should appear in the menu.
  5. Browse to ~/Library/Application Support and delete the 8 agora folder.
  6. Empty the Trash.
  7. Re-install 8 agora using the steps above.
Understand the Architecture

8 agora’s architecture shows how different parts of the system work together to give you the best VR experience.

On This Page

Architecture Overview

8 agora’s architecture consists of the following components that work together and send data to each other for your VR experience.

8 agora Interface

The 8 agora Interface (or simply ‘Interface’) is the main user interface for 8 agora. It is used to explore the metaverse and engage with people from around the world. When you enter a domain, your Interface connects with the domain server that is hosting the virtual world, alongside any global services.

You can download and use the Interface on your computer or your Android phone using the Client-Only Installer.

Physics Engine

Your VR experience won’t be realistic without some physics. 8 agora includes a physics engine that simulates behaviors of objects according to the Newtonian laws of physics. When an object falls to the ground and bounces, or when two or more objects collide, their movements are computed by the physics engine.

Each Interface runs its own physics engine, and the entity server coordinates the results to produce a consistent simulation across the entire domain.

Domain Server

A domain is a spatial simulation in 8 agora that you can visit. It is computed by a stack of programs on one or more computers. You need a domain’s place name to visit a domain, just like you would need a web address to visit a website.

You can set up your own domain and host it on your local machine or on a cloud server to make it available to other users. Your domain’s server stack is a set of components that simulate and manage different aspects of the domain such as audio, entities, and avatars. Everything that you see, hear, and do in your domain is managed by the server stack.

_images/domain-server.png
Server Stack

The Domain Server is at the top of this stack and its job is to give out assignments to the other components. These components are called Assignment Clients, because from the perspective of the domain server, they are clients that take on different roles.

The server stack is not only controlling, managing and computing your domain as you see it, but also how it is seen by anyone visiting your domain. This means that the domain server hands out simulation assignments and provides their IP addresses to connecting Interface clients. The domain server is a single executable that spawns assignment clients that become the different mixers as requested. Each assignment client can function as one of the six types mentioned. The domain server determines which assignment client functions as which mixer.

Assignment Clients

Assignment clients control and manage various aspects of a domain. They also communicate directly with the Interface clients connected to a domain. There are six types of assignment clients:

Assignment Client Description
Avatar Mixer This mixer is in charge of your virtual presence in any domain. It keeps track of where you are, which avatar you’re wearing, and how you move around the domain. For example, it tracks how you move your head while wearing a Head Mounted Display (HMD).
Audio Mixer Mixes all sounds, whether it’s voice or environmental. And it does this not just for avatars, but also for all the entities in a domain. The Audio mixer can customize a stereo mix for you based on your position relative to the audio source.
Entity Server Tracks all entities and their properties in a domain, from their description and position, to any behaviors attached to them in a script. If an entity is modified, the change is communicated to the entity server, which in turn relays the information to all clients currently visiting the domain.
Asset Server Provides copies of the models, audio files, scripts, and other media used by the domain. It functions like a Web server, but using protocols tuned to 8 agora’s architecture.
Agent Executes user-written JavaScript programs. If you’ve written a script to get your avatar to clap, or create a bowling alley, the Agent will execute it. It can see entities, avatars, and send audio.
Messages Mixer Provides communication between scripts running in different programs connected to the domain, which could be Interfaces or Agents.

Note

Sandbox manages all these components on the domain server, five dedicated assignment clients, and as many agent assignments clients as needed. However, it is possible to spread the assignment clients over multiple computers, and even to divide each function among a hierarchy of assignment components, which may be on different computers. For instance, multiple audio mixers could be used to mix the audio in different geographic regions of the domain.

Global Services

8 agora maintains global services to connect different servers together.

See Also

Set Up Your Audio Devices

When you log into 8 agora for the first time, we will automatically detect your computer’s default audio devices, and use those for 8 agora. Usually, your computer will automatically detect a plugged in headset and you will not need to configure your audio devices any further.

However, some audio setups do require additional configuration. If you need to change your audio settings, read on to find out more.

On This Page

Audio “At a Glance”

Your basic audio settings are displayed in the top-left corner of your Interface window. This is called the “Audio Level Meter” and can be turned on or off in your Audio settings (from the Tablet or HUD, click Audio).

_images/audio-settings.png
Change your Input or Output Device

8 agora’s 3D spatialized audio is guaranteed to enhance your experience in the metaverse, whether you are in Desktop mode or using VR equipment. By default, we will select the default audio devices that your operating system or headset has detected. If you want to use a different headset or audio setup than the default, you can change your computer’s default device. If you need to use a different device for 8 agora than other applications on your computer, then you can change your device in the application.

  • An audio input device is any device that captures sound and generates a signal that can be accessed by other devices. Examples of audio input devices include a USB microphone or a microphone headset that is plugged into your computer, or your sound card’s “Stereo Mix” or “What U Hear” device (think of these sound card devices as if they were microphones being held up to your speakers while they output sound).
  • An audio output device is any device that receives information from audio files and converts it into audible sound signals. Examples of audio output devices include your desktop computer speakers, headphones, or huge speakers in a movie theater.

If you are using a headset with a microphone, then your input and output devices will likely be the same device. However, if you are using external speakers or some other open mic setup, then these devices may be different. In these cases, we encourage you to enable acoustic echo cancellation for improved audio quality.

To change your audio devices:

  1. From the Tablet or HUD, click Audio.
  2. Choose your desired input device.
  3. Choose your desired output device.
Using Bluetooth Headsets

You can use bluetooth headsets, such as AirPods with 8 agora. However, note that there are limitations to using them, and they may not work in all environments. If using WiFi, ensure you’re using a 5Ghz WiFi connection. On a 2.4Ghz connection, you may experience audio breakup and occasional disconnects.

Unfortunately, bluetooth audio devices do not currently support stereo input. Therefore, you have two options:

  • Use the bluetooth headset as an output device only, and use another microphone for input. This allows you to take advantage of the stereo audio.
  • Use the bluetooth headset’s built-in microphone. In this case, you will only experience mono sound, rather than 8 agora’s stereo audio.
Acoustic Echo Cancellation

Acoustic echo is the process by which sounds from your speakers get picked up and transmitted by your microphone, resulting in an echoing effect. This is common when you use 8 agora with a laptop’s built-in microphone and speakers (i.e. an “open mic”), rather than a detached headset.

“Acoustic echo cancellation” is a technology which improves voice quality by preventing the echo that results in open mic setups. By default, acoustic echo cancellation is turned on, and you can turn it off in the Audio app.

Note

Acoustic echo cancellation will not run when using input devices with high sample rates (greater than 96khz) or more than 2 channels.

For best performance with open mic setups, ensure that you:

  • Disable any processing and effects on the input and output devices. This includes:

    • On Mac: Turn off ‘Ambient noise reduction’ (System Preferences > Sound > Input > Use ambient noise reduction)
    • On Windows: Turn off all ‘Enhancements’ (Control Panel > Sound > Recording tab > click on your device > Properties button > Enhancements tab)

  • On Mac devices, set the balance of the output device to either the left or the right (System Preferences > Sound > Output > Balance)

  • Lower the microphone’s physical gain setting to approximately 3/4 of the maximum

  • Lower the speaker’s physical volume level to approximately 3/4 of the maximum

  • If you are not using your laptop’s audio devices, move and point the microphone away from the speakers

The acoustic echo cancellation technology picks up the sounds around you and attempts to identify the echoing sounds as you use it. This means that it will improve and become more accurate over time. So don’t despair if you hear a little bit of echoing…it will lessen as the technology learns your voice and the voices of the people around you!

To speed up this “learning” process, you can:

  • Avoid turning your avatar while talking
  • Leave your microphone muted while another person talks for 10 seconds at a time
Test Your Audio Devices

Audio is an integral part of social VR experience, so of course, we want to make sure that your devices are working correctly and that everyone can hear you! There’s nothing more annoying than walking up to a group of friends in a virtual world, only to realize that they haven’t heard a word you said! The good news is that you can test your audio setup to make sure that both your input and output devices are working correctly.

Note

The ‘Test Your Voice’ feature does not automatically mute your voice! We recommend muting yourself prior to checking your voice input if you do not want others to hear your microphone check.

  1. From the Tablet or HUD, click Audio.
  2. Click ‘Test Your Voice’ to test your input device. Speak into your mic, and the sound will be played right back at you through the selected output device. Make any adjustments to your input device to achieve your desired sound.
  3. Click ‘Test Your Sound’ to test your output device. Adjust the headset and/or application volume until the sound is a comfortable volume.
Adjust In-World Volume

There are three different types of “sounds” in 8 agora:

  • People: The sound you hear when people in the domain are talking through their microphones
  • Environment: The ambient sounds in the domain, running as scripts in the background
  • System Sound: The sound your computer makes as you interact with the application window (such as the “clicking” you hear when you hover over an icon)

To change the volume of all of these at once, simply change the volume of your headset or output device.

To change one or more of these sound types independently of the others:

  1. From the Tablet or HUD, click Audio.
  2. Choose ‘Desktop’ or ‘VR’ depending on the mode you are in.
  3. Scroll down to ‘Choose Output Device’.
  4. Adjust the sliders to the desired volume levels for each of the sound types.
Enable Push to Talk (PTT)

‘Push to Talk’ is like having a walkie talkie in your hand. You need to press a button to have others hear you in the environment. When you’re not pressing the button, you are muted and will not be heard.

To turn on ‘Push to Talk’:

  1. From the Tablet or HUD, click Audio.
  2. Choose ‘Desktop’ or ‘VR’ depending on the mode you are in.
  3. Toggle ‘Push to Talk’ on.

In Desktop mode, press and hold the “T” key on your keyboard to talk. When using an HMD in VR mode, press and hold the grip triggers on your controllers to talk. This feature works only when you are focused on the Interface window.

Adjust 8 agora Audio Settings

There are a number of settings you can configure to customize your audio experience in 8 agora. To change these, open your Tablet or HUD and go to Audio.

Setting Description
Mute microphone Mute or unmute your microphone.
HMD Mute Warning (VR) Enable to receive a warning when your microphone is muted when wearing a HMD device.
Noise reduction Enable to turn on noise reduction. This removes outside noise from audio signals.
Audio level meter By default, the audio level meter is visible on the top left corner of your screen. Uncheck this box to hide the meter.
Echo Cancellation Enable or disable acoustic echo cancellation.
Stereo input Enable or disable stereo input. Stereo reproduces sound using two or more audio channels. This means that you will hear sound from various directions, like how you would in the real world.
Adjust OS Audio Settings

Many device settings, such as input levels, boost, gains, and enhancements, cannot be set in 8 agora. These settings can only be adjusted at the operating system level or with a device’s external software. If you experience issues with audio that cannot be resolved with any of the above settings, then try adjusting your operating system’s device settings:

  • Update the driver software for your audio devices:

    • On Mac: Apple handles all driver updates on your computer. To check for updates, click on the Apple icon in the top-left corner of the screen and select ‘Software Update’.
    • On Windows: Open the Device Manager and select the arrow next to Sound, audio and game controllers. Right-click on your audio device and select ‘Update driver’.

  • Adjust microphone levels and/or boost:

    • On Mac: Go to System Preferences > Sound > Input.
    • On Windows: Go to Control Panel > Sound > Recording. Choose your microphone and click ‘Properties’.

  • Adjust other advanced sound settings:

    • Go to Control Panel > Sound
    • Go to Settings > System > Sound
    • Go to Control Panel > Hardware and Sound > Adjust System Volume
Use Your VR Equipment

To get the best and most immersive experience in 8 agora, we encourage you to use VR equipment, such as the Oculus Rift or HTC Vive. With these HMD devices and hand controllers, you will be able to interact with people in 3D, track body movements, and engage with the objects around you. We support the following VR equipment:

Head Mounted Displays Hand Controllers
Oculus Rift (CV1 and S) Oculus Touch
HTC Vive HTC Vive
Windows MR XBox One Controller

On This Page

Comfort Mode

Motion sickness is a real problem for many people when they put on a HMD and enter VR. This happens because your eyes experience movement in VR, while your body stands still. If you experience motion sickness and discomfort using VR equipment, you are not alone.

“Comfort mode” is designed to decrease the effects of motion sickness while using 8 agora. This mode:

  • Disables sharp turns
  • Decreases your field of vision by darkening the edges of the screen
  • Adds a ground plane and grid

All of these features were developed to help you orient yourself when moving around in VR.

To enable comfort mode, go to Menu > Settings > Controls on your tablet. Use the slider to adjust how much of the environment you see in VR.

_images/comfort-mode.png
Change How You Move in VR

You can change many avatar movement settings in VR such as jumping, flying, and leaning behavior. To do so:

  • In Desktop mode, go to Settings > Controls in the menu bar.
  • In VR mode, open your Tablet and go to Menu > Settings > Controls.
Setting Description
VR Movement > Teleporting Enables teleport controls to move seamlessly between positions within a domain.
VR Movement > Walking Enables walking controls to move within a domain.
VR Movement > Strafing Enables strafing controls (to walk sideways).
VR Movement > Jumping and flying Enables jump and fly controls.
VR Movement > Movement Direction

This setting controls which direction you move in:

  • HMD-Relative: Move in the direction your head is pointing.
  • Hand-Relative: Move in the direction your dominant hand is pointing.
  • Hand-Relative (Leveled): Move in the direction your hand is pointing, without taking pitch into account.
VR Movement > Dominant Hand Select ‘Left’ or ‘Right’. Teleport and turn controls move to the controller in the dominant hand.
VR Movement > Rotation Mode

This setting controls how you turn in VR:

  • Snap turn: Rotate your avatar sharply to the left or the right.
  • Smooth turn: Rotate your avatar smoothly as you turn to the left or right.
  • Comfort mode: Enable comfort mode and decrease the field of vision while moving in VR mode.
VR Movement > Control Scheme Selection

This setting determines how you control your walking speed:

  • Default: Your walking speed will remain the same, no matter how far forward you push your controller’s joystick. Fully pushing the joystick forward will make your avatar run.
  • Analog: Your walking speed changes based on how far forward you push your controller’s joystick. Fully pushing your joystick forward will make your avatar run.
  • Analog++: Your walking speed changes based on how far forward you push your controller’s joystick. You can use the slider to change the maximum walking speed in meters/second. Fully pushing your joystick forward will make your avatar run.
VR Movement > Avatar leaning behavior

This setting controls if and when your avatar leans in VR mode.

  • Auto: This is the default setting. Your avatar will lean if you are standing in the real world.
  • Seated: Your avatar will not lean if you are sitting in the real world.
  • Standing: Your avatar will lean if you are sitting in the real world.
  • Disabled: Your avatar can sit on the floor (experimental).
User real world height (in meters) You can change your real world height for better tracking in VR mode.
Motion Capture Using Vive Trackers

You can enhance your 8 agora experience using full body motion capture (mocap). 8 agora currently supports mocap using HTC Vive Trackers.

Vive trackers need to be strapped to the body part you wish to track. You can replace the HMD and hand controllers with trackers if you only need to track the movement of your head and hands.

You can set up different mocap systems:

Mocap System Equipment Needed Recommended Straps
Head HMD or 1 Vive Tracker Head strap for Vive Tracker
Hands Hand controllers or 2 Vive Trackers Hand strap for Vive Tracker
Head + Hands + Feet 2 Vive Trackers + HMD + 2 Hand Controllers Foot straps
Head + Hands + Feet + Hips 3 Vive Trackers + HMD + 2 Hand Controllers Hip Strap: Drill a hole in the back of a thick leather belt and attach the tracker using a 1/4” screw.
Head + Hands + Feet + Hips + Chest 4 Vive Trackers + HMD + 2 Hand Controllers Chest straps
Head + Hands + Feet + Hips + Shoulders 5 Vive Trackers + HMD + 2 Hand Controllers Shoulder straps

Note

You can replace the HMD and hand controllers with trackers if you only need to track the movement of your head and hands.

_images/tracker-placement.jpg
Configure Your Mocap System

  1. Strap your Vive trackers to your body as shown in the image.

  2. Connect your trackers, HMD, and controllers to SteamVR.

  3. In Interface, pull up your HUD or Tablet and go to Menu > Settings > Calibration.

  4. Configure your mocap system by:

    • Selecting the right device for your head and hands. If you’re using a head tracker instead of an HMD, click ‘Use HTC Vive Devices in Desktop Mode’.
    • Selecting the body position of any additional trackers.
    _images/vive-config.PNG

  5. Click ‘Apply and Calibrate’.

  6. Stand in a T-Pose until the timer counts down to zero:

    • Feet together
    • Arms out
    • Head looking straight ahead.

  7. Check to see that each tracker is tracking the corresponding joint on your avatar.

  8. You can also calibrate your trackers without using your tablet. Once you apply your configuration, stand in a T-Pose and hold the following four buttons together for 1 second: Left Trigger, Right Trigger, Left Menu Button, Right Menu Button. You can press the same buttons together for a second to remove your calibration from the trackers.

Note

When you setup your Vive, you choose which way to point the arrow as your reference. During calibration, it is important that you face the same direction. If you can not remember the arrow’s direction, press the Vive System Menu Button and look on the ground for a marker. This is important to make sure your joints are oriented correctly.

Troubleshooting
Issue Troubleshooting Steps
My calibration failed
  • Check if your trackers are properly connected in SteamVR.
  • Have you selected the correct configuration in your tablet and do you have enough number of trackers to support that configuration?
  • If you are performing and not in HMD, did you select to ‘Use HTC Vive in Desktop Mode’?
  • Are any of the trackers blinking? If so, they may need to be paired again.
  • Do you have the correct number of dongles plugged in to your computer? You will need one dongle per tracker. If you are performing with all 7, then you may need a USB hub to handle them.
My sensor is jiggling a lot Make sure the straps on the sensor are tightened.
My sensor keeps losing tracking
  • If it’s the hip tracker, is your shirt is tucked in and not covering the puck? Also make sure your headphone cord isn’t covering the puck.
  • Can the base stations clearly see the tracker?
  • Is the signal from the base station conflicting with another Vive setup nearby?
  • Are you clear of reflective surfaces nearby? (such as picture frames, whiteboards, shiny tables).
  • Is the lighting consistent across the room (minimal outdoor lighting)?
  • Try restarting SteamVR.

Note

Remember to charge your trackers when you aren’t using them so that you don’t have to deal with a low battery tracker negatively impacting your performance.

Gamepad

If your HMD does not come equipped with hand controllers, you can use a gamepad. However, 8 agora is best experienced with VR equipment or the keyboard in Desktop mode.

_images/controls-gamepad.png

See Also

Explore in Desktop Mode

Desktop users are restricted to using their keyboard and mouse to do things in 8 agora. On this page, you can find all of the shortcuts so that you can enjoy your experience in 8 agora to the fullest.

Note

The shortcuts below are for Windows and Linux computers. If you’re running on a Mac, use the same commands, substituting the Command key for the Ctrl key.

On This Page

Movement Controls
_images/controls-keyboard.jpg
Action Key
Walk Forward W or UP ARROW
Walk Backward S or DOWN ARROW
Run Hold SHIFT while using any shortcut to walk
Side Step to the Left Q or Right Click + A or SHIFT + LEFT ARROW
Side Step to the Right E or Right Click + D or SHIFT + RIGHT ARROW
Turn Left A or LEFT ARROW
Turn Right D or RIGHT ARROW
Jump SPACE or PGUP
Fly Hold SPACE or PGUP
Fly Down C or PGDN
In-World Controls
Action Key
Handshake X
Toggle Privacy Shield CTRL + N
Open Tablet TAB (when ‘Desktop becomes toolbar’ is not checked)
Select Item Left Click
Grab Item Left Click
Inspect Item Right Click
Open Browser CTRL + B
Toggle ‘Away from Keyboard’ ESC
Toggle ‘Mute Mic’ CTRL + M
Toggle ‘Show Statistics’ /
Screenshot P
Push to Talk T
Camera Controls
Action Key
First Person View 1
Third Person View 3
Mirror View 2
Pan In/Out

With mouse, use mouse wheel.

On trackpad, drag two fingers up or down.
Take Screenshot P
Avatar Sizing Controls
Action Key
Decrease Avatar Size -
Increase Avatar Size +
Reset Avatar Size =
Create and Edit Mode

These controls work when the Create app is open.

Action Key
Undo CTRL + Z
Redo CTRL + Y
Delete Entity DEL
Focus on Selected Entity F
Align Grid to Bottom of Selected Entities G
Duplicate Entity CTRL + Left Click + Drag
Parent Entity CTRL + P
Unparent Entity CTRL + SHIFT + P
Copy Entity CTRL + C
Paste Entity CTRL + V
Toggle Global/Local Translation T
Gamepad

Instead of a keyboard, you can use a gamepad while experiencing 8 agora in desktop mode.

_images/controls-gamepad.png
Adjust Your Settings

You can adjust various settings in 8 agora so that it runs to your preferences. Many of these settings are changed using the HUD (in Desktop mode) or Tablet (in VR mode).

On This Page

The Tablet and HUD

In VR, all of your settings are found in your Tablet. The Tablet also gives you easy access to any apps that you install. Pull up the tablet by clicking the menu button on your controller.

_images/tablet.png

In Desktop Mode, you have the option to use either the Tablet or a smaller version called the “Heads-up Display” or HUD. It contains the exact same options as the Tablet (settings, apps, etc), but it takes up less space on your screen. To enable the HUD, first enable the Developer menu by going to Settings > Developer Menu. Then, go to Developer > UI > Desktop Tablet Becomes Toolbar.

_images/hud.png
Enter or Exit VR Mode

You can enjoy 8 agora with or with VR equipment such as head mounted displays (HMD), hand controllers and audio headsets. Our Desktop mode contains many of 8 agora’s features such as audio, basic movements and gestures, and the ability to travel to different domains.

Keep in mind, however, that the most immersive and powerful experience is when you use VR equipment. Only then will you be able to interact with people in 3D, track body movements, and easily engage with the objects around you. Once you have set up your VR equipment, you can easily switch between VR mode and Desktop mode. To switch to VR mode, use one of the following methods:

  1. From the HUD, click Enter VR.
  2. Click the Display menu, then select your VR device.

To exit from VR mode, remove your headset, click Exit VR on the HUD or press ESC on your keyboard.

Set Your Perspective

You can choose how you view things around you by changing your perspective. To change your perspective:

  • In Desktop mode, go to View in the menu on the top left corner.
  • In VR mode, open your Tablet and go to Menu > View.
Setting Description
First Person Select this setting if you want to change your perspective in 8 agora to first person. In this view, you will not see yourself, only the environment around you.
Third Person Select this setting to change your perspective to third person. In this view, you will see yourself, as well as the environment around you.
Selfie Select this to change your perspective to look at yourself. In this view, you will see yourself and the space behind you.
Independent Mode Select this to change what you see through scripting instead of avatar’s movements.
Entity Mode Select this to set your perspective to a specific entity, allowing you to move with entity as it moves.
Other Miscellaneous Settings

Here are some other settings you may like to change to optimize your experience.

General Settings

You can modify general settings such user interface and privacy settings in 8 agora.

  • In Desktop mode, go to Settings > General in the menu on the top left corner.
  • In VR mode, open your Tablet and go to Menu > Settings > General.
In-World Graphics Settings

You can make changes to the graphics in 8 agora.

  • In Desktop mode, go to Settings > Graphics in the menu on the top left corner.
  • In VR mode, open your Tablet and go to Menu > Settings > Graphics.
Setting Description
Graphics Settings Choose the graphics settings for your computer tier. In general, a lower graphics setting sacrifices artistic details and rendering effects for increased performance and optimization. Custom lets you configure the world detail, rendering effects, refresh rate, and resolution yourself.
World Detail Control the level of detail visible to you in 8 agora by moving this slider.
Rendering Effects Choose the level of rendering effects that are present in 8 agora. Local lights, fog, bloom, and shadows are all examples of rendering effects.
Refresh Rate Choose the frequency that 8 agora updates its graphics buffers. Most mid-range computers run well on ‘Interactive’.
Resolution Adjust the resolution using the slider. This affects how clear 8 agora appears on your monitor or screen.
Account Security Settings

You can change your account security settings in 8 agora.

  • In Desktop mode, go to Settings > Security in the menu on the top left corner.
  • In VR mode, open your Tablet and go to Menu > Settings > Security.
Setting Description
Account Enable to stay logged in (in the current device) even if you exit 8 agora.
Secure Transactions Change your security picture.

On This Page

Visit Different Worlds

8 agora has many virtual places where you can interact with other users and participate in various activities or events. We have modified several of 8 agora’s most popular virtual worlds to make them more accessible to Android users.

Find these domains by going to the Home tab in the menu.

_images/android-app.png
Movement Controls
Action Controls
Walking When exploring a virtual world, use the arrows in the bottom left corner to turn and/or walk.
Turning Drag your finger left or right across the screen to make your avatar turn.
Look up/down Drag your finger up or down to change the angle of the camera.
Flying Press the button on the bottom right with the winged avatar to fly (the longer you hold it, the higher you go!).
In-World Controls
Action Controls
View Switch to a bird’s eye view camera by pressing the My View button on the top right corner of the screen.
Mute Your avatar in muted by default when you open the app. Press the mic button on the top right corner to unmute.
Avatar Controls
Action Controls
Change Your Avatar Change your avatar to one available in the list in the Avatar tab in the menu.
Set Display Name Set your display name in the Avatar tab in the menu
Discover and Make Friends
Action Controls
Handshake Add people to your Connections by shaking their hand. Press the handshake button which is above the flight button in the bottom right corner of your screen.
Connections List Open the People tab in the menu to view your Connections.

Additional functionality such as opening the Tablet, using the Create Tools app, adding wearables, etc. are not yet available.

See Also

Personalize Your Experience

Before you even enter 8 agora, there are many ways to personalize your experience and make it your own. You can customize everything from the hardware you use, to the way the app works, to how you appear to others.

In This Section:

Change Your Avatar

When you first use 8 agora, you will be wearing the default avatar, Woody. Your avatar is a representation of you in the metaverse. You can control how your avatar moves and speak to other users in-world using it.

On This Page:

Use Your VirtualYou Avatar

VirtualYou: 3D Avatar Creator is 8 agora’s mobile app developed with the help of our friends at Wolf3D. In just a few easy steps, you can create a 3D avatar that looks like you in less than five minutes. The app creates your avatar based on a selfie that you take from your phone’s camera. You can then select customize your hair, face and body attributes, and choose your outfit. Download the app from the Apple or Google Play stores.

At the end, log in to 8 agora to upload your new avatar to your account.

To wear your VirtualYou avatar:

  1. In Interface, pull up your Tablet or HUD and go to Inventory.
  2. Click on the ‘Items’ tab.
  3. Locate your VirtualYou avatar and click ‘Wear’.
Use Your Own Custom Avatar

You can use an avatar that you created. Learn more about how you can create your avatar here.

Note

All avatars must be hosted in the cloud before they can be used with 8 agora. Examples of cloud storage options include Amazon S3, Google Cloud Storage, GitHub, or Microsoft Azure.

Once you have your avatar’s .fst file, you can upload it.

  1. In Interface, pull up your tablet or HUD and click on Avatar.
  2. In the Avatar window, click the link icon next to your current avatar. _images/avatar-link.png
  3. Enter the .fst file’s URL and click ‘Confirm’.
  4. If you want to access this avatar later without loading the .fst file information again, you can click on ‘Add to Favorites’ to save the current avatar information.

See Also

Put On Wearables

You can customize your avatar’s appearance by adding wearables, such as a pirate’s hat, a pair of sunglasses, or even a pair of trousers that you designed.

On This Page

Wear Your Own Wearable

You can put on a wearable that you created. All wearables must be hosted in the cloud before they can be used with 8 agora. Examples of cloud storage options include Amazon S3, Google Cloud Storage, GitHub, or Microsoft Azure.

Once you know the URL for your wearable’s FBX file, then put it on your avatar:

  1. In Interface, pull up your tablet or HUD and click on Avatar.

  2. In the Avatar window, click the hat icon next to ‘Wearables’.

    _images/add-wearable.png

  3. Click ‘Add custom’ at the top of the window.

  4. Enter the .fbx file’s URL and click ‘Confirm’.

  5. Select the joint you’d like to use for your wearable. For example, a hat would be on your head, and fairy wings would be on your spine.

  6. Fine tune the placement using the ‘Position’ and ‘Rotation’ options.

  7. Check ‘Is soft’ if the item is rigged with your skeleton. This allows the item to move and bend with the avatar as it moves.

  8. Click ‘Save’.

See Also

Socialize with Others

8 agora is all about the people you meet and the experiences you have with them. 8 agora enables people connected by interest, community, and friendship to come together from anywhere in the world.

On This Page

Make Connections and Friends

In 8 agora, you can establish a connection with someone else by shaking hands with them. With your hand controllers, place your hands near each other and hold the grip button. Desktop users can press and hold X on their keyboard.

Once you make a connection with someone, they will appear under Connections in the The People app. You will also appear on their list of connections. You will be able to see where they are in the metaverse, and you can travel to them at any time.

To mark a connection as a friend, check the box next to their name in the People app. You can make yourself available to only your friends using the People app.

_images/make-connection.png
The People App

The People app provides a set of tools that help users manage their interactions with people in the metaverse. It gives you a list of the people nearby (in the same domain as you), and gives you easy access to all of your connections. From the People app, you can:

Feature Description
Profile Picture This is where your profile picture will be visible. Click on the image to view your profile. You can change this image on our website.
Display Name You can change your display name at any time. By default, it will be ‘anonymous’. In the image above, the display name is ‘HiFi Docs’.
Set Availability This feature allows you to appear online to select groups of users: Everyone, Friends and Connections, Friends Only, or Appear Offline. The users you appear online to will also be able to teleport to your location.
Master Volume Set the volume of your audio in 8 agora.
Nearby This is the list of users who are nearby in the same domain as you.
In View You can check this box to view only the users in front of you in a domain. This is useful when a domain has a lot of users.
Refresh Button Click this button to refresh the list of users currently in the domain.
Connections This is the list of users who are your friends and connections. You can also teleport to their location from this list.
Loud Click this icon next to the user you want to mute. The user will be muted only for you, not for other users in the domain. The icon also displays how loudly a user is speaking.
Names This is the list of users available in the domain. You will only see their display names.
Ignore If you check this box next to a user, you and the user will not be able to see or hear each other.
Use the People App as an Admin

As an administrator in a domain, you will have privileges to maintain a domain. The People app will have an additional column that allows an admin to silence and ban users in the same domain.

_images/people-admin.PNG
Feature Description
Silence You can click the icon to mute a user. This user will be muted for everyone in the domain.
Ban You can click here to ban a user from the current domain. The user will not be able to enter the domain using the same account. The banned user will still have access to other High Fidelity domains.
Your Privacy Shield

You can enable a privacy shield that protects your personal space in the metaverse. When it is enabled, other people will disappear if they get too close to you. Your privacy shield is disabled by default. To enable it, pull up your tablet or HUD and click Shield. In Desktop mode, you can also use the keyboard shortcut CTRL + N.

There is also a Shield icon on the top-left corner of your Interface window, next to the audio icon, that can be used to toggle your privacy shield.

_images/privacy-bubble.png
Attend Live Events

One of the great things about virtual reality is that you can attend events. 8 agora regularly hosts events such as workshops, lectures on VR, and town hall meetings to meet our team. Click here to view all upcoming events. Events are a great place to meet others and share experiences with others around the world.

To attend an event, simply go to the hosted domain at the time of the event.

Express Yourself

There are many ways you can express yourself in 8 agora, such as animating the mouth of your avatar or using gestures in the Emote app.

By default, all avatars will use a standard set of animations, such as your eyes blinking or your mouth opening and closing as you talk. When you are using a VR controller, your avatar will automatically mimic your hand gestures and movements.

The Emote App

The Emote app is a way for desktop users to express themselves without using VR controllers. With this app, you can display feelings by: crying, acting surprised, dancing, cheering, waving, falling, pointing, clapping, sitting, or showing love.

_images/emote-app.png

Travel Between Worlds

8 agora is made up of many virtual places that let you participate in activities and interact with the people around you. Many of these places are beautifully detailed worlds that are interesting to explore at any time, while others were built to host events and engage with the people around you.

Interact with Your Environment

In 8 agora, your experiences are shaped the world around you. When you enter a domain, all of the space around you is built with entities, or the building blocks of your environments. The walls of your room, the tree in the distance, or the animated butterfly that flew past are all entities.

Just like in the real world, you can interact with your environment by grabbing items or colliding with objects.

On This Page:

Grab Objects

You can grab objects in 8 agora using your mouse or hand controllers. You can grab an entity, hold it, throw it, and drop it depending on the entity’s properties.

  • In Desktop mode, click and hold the left mouse button to grab and hold an entity.
  • In VR mode, reach out towards the object and press the Grab button. The location of this button depends on the controllers you are using.

_images/grab-button.png

Note

Some entities cannot be grabbed. For example, a domain owner will not give you permission to grab and move a wall in their building. When creating your own entities, you can set the Grabbable property to define whether or not it can be grabbed by others.

Collisions

You can collide (or run into) objects and other avatars in 8 agora. Likewise, objects can collide with one another. We use physics to govern how entities behave when they collide with each other or with avatars.

Without this collision property set, objects will move straight through other entities and avatars. As you interact with your environment, take note on which objects have collisions enabled based on whether or not you can walk through them.

When creating your own entities, you can set the Collision property to turn on or off collisions.

Triggered Entities

Some entities have scripts (or triggers) that make them behave a certain way when you interact with it. For example, you can trigger a light switch to turn on or off when your hand passes through it, or make a pet walk when you grab its leash.

These triggers are scripted in the entities themselves by their creators. Because of this, the possible behavior is endless. We encourage you to explore and discover all of the cool ways you can interact with your surroundings.

See Also

Create

8 agora enables people connected by interest, community, and friendship to come together and express their creativity with each other. We invite you to personalize your own experience by creating avatars and wearables, building immersive experiences, and developing apps to make the metaverse your own.

No matter your level of expertise, 8 agora provides the tools you need to create anything you can imagine.

Throughout this chapter, learn how to create, build, and bring to life your own VR experience:

Create Tools

To build and create things in 8 agora, you need to become familiar with the tools available to you. We’ve created our own custom tools (including the Create app and Shapes app). In addition, you can use many external tools to fine-tune your creations. These tools can help you create anything from a cool avatar or a baseball hat, to a magic themed domain.

On This Page

The Create App

Use the Create app to create any type of entity. In Interface, pull up your HUD or Tablet and go to Create to get started. With the Create app, you can:

  • Add any type of entity and import externally created models and materials.
  • Edit entity properties, such as its appearance, position, and behavior.
  • Expose a grid that assists you with the layout and placement of entities.
  • Display the Entity List, which lists all the entities in the domain. When you’re using an HMD, the entity list will be an additional tab in the Create app. In Desktop mode, the Entity List is its own window.

Note

We have received reports that Interface may crash when using a laptop and external monitor with the Create app. If you experience the crash, we recommend that you either a) disable the Nahimic service on your laptop or b) always use the Create Tools on your primary monitor.

Entity List

The Entity List shows you all entities in the local domain. You can filter by entity type and by distance from the current location.

At the top of the Entity List, you can switch between ‘Local’ and ‘World’ view. When set to ‘Local’, the position, size, and rotation settings for entities are set in reference to the parent entity. When set to ‘World’, these settings are set in reference to the world’s default position.

When you select an entity in the Entity List, you can:

  • Find an entity: You can double-click an entity on the list to view it in your domain. You will see the entity with a bounding box and arrows around it.
  • Lock an entity: A locked entity cannot be edited. Select an entity and click the lock icon on the top of the window.
  • Change visibility: You can hide or make an entity visible. Select an entity and click the eye icon on the top of the window.
  • Name an entity: Name an entity when you select it on the list.
  • Delete an entity: Delete an entity by clicking on the red bin icon on the top-right corner of the window.
External Creator Tools

We’ve listed some external tools you might want to use to create avatars and 3D models.

Adobe Fuse

Note

There are community reports where users are unable to easily open Adobe Fuse once installed. To work around this issue, open it multiple times successively until you are able to open the application.

Use Adobe Fuse to create a custom avatar. The default heads, torsos, arms, and legs in Adobe Fuse can help you start your customization.

Mixamo

Mixamo is a rigging system that will rig your avatar’s skeleton for you. You do not need any advanced knowledge of rigging to create simple animations for your avatar.

Blender

Blender is an open-source 3D modeling creation suite which supports everything from modeling and rigging, to animation and simulation. You can also use Blender to fine tune your avatar, and ensure that the materials and textures render correctly in 8 agora.

Maya

Maya is a subscription based 3D modeling toolset that you can use to create 3D models to import into 8 agora.

Blocks

Blocks is a 3D modeling tool you can use in VR. Blocks lets you create models easily regardless of your experience. You can create something on Blocks through Steam or download it for the VR equipment you are using.

See Also

Avatars

When you first use 8 agora, you will be wearing the default avatar. Your avatar is a representation of you in the metaverse. You can make your time in 8 agora unique by creating an avatar of your own. All custom avatars must be hosted somewhere in the cloud so that 8 agora can access it.

In This Section:

Create Your Own Avatar

There are three ways to create your own avatar. You can either:

  • Create your avatar from scratch using 3D modeling tools such as Adobe Fuse, Mixamo, and Blender
  • Use “VirtualYou: 3D Avatar Creator”, 8 agora’s app to create a 3D avatar that looks like you in less than five minutes. Download the app from the Apple or Google Play stores.
  • Download an existing avatar from external sources such as TurboSquid or CGTrader

Note

If you get an avatar from an external source such as TurboSquid or CGTrader, it is likely that the skeleton does not match our avatar standards. To use these avatars with 8 agora, use the 8 agora Avatar Exporter for Unity to correctly map the skeleton and package your avatar.

If you want to create an avatar from scratch, this page covers the steps needed to create, rig, and package your avatar.

On This Page

In This Section

Avatar Standards Guide

This document outlines the standards you should follow when creating your avatar. Your avatar uses bones to animate the character’s limbs and define the scale variable of limbs. You can add custom bones to further adjust the avatar’s shape. Customization of your avatar can be fine-tuned using blendshapes to animate the face and scripting to define advanced behaviors.

On This Page:

Glossary

As we delve deeper into creating custom avatars, we may use terminology that you are unfamiliar with. Here are some terms you might come across:

  • Avatar - A virtual representation of a person or NPC.
  • Mesh - The collection of 3D vertices and triangles for the avatar model. Without this, the avatar is invisible.
  • Bones - A component of a skeleton that defines a “limb” such as an arm, leg, etc. Each bone may be animated as a separate limb in your avatar.
  • Skeleton - A hierarchy of joints.
  • Rigging - The process of creating a skeleton of the avatar model.
  • Blendshapes - Variations of the topology that defines how the mesh is modified to create various “shapes”.
  • FST file - The main avatar file, which contains information about the skeleton, blendshapes, FBX file and textures used by an avatar.
Reference Pose

For the Reference pose, use a T-Pose which complies with the specifications below. You may wish to refer to the properly configured example avatar fbx with source files.

  • The character must face along the positive direction of the Z-axis.
  • The arms must be spread along the X-axis. The left arm should therefore be pointing along the positive direction of the X-axis.
  • The top of the character’s head must be up, in the positive direction of the Y-axis.
  • The character’s hands are flat, palms facing the ground, with the thumbs parallel to the X axis.
  • The character’s feet need to be perpendicular to the legs (with the toes pointing along the Z-axis as shown). The feet must not be rotated around the Y-axis (meaning the toes of the left foot should not point inward toward the right leg or outward away from the right leg).

_images/hifi-skel.png

You can download the standard 8 agora skeleton here. This skeleton conforms to the specifications above.

Skeleton

The standard humanoid skeleton of your avatar should follow HumanIK Skeleton with some modifications made for Mixamo. This skeleton system will work with the input systems already in place in 8 agora, and will allow users to use their input devices to control their avatar’s arm and finger movements (if they have any).

8 agora avatars should match the following standard skeletal structure. Each of these joints can be animated.

Note

Finger #1 is not the metacarpal; instead, it is the first joint between the proximal and intermediate.

_images/avatar-skeleton.png

Flow Bones

The sim and flow prefixes are reserved for flow bones, such as clothing, hair and tails. These bones should not be animated by an animator. _images/flow-bones.png

For example, consider a full cape that surrounds the avatar:

simBackCape1 - first bone of the cape, center back
simBackCape# - additional bone(s) of the cape, center back
simFrontCape1 - first bone of the cape, center front
simFrontCape# - additional bone(s) of the cape, center front
simLeftCape1 - first bone of the cape, left
simLeftCape# - additional bone(s) of the cape, left
simRightCape1 - first bone of the cape, right
simRightCape# - additional bone(s) of the cape, right

Alternatively, you can use the flow prefix, separating the name and joint number with an underscore. The same cape as above would look like:

flow_BackCape_01
flow_BackCape_02
flow_FrontCape_01
flow_FrontCape_#
flow_LeftCape_01
flow_LeftCape_#
flow_RightCape_01
flow_RightCape_#
Look-at Vectors

The look-at vectors are driven by the z-vector of the eye joints.

The +z axis of the eye joints should go through the center of the pupil, and should continue to do so as the eye joint is rotated.

The eye joints are defined in the FST.

Blendshapes

8 agora uses blendshapes to animate your avatar’s face. Blendshapes allow you to specify a new state for your avatar’s mesh, and facial positions are animated by moving between the different states of your avatar’s expressions. Blendshape behaviors are defined in your avatar’s FST file, and are added to the avatar mesh using a 3D modeling tool like Blender (Shape Keys) or Maya. Adobe’s Fuse program and Mixamo pipeline allow you to export blendshapes as part of your FBX, but if you are modeling an avatar from scratch, you will likely need to specify your own facial expressions.

8 agora avatars support a number of blendshapes for creating different facial expressions.

Basic Blendshapes

  • EyeBlink_L: Blinking action for the left eye.
  • EyeBlink_R: Blicking action for the right eye.
  • JawOpen: Opening of the jaw.

Audio Blendshapes

These blendshapes are used when you speak.

Your eyebrows are blendshapes that react to a change in volume. They will move upwards when your voice gets louder. These include:

  • BrowsU_C: Center of the brow going up
  • BrowsU_L: Outside corner of the left brow going up
  • BrowsU_R: Outside corner of the right brow going up

Other audio blendshapes are randomly mixed when you speak. These include:

  • MouthSmile_L: Left side of the mouth lifting up to a smile
  • MouthSmile_R: Right side of the mouth lifting up to a smile
  • LipsFunnel: Funneling of the lips, as when you say “Oh!”
  • LipsUpperClose: Upper lips rolled inwards

Eyelid Offset

To ensure that the top of the eyelid rests on the iris, blendshapes are used to track the current position of the eye along with your head orientation.

  • EyeBlink_L: Blinking action for the left eye
  • EyeBlink_R: Blicking action for the right eye
  • EyeOpen_L: Opening of left eye
  • EyeOpen_R: Opening of right eye
  • BrowsD_L: Outside corner of the left brow moving down
  • BrowsD_R: Outside corner of the right brow moving down

We apply a small procedural offset to the blendshape coefficients to prevent sleepy or crazy eye lids:

  • If you are looking straight ahead: The EyeBlink and EyeOpen coefficients will be 0.
  • If your eyes begin to look upward: EyeBlink, EyeOpen, and BrowsU start changing in value, reaching the values of -1, 1, and 0.5 respectively at 16.3 degrees. This will have the effect of raising your lids and brows as you look upward.
  • If your eyes begin to look downward: EyeBlink and EyeOpen start changing in value. EyeBlink reaches a value of 0.5 at 32 degrees. EyeOpen will reach a value of 0.5 at 27 degrees. This will have the effect of lowering your lids as you look downward.

Tweaks to your blendshapes can be made with a 3D modeling tool, or directly in your avatar’s FST file. In the FST file, blendshapes are defined with the syntax:

bs = [blendshape constant] = [your key/blendshape name] = [value between 0 and 1]

Here is an example of modifying your blendshapes in your FST file:

bs = BrowsU_L = head_BS_brow_up = 0.3
bs = BrowsU_C = head_BS_brow_up = 0.3
bs = BrowsU_R = head_BS_brow_up = 0.3
bs = BrowsD_R = head_BS_brow_down = 0.5
bs = BrowsD_L = head_BS_brow_down = 0.5
bs = EyeBlink_L = head_BS_L_eye_close = 1
bs = EyeBlink_R = head_BS_R_eye_close = 1
bs = EyeOpen_L = head_BS_L_eye_open = 1
bs = EyeOpen_R = head_BS_R_eye_open = 1
bs = JawOpen = JawOpen = 1
bs = MouthSmile_R = head_BS_L_smile = 0.6
bs = MouthSmile_L = head_BS_R_smile = 0.6
bs = LipsFunnel = head_BS_oo = 0.5
bs = LipsUpperClose = head_BS_mouth_down = 0.1
Other Considerations
File Optimization

Content creators will have limited bandwidth on servers (read small print on any unlimited host plans) so optimization is important, for both the end users and content creators. The more polygons and larger textures you use, the more bandwidth you are using from your servers per load. Optimally, keep your avatar models under 20 MB.

Textures

We recommend that you try to keep total size of all the textures per avatar below 8 MB. They should be always smaller than 1024x1024, unless all the textures are in a single file. If using multiple texture files, then smaller the better, especially if you can make the textures smaller. Remember that you can get a lot more detail through roughness and normal mapping, than just textures. It is suggested that you keep Albedo at a smaller size than your roughness for best detail through light reflection instead of color variation.

Avatar Collision Hulls

When you wear different avatars, you’ll notice that each avatar has a different collision shape or collision hull. The collision hull is the invisible area around your avatar that is used to used to detect when other avatars or entities collide with you.

Depending on the avatar’s design, the collision hulls can be very large or small. This occurs because 8 agora analyzes the shape of the avatar’s torso (from hips to head) and tries to find the best shape that encloses the mesh. For example, if your avatar has large hips or perhaps a fully extended tail, 8 agora thinks that the tip of the tail is part of your hips, and makes a very large collision hull. To reduce the size of the collision hull, you can add skeleton joints to your avatar’s tail.

See Also

Create an Avatar from Scratch

The steps involved in creating your avatar are:

  1. Create an avatar with 3D character modeling tool such as Adobe Fuse, Blender or Maya.
  2. Rig and animate your avatar with an animation tool such as Mixamo.
  3. Fine tune your avatar using a tool such as Blender or Maya.
  4. Package the model in 8 agora for use as an avatar.

Check out this YouTube playlist for one way to create and customize your own avatar. Here, we use Adobe Fuse to create our avatar, Mixamo to rig our avatar automatically, and Blender to adjust the rendering on our avatar. We also have written instructions on the same process:

Find and Use an Existing Avatar

You can download avatars for use from external sources such as TurboSquid or CGTrader. Once you get the avatar, you will need to process it in Unity using the 8 agora Avatar Exporter. This tool imports most avatars into Unity, maps their skeleton using Unity’s humanoid tool, and exports them as FST and FBX files to import in-world.

On This Page

Avatar Guidelines

Many external sites like TurboSquid and CGTrader provide avatars that you can use. However, note that not all of the avatars you find may work in 8 agora. To improve the chances that your downloaded avatar is compatible with 8 agora, we’ve compiled a list of guidelines to help you “sanity check” it prior to use.

You should ensure that:

  • You downloaded a real-time models (rigged for run-time, not rigged for render).

  • You have the correct downloaded files

    • An FBX model for your avatar. We do not support other 3D model formats.
    • (Optional) One or more image files to give your avatar color and texture. Sometimes, these are already embedded in your FBX model and you won’t have any additional image files in your download.

  • Your avatar is rigged.

Note

If your avatar is not rigged, you can use Mixamo to rig it. If you use Mixamo, you do not necessarily need to use Unity and the avatar exporter. Because Mixamo already uses a skeleton that we support, you can use our Avatar Packager to import your avatar into 8 agora.

8 agora Avatar Exporter for Unity

8 agora supports only one standard type of rigging for avatars. Because many avatars do not match this skeleton, we created the 8 agora Avatar Exporter for Unity (also known as the “avatar exporter”) to convert human-like avatars with a humanoid bone structure (body, head, and limbs). The avatar exporter also automatically packages your avatar for use in 8 agora.

Note

The avatar exporter was written to improve the process of rigging and mapping the skeleton rig. This will not affect the animations or materials in your avatar. To adjust the materials, you will need to use a 3D modeling tool such as Blender or Maya and make modifications to your avatar prior to using the avatar exporter in Unity.

You will need the following to use this tool:

  • Unity (Recommended versions: 2017.4.17f1 - 2018.2.12f1)
  • 8 agora (v0.77.0 or higher)

Please note that the recommended version of Unity is not the latest version. If you are using a newer version of Unity, we recommend that you apply a T-Pose to your avatar. To do so, go to the ‘Inspector’, and click ‘Pose’ near the bottom of the panel. Select ‘Enforce T-Pose’ from the drop-down. Click ‘Apply’ and ‘Done’. We recommend doing this after correcting any issues with remapping bones.

Install the Avatar Exporter

You need to install the extension for every Unity project that you have. Keep in mind, however, that you can import and export multiple avatars in a single Unity project.

  1. Download the avatar exporter from 8 agora.
  2. In Unity, open the ‘Project’ window at the bottom.
_images/project-window.png
  1. Right-click the ‘Assets’ folder, then select Import Package > Custom Package.
_images/import-package.png
  1. Navigate to the avatarExporter package (with a .unitypackage extension). Click ‘Open’. You can also double-click the package on your computer to import it automatically.
  2. In the ‘Importing Package’ window, review the list of files to be imported and check for conflicts with files already in your project. If a conflict exists, save any local changes somewhere outside of your project.
  3. Click ‘Import’. The package’s files are added to the Assets folder. You should now have a ‘8 agora’ menu in Unity.
_images/hifi-menu.png
Create an Avatar Package
  1. If you don’t already have your model open in Unity, you need to import your model. Use any of the following methods:
    • Drag and drop the FBX file into the ‘Assets’ folder of your ‘Project’ window.
    • In the ‘Project’ window, right-click the ‘Assets’ folder, then select Import Package > Import New Asset. Navigate to the FBX file and click ‘Import’.
    • In Unity, open the ‘Assets’ menu, then select Import Package > Import New Asset. Navigate to the FBX file and click ‘Import’.
  2. In the ‘Project’ window, select your avatar’s FBX file. In the ‘Inspector’, open ‘Rig’. For ‘Animation Type’, choose ‘Humanoid’ and then click ‘Apply’.
_images/apply-humanoid-animation.png
  1. Click ‘Configure’ to investigate and tweak the mapping of your avatar.
_images/configure-avatar.png
  1. All bones mapped in Unity are highlighted in green and can be selected. Check if anything is missing. Any errors will appear in red. The minimum required bones for mapping are Hips, Spine, Chest, and Head. If either of these are missing, you must manually add bones before continuing. You can do this by dragging the bones from the ‘Avatar Configuration’ panel to the ‘Inspector’ panel.
_images/check-mesh.png _images/avatar-config.png

Note

Avatars in 8 agora must have a Chest bone. If your avatar does not have a chest bone, the avatar exporter may suggest a suitable alternative from the ‘Avatar Configuration’ panel. If the exporter doesn’t suggest an alternative and Humanoid doesn’t correctly map the Chest, then you will get an error and need to manually map a bone to the Chest from ‘Avatar Configuration’.

  1. If you made any changes, click ‘Done’.
  2. Click on the FBX file in the ‘Assets’ manager.
_images/select-avatar-unity.png
  1. Make sure that you have the avatar exporter installed. Open the ‘8 agora’ menu in the top menu bar, then select ‘Export New Avatar’.
  2. Give your avatar project a name. The default project location is your local user’s Documents\8 agora Projects directory, which is created automatically for you. Though we recommend that you keep your avatars in this directory, you can change it to another location on your computer.
_images/export-avatar.png
  1. Click ‘Export’.

Your avatar package has been created! The File Explorer will open to your new avatar project.

_images/exported-package.png

Note

If you are using any external textures with your avatar model, copy those textures to your local user’s Documents\8 agora Projects\avatar\<project name>\textures directory. Otherwise, they may not show up on your avatar.

Test Your Avatar

We encourage you to “spot check” your avatar in Unity before exporting it with the 8 agora Avatar Exporter for Unity. Check for the following:

  • Confirm that there are no extraneous objects attached to your model. For example, this Mech avatar has a ground blue object included in the model. All extraneous objects will be imported into 8 agora and may affect the rendering or animation of your avatar.
  • Test your bone movements. In Unity’s ‘Inspector’, open ‘Rig’. For ‘Animation Type’, choose ‘Humanoid’ and then click ‘Apply’. Go to ‘Muscles & Settings’ to test your avatar’s bone configuration and ensure that it works as expected.
_images/muscle-adjustment.gif

If everything looks good, you need to host your avatar then change your avatar to wear it.

Troubleshooting Tips

Many of the errors you will encounter describe issues with the avatar’s skeleton. These are fully documented here: Troubleshooting with the Avatar Packager. Here are some other issues you may encounter after using a downloaded avatar and using the avatar exporter:

Issue Troubleshooting Tip

You receive a warning in Unity:

“Character is not in T pose.”

 Go to the ‘Inspector’, click ‘Configure’, and then select ‘Pose’ near the bottom of the panel. Select ‘Enforce T-Pose’ from the drop-down. Click ‘Apply’ and ‘Done’. We recommend doing this after correcting any issues with remapping bones.
In Unity, your avatar is a solid color.

This suggests that the materials or shaders you are using are not supported.

  1. Click and drag your model into the ‘Scene’ window.
  2. Select all of the unsupported materials. These will be one solid color, such as pink.
  3. In the ‘Inspector’, change the ‘Shader’ to one of the ‘Standard’ options. All materials should now show up correctly.
Your avatar is grey.

One of the following issues could have occurred:

  1. Make sure you copied your avatar’s textures into the project’s textures folder
  2. Verify that your textures are in a format that we support (PNG, JPEG, JPG, TGA, TIF, or TIFF).
  3. If your textures are embedded in your avatar: select the FBX file, go to ‘Inspector’, and click ‘Extract Textures’. Extract your textures into your asset’s folder. You can do the same with Materials.
Your avatar is tied up into knots or laying down.

This could mean that your skeleton is not right. Re-open your avatar in Unity and run through steps 2-5 of Create an Avatar Package again. Update your project in Unity (go to Update Existing Avatar, then browse to your avatar package).

If it still doesn’t work, ensure that you are testing the correct file that the avatar exporter created.
Your avatar’s skin doesn’t move properly with animations. The avatar exporter was written to improve the process of rigging and mapping the skeleton rig. This will not affect the animations in your avatar. To adjust the animations, you will need to use a 3D modeling tool such as Blender or Maya and fix the skin weighting on the avatar prior to using the avatar exporter in Unity.

See Also

Package and Host Your Avatar

At a minimum, avatars in 8 agora must have an FBX model and an associated FST file that includes information about how your avatar looks and behaves. Together, these two files (with any optional texture or script) form an “avatar package”. There are two ways you can create an avatar package: by using the Avatar Packager in Interface or the 8 agora Avatar Exporter for Unity in Unity.

Once you have packaged your avatar, you need to host it on the cloud so that 8 agora can access it and correctly render your avatar for all users.

On This Page

Package Your Avatar

If you’re reading this page, you likely already built your own FBX model or found and downloaded a model that you want to use in 8 agora. Therefore, all that remains is to package your avatar and create the FST file. This file includes information about the skeleton, blendshapes, textures, and scripts used by your avatar.

We provide two ways to create an avatar package: either through Unity or through our Avatar Packager.

8 agora Avatar Exporter for Unity

In some cases, you will want to download an avatar from an external website and use that avatar in 8 agora. The 8 agora Avatar Exporter for Unity (also known as the “avatar exporter”) converts human-like avatars and packages them for use in 8 agora.

Once you have successfully used the avatar exporter to package your avatar, you must host it somewhere on the cloud. You can host it on our servers (using the Avatar Packager), or simply copy the avatar package to your own servers.

Avatar Packager

The Avatar Packager is a tool in Interface that identifies potential errors in your avatar’s FBX model and then creates an FST file for you.

To package your avatar using the Avatar Packager:

  1. In Interface, go to Edit > Avatar Packager.
  2. In the Avatar Packager window, click ‘New Project’.
  3. In the Create Project window, fill in the following details:
    • Name: The name you want for your avatar.
    • Project Location: The folder path where your avatar’s files are stored. The Avatar Packager will create a new folder for your project at this location. The package will contain your FBX model, an FST file, and any scripts/textures in your avatar.
    • Avatar Model: The location of your avatar’s FBX model.
    • Texture Folder: If your avatar has textures in a separate folder, specify the folder location. If your avatar’s textures are embedded in the FBX, you do not need to specify anything.
  4. Click ‘Create’.

At this point, you have successfully packaged your avatar. If you choose to host your avatar on the cloud with your own servers (and not use 8 agora’s servers), you can close the Avatar Packager here and upload your FST file and FBX model to the cloud location of your choice.

Host Your Avatar

Before you can use a custom avatar, you must first host its FST and FBX files in a place that is publicly accessible to 8 agora. We recommend hosting them on our own servers using the Avatar Packager, but you can also use any cloud platform including Amazon S3, Google Cloud Storage, Microsoft Azure, Dropbox, etc.

  1. If this is a new avatar, first use the Avatar Packager to create an FST file. When you proceed with Step 3 below, you will upload this new project to our servers.

  2. If you want to host an avatar that has already been packaged:

    1. In Interface, go to Edit > Avatar Packager.
    2. In the Avatar Packager window that opens, click ‘Open Project’.
    3. Navigate to your FST file and click ‘Open’.

  3. Click ‘Upload’ to upload your avatar’s files to 8 agora’s servers. The Avatar Packager will display any errors or warnings that you may want to resolve prior to uploading. View Troubleshooting with the Avatar Packager to determine whether a fix is required to have a usable avatar.

_images/inventory.png

Note

If you make any changes to your custom avatar, you will need to update it through the Avatar Packager to see your changes. To update, select your project and click ‘Open Project’ in step 1. Follow the same steps to update your avatar.

Troubleshooting with the Avatar Packager

The Avatar Packager will notify you of any errors or warnings that may affect the way your avatar looks and behaves in 8 agora. This is a list of the errors you may encounter, along with basic instructions on how to fix your avatar. Errors (in red) must be fixed before you upload your avatar, while Warnings (in orange) may or may not affect whether your avatar will show up and behave correctly in 8 agora.

Note

Many of the errors you will encounter describe issues with the avatar’s skeleton. The troubleshooting tips below will attempt to fix the errors in Unity.

However, if the bone structure of the model does not resemble a humanoid skeleton (with two legs, two arms, hips, chest, spine, and head), then it is likely not compatible with 8 agora. You will not be able to fix these avatars in Unity alone. Instead, you will likely need advanced knowledge of building, rigging, and mapping bones in a 3D modeling tool such as Blender or Maya.

Error How to Fix

Hips are not mapped

This error occurs when there is no "hip" bone identified in your avatar's skeleton.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Body' button next to the humanoid illustration.
  6. Locate 'Hips' and drag the appropriate bone from the Hierarchy window to map it.

If an appropriate bone does not exist, or this does not resolve the issue, you will need to fix the avatar's skeleton in a 3D modeling tool of your choice.

Spine is not mapped

This error occurs when there is no "spine" bone identified in your avatar's skeleton.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Body' button next to the humanoid illustration.
  6. Locate 'Spine' and drag the appropriate bone from the Hierarchy window to map it.

If an appropriate bone does not exist, or this does not resolve the issue, you will need to fix the avatar's skeleton in a 3D modeling tool of your choice.

Chest (Spine1) is not mapped

This error occurs when there is no "chest" bone identified in your avatar's skeleton.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Body' button next to the humanoid illustration.
  6. Locate 'Chest' and drag the appropriate bone from the Hierarchy window to map it.

If an appropriate bone does not exist, or this does not resolve the issue, you will need to fix the avatar's skeleton in a 3D modeling tool of your choice.

Head is not mapped

This error occurs when there is no "head" bone identified in your avatar's skeleton.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Head' button next to the humanoid illustration.
  6. Locate 'Head' and drag the appropriate bone from the Hierarchy window to map it.

If an appropriate bone does not exist, or this does not resolve the issue, you will need to fix the avatar's skeleton in a 3D modeling tool of your choice.

Neck is not mapped

This warning occurs when there is no "neck" bone identified in your avatar's skeleton.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Head' button next to the humanoid illustration.
  6. Locate 'Neck' and drag the appropriate bone from the Hierarchy window to map it.

If an appropriate bone does not exist, or this does not resolve the issue, you will need to fix the avatar's skeleton in a 3D modeling tool of your choice.

LeftEye is not mapped |
RightEye is not mapped |
Eyes are not mapped

This warning occurs when there is one or more missing "eye" bones in your avatar's skeleton.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Head' button next to the humanoid illustration.
  6. Locate the faulty 'Eye' joint and drag the appropriate bone from the Hierarchy window to map it.

If an appropriate bone does not exist, or this does not resolve the issue, you will need to fix the avatar's skeleton in a 3D modeling tool of your choice.

Multiple top-level joints found

8 agora's standard avatar skeleton has one root bone (typically the hips) that every other bone is connected to, either directly or indirectly. This bone is known as the "parent", "root", or "top-level" bone and it defines the center of your avatar. Click here to view our standard avatar skeleton.

This error occurs when you have more than one of these "top-level" bones defined in your avatar's skeleton. Rather than a hierarchy of joints, you will likely see many bones at the same root level in your skeleton.

In Unity, check your avatar's skeleton in the Hierarchy window. In some cases, having multiple bones at the root level won't affect your avatar, especially if they are unimportant bones (for example, the tongue bone probably will not affect the overall appearance of your avatar). In these cases, you can simply ignore the error and proceed with packaging and hosting your avatar.

If you have multiple "top-level" bones that are important (for example, if the hips and neck bone are at the same level), then you will need to fix the avatar's skeleton in a 3D modeling tool of your choice.

<boneName> is mapped multiple times

This warning occurs when one of your avatar's bones is mapped multiple times in your skeleton. For example, a back bone may be mapped to both the spine and the hips.

  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Locate the duplicate mapping in Humanoid and delete it.
  6. If it is a required bone (such as hips, spine, chest, or head), then locate the correct bone in the Hierarchy window. Drag it to the Humanoid mapping.

If an appropriate bone does not exist, or this does not resolve the issue, you will need to fix the avatar's skeleton in a 3D modeling tool of your choice.

Asymmetrical arm/leg/hand bones

We assume that the left and right appendages (arms, legs, and hands) have the same number of bones. This warning occurs if we detect a different number of bones on the left and rights sides of the body.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. For arm and leg warnings, click the 'Body' button next to the humanoid illustration. For hand warnings, click the appropriate 'Hand' button next to the humanoid illustration.
  6. Compare the left and right side. If the number of bones on the sides do not match, then locate and drag the appropriate bone from the Hierarchy window to map it.

Spine is not a child of Hips

8 agora's standard avatar skeleton has one root bone, and every other bone is a descendent of that bone (either directly or indirectly). In the standard skeleton, the spine must be a direct descendent of the hips. Click here to view our standard avatar skeleton.

This warning occurs when the spine is not a direct descendent of the hip bone.

  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Body' button next to the humanoid illustration, and click on the 'Hips' mapping. This will highlight the mapped bone in the Hierarchy window.
  6. Now click on the 'Spine' mapping. The highlighted bone should be directly below the Hips bone. If it is not, then locate and drag the appropriate bone from the Hierarchy window to map it.

If the appropriate bones are mapped to the Hips and Spine, or this does not resolve the issue, you will need to fix the avatar's hierarchy in a 3D modeling tool of your choice.

Spine1 is not a child of Spine

8 agora's standard avatar skeleton has one root bone, and every other bone is a descendent of that bone (either directly or indirectly). In the standard skeleton, the chest bone (or Spine1) must be a direct descendent of the spine. Click here to view our standard avatar skeleton.

This warning occurs when the chest is not a direct descendent of the spine bone.

  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Body' button next to the humanoid illustration, and click on the 'Spine' mapping. This will highlight the mapped bone in the Hierarchy window.
  6. Now click on the 'Chest' mapping. The highlighted bone should be directly below the Spine bone. If it is not, then locate and drag the appropriate bone from the Hierarchy window to map it.

If the appropriate bones are mapped to the Spine and Chest (Spine1), or this does not resolve the issue, you will need to fix the avatar's bone hierarchy in a 3D modeling tool of your choice.

Head is not a child of Spine1

8 agora's standard avatar skeleton has one root bone, and every other bone is a descendent of that bone (either directly or indirectly). In the standard skeleton, the head bone must be a direct descendent of the chest (or Spine1). Click here to view our standard avatar skeleton.

This warning occurs when the head is not a direct descendent of the chest bone.

  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Body' button next to the humanoid illustration, and click on the 'Chest' mapping. This will highlight the mapped bone in the Hierarchy window.
  6. Now click the 'Head' button, and click on the 'Head' mapping. The highlighted bone should be below the Chest bone. If it is not, then locate and drag the appropriate bone from the Hierarchy window to map it.

If the appropriate bones are mapped to the Chest (Spine1) and Head, or this does not resolve the issue, you will need to fix the avatar's bone hierarchy in a 3D modeling tool of your choice.

Hips are on ground

This warning occurs when the bone mapped to the Hips is on the ground, rather than at hip level.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Body' button next to the humanoid illustration.
  6. Locate the 'Hips' mapping. This is the one with an incorrect mapping.
  7. Drag the appropriate bone from the Hierarchy window to re-map it.

If the appropriate bone is mapped to the Hips, or this does not resolve the issue, you will need to fix the avatar's bone placement in a 3D modeling tool of your choice.

Hips/Spine/Chest Overlap

8 agora's standard avatar skeleton requires that each bone is placed at different locations on the body. For example, the hips cannot be positioned at the same location as the chest. This error occurs when either the hips, spine, and/or chest bones have overlapping positions.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Ensure that your avatar is 'Humanoid' (in Unity, go to Inspector > Rig > Animation Type > Humanoid).
  4. Click 'Configure' to open the skeleton mapping configuration.
  5. Click the 'Body' button next to the humanoid illustration, then click on the bone you want to reposition.
  6. In the Scene window, arrows will appear around the bone you have selected. Make minor adjustments to the bone's position using these arrows, until each bone is at its own unique position on the avatar.

If this does not resolve the issue, you will need to fix the avatar's bone placement in a 3D modeling tool of your choice.

Avatar has over 256 bones

This warning occurs when you have more than the maximum number of bones allowed (which is 256 bones).

This warning cannot be resolved in Unity or 8 agora. To fix it, you need to remove bones from your skeleton using a 3D modeling tool of your choice.

Missing # texture(s)

This warning occurs when 8 agora cannot find textures for your avatar. This will affect the appearance of your avatar, and it may appear grey when you try to use it.

After you package your avatar, copy all external textures to the 'Textures' folder that we create for you. Then, update your project using the Avatar Packager.

# unsupported texture(s) found

This warning occurs when your textures are not supported by 8 agora. Supported image formats include PNG, JPG, JPEG, TGA, TIF, and TIFF files.
  1. Open your textures in an image editor of your choice.
  2. Export the textures to a supported format.
  3. Set the new texture to your avatar using Unity's Material Editor or a 3D modeling tool of your choice.

No textures assigned

This warning occurs when you do not have any textures embedded in your model or referenced in your FST file. If your avatar was intentionally designed without textures, this warning can be safely ignored.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. Go to Inspector > Materials.
  4. Change the 'Location' to 'Use External Materials (Legacy)'. Click 'Apply'. This creates a Materials folder.
  5. Copy your textures into the new Materials folder.
  6. Select a material to view its shader in the **Inspector** window. Click and drag your textures to configure them.

For more information, see Unity's help on their Material Editor. You can alternatively use a 3D modeling tool of your choice to assign materials and textures to your avatar.

Model file cannot be opened

This warning occurs when your avatar package is missing either an FBX or FST file.

  1. In a file explorer, open your avatar package folder.

  2. Ensure that your avatar package has both an FST and FBX file.

    • If you are missing your FBX file, locate it and copy it back into this folder.
    • If you are missing an FST file, re-package your avatar using either the 8 agora Exporter Avatar Exporter for Unity or the Avatar Packager.
  3. If both files are there and you still receive this error, open the FST file in a text editor of your choice.
  4. Locate the line filename = , and ensure that the path to your FBX file is correct.

Unsupported avatar model format

This warning occurs when your avatar model is not a supported format. 8 agora only supports FBX models for avatars.

This warning cannot be resolved in Unity or 8 agora. To fix it, you need to open your model in the 3D modeling tool of your choice, and export your model as an FBX model.

Avatar is possibly too short

This warning occurs when 8 agora detects that your avatar will appear very small when you use it.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. From the 8 agora menu, click 'Export New Model'.
  4. Slide the scale slider to the right to increase the size of your avatar.

Avatar is possibly too tall

This warning occurs when 8 agora detects that your avatar will appear very large when you use it.
  1. Import your FBX model into a Unity project.
  2. Install the avatar exporter for Unity.
  3. From the 8 agora menu, click 'Export New Model'.
  4. Slide the scale slider to the left to decrease the size of your avatar.

Avatar has no rig

This warning occurs when your avatar is not rigged.

This warning cannot be resolved in Unity or 8 agora. To fix it, we recommend running your avatar model through an auto-rigging tool such as Mixamo.

Add Flow to Your Avatar

You can simulate physics on your avatar’s hair, clothes, and body parts with a little bit of scripting and the help of 8 agora’s Flow technology. The concept of “Flow” simply mimics the natural movement of hair and other attachments on your avatar.

On This Page

Prepare Your Avatar

In order to use the Flow technology, your avatar must contain flow threads, which are sets of connected joints in your avatar. Each flow thread must comply with the following rules:

  1. The first joint is connected to an existing avatar joint, such as “Hips”.
  2. Every joint in the thread should be named flow_[TYPE]_[INDEX] or sim[TYPE][INDEX], where TYPE defines a group of joints that share a common physics setup and INDEX is an integer. For example, if the thread is used to simulate a skirt, all the “skirt” joints are named flow_skirt_01, flow_skirt_02, etc.
_images/flow-threads.png

While experimenting, feel free to use Mannequin with Hair, whose hair has flow threads already configured.

Flow App

Load this script in Running scripts (from URL):Flow app to configure your flow settings.

The Flow app will show up as an icon on your HUD or tablet. Click this icon to open the Flow app.

_images/flow-app-icon.png
Display Panel

The Display panel affects how your avatar looks while the Flow app is open. Using these options, you can choose to view meshes and collisions to help you determine what your final flow configuration will look like.

_images/flow-display.png
Option Description
Avatar Hides or displays the avatar mesh.
Collisions Activates or deactivates collisions.
Debug Hides or displays the debug shapes.
Solid Enables either a solid or wireframe display for debug shapes.
Joints Panel

The Joints panel lists all of the available flow threads, and lets you configure the behavior of your joints.

_images/flow-joints.png
Option Description
Radius Determines the thickness of segments and knots (needed for collision testing).
Gravity Sets the how each joint will respond to gravity. A positive value will lift your joints in the air, while a negative value will respond to gravity and be pulled towards the ground. Larger values will cause the movement to happen more quickly.
Stiffness Defines how susceptible the flow threads are to movement.
Damping Determines how easily the bones oscillate or move around the joints.
Inertia Changes the rotational velocity of the bones.
Delta Controls the amount of time between each joint movement.
Collisions Panel

The Collisions panel controls the collision spheres that define the interactions between flow threads and the joints in your avatar. Each collision sphere is positioned using an existing avatar joint and offset: as you increase the radius of a collision sphere, you increase the distance between the flow thread and the joint. You can only have a maximum of 4 collisions defined for your avatar.

_images/flow-collisions.png
Option Description
Radius Controls the collision sphere radius.
Offset Controls the collision sphere offset.
Output Panel

The Output panel displays the resulting FST data for your avatar’s flow configuration, based on what you entered in the Joints Panel and the Collisions Panel.

Copy this data directly into your avatar’s FST file to complete the flow process.

_images/flow-fst.png
Resources
File Description URL
Flow App This app lets users easily update Flow settings without the need for scripting or advanced knowledge of avatars. flowAppCpp.js
Mannequin with Hair This avatar is properly rigged to work with Flow. Use this as an example for your own avatar models. Mannequin with Hair

See Also

Customize Avatar Animations

You can express yourself by overriding 8 agora’s standard set of animations with your own custom animations such as dancing, juggling, or waving. Any custom animations you set up will be independent to each avatar you own and wear.

Note

We often update our process for importing custom animations to make it more user friendly. As you develop custom animations, keep in mind that you may need to modify them in the future as our custom animation support continues to improve.

On This Page

Prerequisites

As we delve deeper into creating custom animations, we may use terminology that you are unfamiliar with. Here are some terms you might come across:

Term Description
Avatar animations Avatar animations are FBX files that define how your avatar moves. For example, turn_left.fbx is the standard animation file for your avatar turning left.
Animation roles Animation roles are triggers that map to an action that an avatar can perform. For example, turnLeft is an animation role that makes your avatar turn left while standing in place. This animation role is mapped to the turn_left.fbx file. You can see this in action by pressing the left arrow key or A in Desktop mode or using your hand controllers in VR mode.
Avatar Animation JSON or Animation Graph File The standard animation system blends and layers a series of animations from FBX files using a JSON data file. This JSON file is called the Animation Graph file, and it specifies exactly which animations to play and how they are blended. It also determines the order of operations, so that operations like Inverse Kinematics occur after the rest of the body has been animated by traditional means. By default, every avatar uses the same Animation Graph file.
Prepare Your Custom Animation

Before you replace the existing standard animations, you need to prepare your custom animation file. Use our Avatar Standards Guide and keep the following guidelines in mind:

  • Animations must have standard joint names for 8 agora.
  • Animations must have standard joint orientations (y down the bone).
  • Key frames must have key frames for every joint at a uniform interval of 30 frames per second.
  • Locomotion animation phase has the left ankle in passing position on the first frame. Try to match this phase if you want your locomotion animation to blend with the default set.

Once you create your animation:

  1. Export your animation from the external tool of your choice as an FBX file.
  2. Upload your animation FBX file to a cloud server and copy the URL.
Replace Standard Animations

You can have your avatar use your custom animations by overriding the default animations. There are two different ways to do this:

Override Using a Script

You can write a script and use the MyAvatar namespace to override an existing animation or animation role.

We’ve listed the methods you can use to replace the standard animations on your avatar.

Method Description
MyAvatar.overrideAnimation This method can be used to play any animation on the current avatar. It will move smoothly from the current pose to the starting frame of the custom animation. For example, if your avatar is waving, this script will stop your avatar waving and play the custom animation provided.
AnimationCache.prefetch This method fetches a resource. You can use this to fetch a custom animation you’ve hosted on a cloud server. If you do not prefetch your animations before playing them, you might see a t-pose appear briefly as the animation is downloaded.
MyAvatar.restoreAnimation This method stops the override function from playing any custom animation. Your avatar will go back to playing the standard animations.

Note

This process to replace an existing animation will take complete control of all avatar joints. Inverse Kinematics of the hands and head of HMD users will be disabled.

You can also override an existing animation role mapping:

  1. Use MyAvatar.getAnimationRoles to view the list of roles for the current avatar.
  2. You can replace the animation for each role with a custom animation (FBX file) using MyAvatar.overrideRoleAnimation.

We’ve listed the animation roles and their description. These are frequently updated, so we recommend using MyAvatar.getAnimationRoles to get the latest animation roles before continuing. The standard animation FBX files for these roles can be found in the 8 agora source code repository on GitHub.

Animation Roles Description
rightHandGraspOpen When hand controller trigger is not squeezed.
rightHandGraspClosed When hand controller trigger is fully squeezed.
rightIndexPointOpen Point gesture.
rightIndexPointClosed Point gesture with trigger squeezed.
rightThumbRaiseOpen Thumbs up gesture.
rightThumbRaiseClosed Thumbs up gesture with trigger squeezed.
rightIndexPointAndThumbRaiseOpen Simultaneous thumbs up and point gesture.
rightIndexPointAndThumbRaiseClosed Simultaneous thumbs up and point gesture, with trigger squeezed.
leftHandGraspOpen When hand controller trigger is not squeezed.
leftHandGraspClosed When hand controller trigger is fully squeezed.
leftIndexPointOpen Point gesture.
leftIndexPointClosed Point gesture with trigger squeezed.
leftThumbRaiseOpen Thumbs up gesture.
leftThumbRaiseClosed Thumbs up gesture with trigger squeezed.
leftIndexPointAndThumbRaiseOpen Simultaneous thumbs up and point gesture.
leftIndexPointAndThumbRaiseClosed Simultaneous thumbs up and point gesture, with trigger squeezed.
idleStand Standing still, not talking.
idleTalk Standing still, but avatar is talking.
walkFwdShort_c Walking forward at 0.5 m/s.
walkFwdNormal_c, walkFwdFast_c Walking forward at 1.8 m/s. Walking forward at 2.3 m/s.
walkFwdJog_c, walkFwdRun_c Walking forward at 3.2 m/s. Walking forward at 4.5 m/s.
idleToWalkFwd, idleSettle Short transition from standing idle to walking forward. Transition from walk to idle.
walkBwdShort_c Walking backward at 0.6 m/s.
walkBwdFast_c, jogBwd_c, runBwd_c Walking backward at 1.6 m/s. Jog backward at 2.3 m/s. Jog backward at 3.1 m/s.
turnLeft Standing turning in place animation.
turnRight Standing turning in place animation.
strafeLeftShortStep_c Sidestep at 0.1 m/s.
strafeLeftStep_c, strafeLeftWalk_c, strafeLeftWalkFast_c, strafeLeftJog_c Sidestep at 0.5 m/s. Side walk at 1.0 m/s. Side walk at 2.6 m/s. Side jog at 3.0 m/s.
strafeRightShortStep_c, strafeRightStep_c Sidestep at 0.1 m/s. Sidestep at 0.5 m/s.
strafeRightWalk_c, strafeRightFast_c, strafeRightJog_c, stepLeftShort_c, stepLeft_c, strafeLeftAnim_c, stepRightShort_c, stepRight_c, strafeRightAnim_c Side walk at 1 m/s. Sidewalk at 2.6 m/s Side jog at 3 m/s. HMD step left at 0 m/s. HMD step left at 0.5 m/s. HMD strafe left at 2.5 m/s. HMD step right at 0 m/s. HMD step right at 0.5 m/s. HMD strafe right at 2.5 m/s.
fly Flying idle.
takeoffStand Standing jump takeoff.
TAKEOFFRUN Running jump takeoff.
inAirStandPreApex Standing jump in air on the way upward towards the jump apex.
inAirStandApex Standing jump in air at apex of the jump.
inAirStandPostApex Standing jump in air on the downward arc of the jump.
inAirRunPreApex Running jump in air on the way upward towards the jump apex.
inAirRunApex Running jump in air at apex of the jump.
inAirRunPostApex Running jump in air on the downward arc of the jump.
landStandImpact Standing land.
landStand Standing land.
LANDRUN Running land.
Create a Custom Avatar Animation JSON file

If you’re not comfortable using a script, you can edit or replace the existing Avatar Animation JSON file to override the standard animations.

Note

If you create a custom JSON file for your avatar’s animations, you will not inherit any updates made to the standard animations’ JSON file. You can perform a text merge to the latest version at any time.

The JSON file shows which animation role is mapped to which animation FBX file. You can replace standard animation FBX files with your custom animation’s FBX files. Or, you can write a new JSON file with the new mappings for each animation role.

To replace standard animations:

  1. Upload your custom JSON file to a cloud server and copy the URL.
  2. In Interface, pull up your HUD or Tablet and go to Avatar.
  3. Click on the Settings icon on the top-right corner.
  4. Under ‘Avatar Animation JSON’, paste the URL for your JSON file.

OR

  1. Open your avatar’s FST file in a text editor.
  2. Add your Animation Graph file’s URL.

Note

You will need to run your avatar’s files through the Avatar Packager to include the changes in your FST file.

animGraphUrl = "URL"
Examples
  • Here is the current default avatar-animation.json file.
  • This scoot-animation.json file replaces the idle and walk animations with a sitting pose. This example shows how you can replace some of an avatar’s default animations.
Advanced Topic: AnimNode System

The Avatar Animation JSON file contains a hierarchical tree of nodes called the AnimNode System. The AnimNode system defines how an avatar moves and is described in the Animation Graph JSON file.

The movement of an avatar is determined by a complex blend of procedural animation, pre-recorded animation clips, and inverse kinematics. This blend is calculated at every frame to ensure that the avatar body follows physics and controller input as rapidly as possible. It must handle animation for desktop users, HMD users, and users wearing a full set of HTC Vive trackers. It must be configured on the fly as sensors are added and removed from the system. It should also be open to extensions so unique animations and avatar configurations are possible. These functionalities are handled by the AnimNode system.

We’ve listed some features of the system:

  • The AnimNode system is a graph of nodes.
  • Some nodes are output only, such as pre-recorded animation clips.
  • Other nodes produce output by processing nodes below it in the graph and blending the results together.
  • By manipulating the node hierarchy, certain animation actions will occur before or after other animation actions.
  • The node parameters can be dynamically changed at runtime. This flexibility is necessary to achieve good visual results.
  • The system is in the default Animation Graph JSON file and is loaded during avatar initialization.

Key Concepts

The AnimNode system operates like an expression parse tree. For example the following expression: 4 + 3 * 7 - (5 / (3 + 4)) + 6, can be represented by the following parse tree.

_images/animnode.png

This parse tree can then be evaluated at runtime to compute the actual value. In this tree, the leaf nodes are values and interior nodes are operations that combine two or more sub-trees and produce a new value. The tree is evaluated until there is a single value remaining, which should be the result of the entire expression: 30.2957142.

In the expression case, the output value of each node is a floating point number, and operations can be implemented simply by evaluating each sub-tree, and then combining them with an arithmetic operation, such as addition or multiplication.

The AnimNode system works on a similar concept. Except the value of each node contains all of the avatar’s joint translations and rotations. Leaf nodes can be static avatar poses, such as the T-pose or can be a single frame of an animation clip. Interior nodes can perform operations such as blending between two or more sub-trees, or combining the upper body of one animation with the lower body of another.

See Also

Tutorial: Create an Avatar with Fuse

Note

There are community reports where users are unable to easily open Adobe Fuse once installed. To work around this issue, open it multiple times successively until you are able to open the application.

Using Adobe Fuse, you can create a custom avatar. The default heads, torsos, arms and legs in Adobe Fuse can help you start your customization.

  1. Launch Adobe Fuse.
  2. Pick your default body parts. _images/fuse-assemble.png
  3. Click ‘Customize’. Here, you can customize the avatar. For example, you can customize how the eyebrows are shaped, facial expressions, how long the fingers are and much more. _images/fuse-customize.png
  4. Click ‘Clothing’. Here, you can choose the clothing you’d like. In addition, you can set hair and facial hair options. In the next step, you will be able to modify the materials, colors, and textures of each clothing item you choose._images/fuse-clothing.png
  5. Click ‘Texture’. Here, you can modify your clothing choices with custom materials and colors. _images/fuse-texture.png
  6. Save your avatar.

See Also

Tutorial: Rig Avatars in Mixamo

Mixamo is a rigging system that will rig your model’s skeleton automatically for you. You do not need any advanced knowledge of rigging to create simple animations for your avatar.

In this tutorial, we will use the avatar that we created in Adobe Fuse.

  1. Open your avatar in Adobe Fuse.

  2. Go to File > Animate with Mixamo.

  3. Save your avatar with a name and wait while it is exported to the auto-rigger. _images/character-upload.png

    Note

    Mixamo's auto-rigger will create a custom skeleton for your avatar so you can start animating. The auto-rigger algorithm can take up to 2 minutes, so be patient!

  4. Once your avatar is processed, Mixamo’s auto-rigger will show your animated avatar. Ensure that Facial Blendshapes are ‘Enabled’ and Skeleton LOD has been set to ‘Standard’. These settings ensure that your avatar will work property in 8 agora. _images/auto-rigger.png

  5. If you made changes to your settings, click ‘Update Rig’. Mixamo will re-process your avatar with these updates.

  6. Click ‘Finish’ to start applying animation.

  7. Once your avatar has been successfully rigged, you can download it and modify it further using a 3D software of your choice. When prompted, select Format as ‘FBX’ and Pose as ‘T-pose’. _images/mixamo-download.png

See Also

Tutorial: Modify Materials and Textures Using Blender

Blender is an open-source 3D modeling tool that you can use to fine tune your avatar and ensure that the materials and textures render correctly in 8 agora.

In this tutorial, we will walk you through simple modifications you can make to your avatar using Blender. You will need to import an FBX file for your avatar. If you don’t have one, see our tutorials for Fuse and Mixamo.

  1. In Blender, go to File > Import > FBX (.fbx).

  2. Choose your avatar’s FBX file and click ‘Import FBX’. This will open your avatar in the main view. _images/import-avatar.png

  3. By default, you will not see the materials on your avatar. You can change your view using the toolbar at the bottom of the view. _images/view-materials.png

  4. To get a better view of your avatar, change the lamp settings:

    • From the Outliner, click the Lamp node in Blender.
    • For ‘Type of Active Data to display and edit’, choose the ‘Data’ icon.
    • Change the lamp to Sun.
    • Rotate the Lamp to light up your avatar._images/lamp-settings.png

  5. From the Outliner, open the ‘Armature’ tree and select the item you want to fine tune. You can also click on the item directly on your model.

  6. Using the toolbox below, you can change the materials and texture of each body part as desired. We’ve included an example below that changes our avatar’s eyelashes. You can follow similar steps for other avatar items. _images/texture-material.png

    Note

    To remove a metallic feel to your avatar in 8 agora, we recommend changing the default Specular Intensity for each of the main body parts from 0.500 to 0.000.

  7. When you’re done changing your materials and textures, go to File > Export > FBX (.fbx).

  8. Change the ‘Path Mode’ to ‘Copy’, then click the ‘Embed Textures’ icon. This makes sure that all of the textures are embedded into your model. _images/blender-export.png

  9. Give your avatar a unique name.

  10. Click the ‘Export FBX’ button.

Now, you are ready to bring your avatar into 8 agora.

Example: Update Eyelashes from an Image
  1. Save this texture to a directory where you will remember.
  2. From the Outliner, open the ‘Armature’ tree and select ‘Eyelashes’.
  3. In the Toolbox below, click the ‘Materials’ icon. _images/materials-tab.png
  4. Click the ‘+’ button next to the material list to create a new material slot.
  5. Click ‘+ New’ to add a new material.
  6. Rename the new material to ‘lashes’.
  7. At the bottom of the Blender window, switch to ‘Edit Mode’. _images/edit-mode.png
  8. Under the material list, click ‘Assign’.
  9. Scroll to the ‘Transparency’ section. Check the Transparency box and change the ‘Alpha’ value to 0.00. _images/transparency-setting.png
  10. Scroll to the ‘Specular’ section. Set the specular color to black. _images/specular-setting.png
  11. Change to the ‘Textures’ view. _images/texture-tab.png
  12. Click ‘+ New’ to add a new texture.
  13. Scroll to the Image section. Click ‘Open’ and find the lashes texture named ‘mixamo_eyelashes’ you previously downloaded. Click ‘Open Image’. _images/image-setting.png
  14. Check the ‘Alpha’ options in the following sections: Image, Preview, Texture, Influence
  15. Go to File > External Data > Pack All Into .blend. This will include the texture in your model.

See Also

Tutorial: Add a Scattering Effect

Subsurface Scattering (SSS) is the diffuse reflection caused by light entering a material, being absorbed, scattered, and eventually exiting the material. It’s critical for surfaces like paper, marble, wax, and realistic skin. You can add this effect to your avatar in 8 agora.

On This Page

Subsurface Scattering Map and Value

Subsurface scattering (SSS) is noticeable when light passes through a thin translucent object like an avatar’s skin. It causes the diffusion of light within the shallow top layer of skin.

Scattering is composed of a “scattering value” and a “scattering map”. By setting the scattering value and map, you can influence how light scatters on the geometry of an avatar.

  • The scattering value is a [0,1] number which sets the amount of scatter.
  • The scattering map is gray scale image that masks the areas of scatter. It is based on the avatar’s UV map.
Add Scattering to an Avatar

You can easily add scattering to an avatar by adding the value and map to the avatar’s FST file.

  1. Create a custom avatar and package it using the Avatar Packager.
  2. Create a scattering map for the subsurface scattering in Adobe Photoshop or its equivalent.
  3. Open your avatar’s FST file in a text editor of your choice.
  4. Add scattering information to the avatar’s FST file. For example:
materialMap = { "body_mat": { "scattering": 1.0, "scatteringMap" : "![skinMap.jpg](http://.../skinMap.jpg)" } }
  1. Wear the avatar to observe the scattering effects in 8 agora.

Here’s an example of the scattering effect. The left image has no scattering and the right image has scattering. You can see the red diffuse reflection along the shadow line.

No Scattering Scattering
_images/no-scattering.png _images/scattering.png

Here are the scattering skin maps for this avatar.

_images/skin-map.png _images/skin-map-2.png

See Also

Wearables

Wearables are objects that attach to your avatar. They can be hats, skirts, glasses, headphones and anything else that can accessorize your look in-world. You can express your individuality by creating wearables of your own and putting them on.

Before you can use a custom wearable, you must first host its FBX and JSON files in a place that is publicly accessible to 8 agora. You can use any cloud platforms including Amazon S3, Google Cloud Storage, Microsoft Azure, Dropbox, etc.

Build a Custom Wearable

Wearables are simply 3D models that are customized to fit on your avatar. Therefore, the first step in creating your wearable is to build one or find an existing model that you want to use.

There are a few different applications you can use to build and edit the 3D model for your wearable, including:

Some guidelines to follow when you’re building soft wearables like clothes:

  • Your soft wearable should be designed to fit a particular type of avatar. Since avatars vary in size and structure, a soft wearable designed to fit one avatar may not fit another one as well.
  • The soft wearable should be slightly larger than the avatar to avoid clipping. Clipping is when one 3D object goes through another 3D object without colliding.
  • Your soft wearable’s shape should match the avatar’s.
  • The soft wearable should have similar or the same weights as the avatar.

When building soft wearables like clothes, ensure that you are making it to fit the avatar well. Its mesh should match the avatar’s and have a higher weight.

When building your model, be sure to follow these guidelines to ensure that it is compatible with 8 agora. Once you’re done editing your model, export the file as an FBX or OBJ file. You’ve now created your own custom model!

Note

See Also

Entities

To build any content in 8 agora, whether it is an object that you interact with, or a domain to host an event, you need entities. Entities are the building blocks of the virtual world, and are used to build items as simple as boxes and squares to complex animated items such as butterflies and stereo equipment. Each entity type has its own set of properties that define its appearance and behavior.

In This Section:

Create New Entities

We are continually surprised by the ingenuity and creativity of the content creators in our community. You too can join this community by creating new entities. The easiest way to start building is to use 8 agora’s Create app.

Note

You can only use the Create app in domains where you have the permission to build.

To add a new entity to your domain:

  1. In Interface, pull up your tablet or HUD and go to Create.
  2. In the Create app, select the type of entity you want to create.
  3. Depending on the entity type, the behavior will be different:
    • For model and material entities, enter the URL that you want to import.
    • For all other entities, an entity with the default settings will appear in front of your avatar.
  4. Edit the properties of your entity so that it looks and behaves like you want it to.

_images/add-cube.png

Types of Entities

You can choose from the following entity types:

  • MODEL entities are 3D models that you can import in-world.
  • CUBE entities are used to create basic box shaped entities.
  • SPHERE entities are used to create basic sphere shaped entities.
  • LIGHT entities are balls or beams of light that are used to add local lighting effects and spotlights to an area.
  • TEXT entities display text against a flat plane, similar to a whiteboard or blackboard.
  • IMAGE entities display an image from a specified URL.
  • WEB entities display a web page from a specified URL. Only 20 web entities can run at the same time in a domain.
  • ZONE entities are 3-dimensional areas that allow you to create a custom lighting environment.
  • PARTICLE entities create dynamic effects that are made of many small parts, such as smoke clouds or falling water.
  • MATERIAL entities modify the existing materials on other entities and avatars.

See Also

Change How Entities Look

You can edit an entity’s size, color, position and rotation using your mouse or trackpad. To edit an entity, open the Create app and either select the entity or find it in the Entity List.

Note

You can select and edit multiple entities at once. The behavior will be different based on the type of property you’d like to set:

  • Numbers: When using the slider, an offset will be applied to each of the original values. When typed in, the new value will replace the original values for the selected entities.
  • All other field types (checkboxes, input fields, etc): The new value will replace the original values for the selected entities.
_images/select-entity.PNG

On This Page

Change the Color of an Entity

You can manually change the color of most entity types in the Create app. With the entity selected, click on ‘Properties’ and scroll down to the ‘Color’ settings. Here are the different color settings you can configure:

Setting Description Supported Entity Type(s)
Color The color of an entity. Cube, Sphere
Light Color The color of the light. Light
Text Color The color of the text. Text
Background Color The color of the background of the text. Text
Key Light The color of the lighting in the zone. Select ‘Inherit’ to keep the lighting of the domain, or ‘Off’ to remove all lighting. Zone
Sky Box The color of the ceiling in the zone. Select ‘Inherit’ to keep the color of the domain, or ‘Off’ to remove all color. Zone
Ambient Light Configures the amount of ambient light in the zone. Ambient light reflects on content within your zone. Zone
Haze > Haze Color When Haze is turned on, the color of the haze in the zone. Zone
Haze > Glare Color When Haze is turned on, the color of the glare based on the key light. Zone
Bloom Configures how much the bright areas of the scene glow. Zone
Color > Color As the particle moves, sets the color of the particle at the start, middle, and finish. Particle
Color > Color Spread The spread of color that each particle is given, resulting in a variety of colors. Particle
Set the Size of an Entity

For cube, sphere, text, image and web entities, you can change its size directly in your environment by selecting and dragging the small boxes inside the object.

_images/resize-entity.gif

For all entities, you can also set the size manually in the Create app. With the entity selected, click on ‘Properties’ and scroll down to the ‘Size’ settings. Here are the different size settings you can configure:

Setting Description Supported Entity Type(s)
Spatial > Local Dimensions The size of the entity. If the entity is parented to an avatar, this value remains the original dimensions value while the avatar scale changes. All
Spatial > Dimensions The size of the entity. If the entity is parented to an avatar, this value will change if the avatar scale changes All
Spatial > Scale Sets the size of the entity as a percentage of its original size. All
Fall-Off Radius The distance from the light’s center where the intensity is reduced. Light
Spotlight Cut-Off Affects the size of the spotlight’s beam; the higher the value, the larger the beam. Light
Line Height The height of each line of text. Text
Emit > Dimensions The outer limit radius that particles can be emitted from. Particle
Emit > Radius Start The inner limit radius that particles can start emitting from. Particle
Size > Size The size of each individual particle in the entity. Particle
Size > Size Spread How far apart a particle is from other particles. Particle
Rotate an Entity

All entities can be rotated directly in your environment by selecting and dragging the circles around the object.

_images/rotate-entity.gif

You can also set the rotation manually in the Create app. With the entity selected, click on ‘Properties’ and scroll down to the ‘Rotation’ settings. Here are the different rotation settings you can configure:

Setting Description Supported Entity Type(s)
Spatial > Local Rotation The orientation of the entity relative to its parent. All
Spatial > Rotation The orientation of the entity with respect to world coordinates. All

Note

You can switch between ‘Local’ and ‘World’ using the keyboard shortcut T.

Move an Entity

All entities can be moved directly in your environment by selecting and dragging the object to the correct location. Alternatively, you can use the arrows around the object to move it in only one direction.

_images/move-entity.gif

You can also set the position manually in the Create app. With the entity selected, click on ‘Properties’ and scroll down to the ‘Position’ settings. Here are the different position settings you can configure:

Setting Description Supported Entity Type(s)
Spatial > Local Position The position of the entity relative to its parent. All
Spatial > Position The position of the entity with respect to world coordinates. All

Note

You can switch between ‘Local’ and ‘World’ using the keyboard shortcut T.

See Also

Define an Entity’s Behavior

An entity’s behavior controls its interactions with other entities and avatars in 8 agora. Can an entity be grabbed, does it collide with other entities and avatars, or can a change in the domain’s gravity affect it? You can check and change an entity’s behavior by editing its properties.

Note

You can select and edit multiple entities at once. The behavior will be different based on the type of property you’d like to set:

  • Numbers: When using the slider, an offset will be applied to each of the original values. When typed in, the new value will replace the original values for the selected entities.
  • All other field types (checkboxes, input fields, etc): The new value will replace the original values for the selected entities.

On This Page

Set an Entity to Respond to Physics

If you want an entity to respond to physics or other entities and avatars, you need to make it dynamic. This allows a box to respond to gravity or a ball to bounce when it hits the floor. If an entity is not dynamic, it is static and has no gravity and no velocity. It can only be moved by a user.

To make an entity dynamic:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Select your entity on the ‘Entity List’ window or just click on it.
  3. Go to the ‘Properties’ tab, scroll down to ‘Collision’ and check ‘Dynamic’.
Set Entity Behavior on Collision

When an entity has no collision properties, it moves through other entities and avatars like it’s not a solid object. For an entity to collide when it comes in contact with another entity or avatar, its collision properties need to be changed. With the entity selected, click on ‘Properties’ and scroll down to the ‘Collision’ settings.

Here are the different collision settings you can configure:

Collides With Description
Static Entities Your entity will collide with static entities. Keep in mind that if your entity is a static entity, it will not collide with another static entity. Only a dynamic entity can collide with a static entity.
Kinematic Entities Your entity will collide with kinematic entities. Kinematic entities have velocity, but are not dynamic. Their behavior is controlled by an external script.
Dynamic Entities Your entity will collide with other dynamic entities.
My avatar Your entity will collide with your avatar.
Other avatars Your entity will collide with other user’s avatars.
Collision Sound You can make your entity emit a sound whenever it collides with other entities.
Make an Entity Grabbable

Your entity’s grab properties determine how it behaves when you or another user interacts with it. By default, ‘Grabbable’ and ‘Follow Controller’ are checked.

Here are the different grab settings you can configure:

Behavior Description
Grabbable You or other users can grab this entity.
Follow Controller Your entity will follow the movements of your hand controller instead of your avatar’s hands. If your avatar’s arms are shorter than your real arms, your entity will be grabbed where the controller is (at a distance from your avatar’s hands).
Set an Entity to Trigger Scripts

If you want your entity to trigger a script when you, other users, or other entities come in contact with it, you can do so by editing its properties.

Here are the different trigger settings you can configure:

Behavior Description
Triggerable Your entity can trigger a script. For instance, you can trigger a cube entity to run a script asking for a tip every time you click it.
Make an Entity Cloneable

You can clone your entity to create other entities with the same properties as yours. While creating clones, you can set how long they’ll exist, how many clones you can create, how the clone responds to physics, and if the clone is an avatar entity.

Here are the different clone settings you can configure:

Behavior Description
Cloneable Your entity can be cloned. You can change the ‘Clone’ settings to manipulate your cloned entity’s behavior.
Cloneable > Clone Lifetime Select this option to set how long (in seconds) your clone will exist.

Cloneable >

Clone Limit

 Select to set a limit to how many clones you can create. If you don’t want to have a limit, set the value to 0 .
Cloneable > Clone Dynamic Select to make the clone entity a dynamic entity.
Cloneable > Clone Avatar Entity Select to specify if a cloned entity is created as an avatar entity. An avatar entity doesn’t exist in the Entity Server. Instead, it is specific to a user’s Interface client. For instance, say a user comes to visit the coffee shop in your domain. The user grabs a coffee cup that’s been cloned. Once the user is done visiting, the cloned entity leaves with their avatar, ensuring there isn’t any clutter left behind. This feature ensures that your entity is cloned locally for each avatar.

Note

A user does not need create permissions to clone an entity or edit an unlocked entity.

To make entities cloneable in your domain (this can only be done with unlocked entities):

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Select the entity of your choice in the ‘Entity List’ window.
  3. Go to the ‘Properties’ tab, scroll down, and check ‘Cloneable’.

Keep in mind that any user can now clone the entities that are cloneable. If you don’t want any users to clone your entity or any entities in your domain, you can do one of the following:

  • Lock any entities you don’t want cloned, then restrict user ‘Lock’ permissions to the users of your choice.
  • Set entity filters to prevent users from editing entities in your domain.
Set an Entity to Cast a Shadow

You can make your entity behave like a real world object by making it cast a shadow on other entities and avatars. In 8 agora, entities cast shadows only from the key light, not from the light entities. The key light is a parallel source of light, like the sun.

Here are the different shadow settings you can configure:

Behavior Description
Cast Shadow Your entity will cast a shadow on other objects and avatars.

See Also

Apply Physics to Entities

Your 8 agora VR experience is made realistic with the help of a physics engine. 8 agora uses this engine to simulate an object’s behavior according to the Newtonian laws of physics. For example, if you hit a ball with a bat in 8 agora, the physics engine computes these movements and makes the ball spin away from the bat after collision. You can modify an entity’s physics behavior using the Create app.

Note

You can select and edit multiple entities at once. The behavior will be different based on the type of property you'd like to set:

  • Numbers: When using the slider, an offset will be applied to each of the original values. When typed in, the new value will replace the original values for the selected entities.
  • All other field types (checkboxes, input fields, etc): The new value will replace the original values for the selected entities.

On This Page:

Apply Physics to an Entity

To apply physics properties to an entity:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Select or add any entity of your choice.
  3. In the ‘Properties’ tab, scroll down to the Physics section. When you first create an entity, the physics properties are set to the default values you can see in the image below. _images/physics-prop.PNG
Change an Entity’s Velocity

Velocity is the speed of an object in a certain direction. All entities that have a position and orientation in 8 agora will have linear and angular velocity. These velocities might be zero, but they still exist.

Linear Velocity

Type: 3D Vector
Unit: meters/second
Default Value: (0,0,0)

You can choose to make an entity move in a specified direction by changing its linear velocity. The direction is determined using the x, y, or z coordinates in a 3D Cartesian coordinate system. The 3D Cartesian coordinate system helps you determine the position of your entity in space. Every time your entity moves, its x, y, and z coordinates change to show you the new position. To change an entity’s linear velocity:

  1. In the ‘Properties’ tab, scroll down to ‘Linear Velocity’ property. The default value is 0.0000.
  2. Say you want to move a cube entity upwards in a straight line. Change the Y value for linear velocity to 0.1000 and see your cube start moving.
  3. If you want your cube to change direction, change the x and z values to 0.1000.
Angular Velocity

Type: 3D Vector
Unit: radians/second
Default Value: (0,0,0)

Angular velocity is the speed at which an object is rotating in a certain direction. It is measured in radians/second. To change an entity’s angular velocity:

  1. In the ‘Properties’ tab, scroll down to the ‘Angular Velocity’ property. The default value is 0.0000.
  2. Change the X value to see your cube entity start rotating around an axis.
  3. If you want your cube entity to change its angular velocity direction, change the Y and Z values.
Set How a Moving Entity Slows Down

Type: Scalar
Range: 0 - 1
Default Value: 0.00

In 8 agora, damping represents how much of an entity’s linear or angular velocity is lost over time. All moving objects we see in the real world experience some friction with air, reducing their velocities over time. Damping is used to approximate this effect of the real world in 8 agora. So if the damping of an object is 0.00, it will not lose any velocity and it will not slow down. If the damping of an object is 1.00, it will lose all its velocity and stop immediately. If you want to throw a ball and have it slow down over time, you can add a damping value to do so.

To set the linear damping of an object:

  1. In the ‘Properties’ tab, scroll down to the ‘Linear Damping’ property. The default value is 0.00.
  2. Change the linear velocity of a cube to any value.
  3. Change the ‘Linear Damping’ value to 1.00 to make the cube stop moving. You can change this value to anything between 0.00 and 1.00 to make an entity slow down over time.

To set the angular damping of an object:

  1. In the ‘Properties’ tab, scroll down to the ‘Angular Damping’ property. The default value is 0.00.
  2. Change the angular velocity of a cube to any value.
  3. Change the ‘Angular Damping’ value to 1.00 to make the cube stop moving. You can change this value to anything between 0.00 and 1.00 to make an entity slow down over time.

_images/gif-1.gif

Set an Entity’s Friction and Bounciness

Range: 0 - 1
Default Value: 0.5000

When a dynamic entity collides with another entity, it can react in a number of ways depending on its physics properties. The values you set for friction and bounciness determine this reaction. By default, both values are 0.5000.

Friction is a measure of how slippery an object is. When an entity with low friction collides against another object, it will slide a good distance before coming to a stop. On the other hand, an entity with high friction will slow down much faster. To set the friction of an entity:

  1. In the ‘Properties’ tab, scroll down to the ‘Friction’ property.
  2. Change the value to anything between 0.0000 and 1.0000. An entity with a friction of 0.0000 will be very slippery, while an entity with a friction of 1.0000 will have a coarse or sticky surface.

Bounciness is the energy an entity conserves during collision. For example, a ball will conserve more energy and bounce more than a heavy cube. To set the bounciness:

  1. In the ‘Properties’ tab, scroll down to the ‘Bounciness’ property.
  2. Change the value to anything between 0.0000 and 1.0000. An entity with a bounciness of 0.0000 will conserve no energy, while an entity with a bounciness of 1.0000 will conserve all of its energy.
Set an Entity’s Density

Type: Scalar
Unit: kg/meter3
Range: 100 - 10000
Default Value: 1000.0000

An entity’s density is the ratio of its mass to its volume. For example, an entity with low density is made of light materials such as wood, while an entity with high density is made of dense materials such as iron.

In 8 agora, the maximum (10000) and minimum (100) values of density were chosen for stability. It’s difficult to perform stable physics calculations between objects of very disparate masses (such as a light feather and an iron ball). To help keep the environment stable, we picked conservative density limits.

To change this value, scroll down to the ‘Density’ property in the ‘Properties’ tab. Change it to the value of your choice.

Set How an Entity Moves in a Gravitational Field

Type: 3D Vector
Unit: meters/second2
Default Value: (0,0,0)

In the Create app, ‘Gravity’ is the acceleration of the entity, as if it were in a uniform gravitational field. This property controls how an entity behaves when you change the gravity of a domain. For example, if a ball is floating in zero gravity, it will float downwards when you increase gravity downwards.

To change this value, scroll down to the ‘Gravity’ property in the ‘Properties’ tab. Change it to the value of your choice.

See Also

Add a Material Entity

You can add a material entity to an object in your domain. A material entity contains specific material data that determines the texture and shading of an object. For example, if you want to create a castle in your domain, you need your walls to look like they’re made of rough gray stone. You can do this by adding a castle wall material entity to your walls.

Before adding a material entity, make sure you have created a material using the PBR Materials Guide.

On This Page:

Generate a Material Entity

To add a material to your object in 8 agora, you need to specify the material data in a JSON file or add the material directly into the Create app.

Note

We are aware of the difficulties involved in converting your material data to a JSON file and are working on making the process easier for our users. In the meantime, we recommend embedding your material data in your models as FBX files if you are facing difficulties generating a JSON file.

This is what the JSON file for a sample castle wall material looks like:

{
  "materialVersion": 1,
  "materials": [
    {
      "name": "CastleWall",
      "model": "hifi_pbr",
      "albedo": [1, 1, 1],
      "albedoMap": "https://hifi-public.s3.amazonaws.com/sam/MaterialExportGuide/MaterialEntities/MatOne/CastleWall/CastleWall_Base_Color.png",
      "roughnessMap": "https://hifi-public.s3.amazonaws.com/sam/MaterialExportGuide/MaterialEntities/MatOne/CastleWall/CCastleWall_Roughness.png",
      "normalMap": "https://hifi-public.s3.amazonaws.com/sam/MaterialExportGuide/MaterialEntities/MatOne/CastleWall/CastleWall_Normal.png"
    }
  ]
}

This file contains all related material data, such as the color, roughness, and other texture and shading information. Note that you can edit this information programmatically with the Material EntityType in our API, and define its properties using EntityProperties-Material.

Add a Material Entity
Use the Material Entity JSON File

Note

At this time, we have no way to automatically generate a JSON file with another tool, and you will need to write your own JSON file.

Once you have your material entity JSON file, you can add it to an object in 8 agora. Let’s add the castle wall material to a box entity in your domain.

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Create a wall. Click the ‘Cube’ icon to add a box entity and change the dimensions to make it resemble a wall.
  3. Go to the Create tab and click on the ‘Material’ icon to add a material entity. Enter the material’s JSON file URL when prompted. You will see the material entity represented as a small sphere.
  4. Click and select the wall. Go to the ‘Properties’ tab and copy the parent ID under the ‘Name’ box.
  5. Click and select the material entity. Go to the ‘Properties’ tab and paste the copied parent ID in the ‘Parent’ box. You will see the material applied to the wall. In this step, you are parenting or applying a material to an entity.

_images/material-entity.gif

Use the materialData Field

To add a material entity directly into the Create Tools app:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Create a wall. Click the ‘Cube’ icon to add a box entity and change the dimensions to make it resemble a wall.
  3. Go to the Create tab and click on the ‘Material’ icon to add a material entity.
  4. Enter materialData when you’re prompted for a ‘Material URL’.
  5. Click and select the wall. Go to the ‘Properties’ tab and copy the parent ID under the ‘Name’ box.
  6. Click and select the material entity. Go to the ‘Properties’ tab and paste the copied parent ID in the ‘Parent’ box. In this step, you are parenting or applying a material to an entity.
  7. Scroll down to the ‘Material Data’ field. Click ‘Clear Material Data’ and then paste the following JSON data:
  {
    "materialVersion": 1,
    "materials": [
    {
      "name": "CastleWall",
      "model": "hifi_pbr",
      "albedo": [1, 1, 1],
      "albedoMap": "https://hifi-public.s3.amazonaws.com/sam/MaterialExportGuide/MaterialEntities/MatOne/CastleWall/CastleWall_Base_Color.png",
      "roughnessMap": "https://hifi-public.s3.amazonaws.com/sam/MaterialExportGuide/MaterialEntities/MatOne/CastleWall/CCastleWall_Roughness.png",
      "normalMap": "https://hifi-public.s3.amazonaws.com/sam/MaterialExportGuide/MaterialEntities/MatOne/CastleWall/CastleWall_Normal.png"
    }
    ]
  }

_images/material-data.gif

See Also

Add Sound to Entities

Entities have the ability to add a collision sound, so that the entity will emit a sound every time it comes in contact, or collides, with another entity.

To add a sound:

  1. In Interface, pull up your Tablet or HUD and go to Create.
  2. Select the entity.
  3. In the Create app, click on ‘Properties’ and scroll down to the ‘Collision’ settings.
  4. Check the box for ‘Collides’, then enter the URL of the audio file for ‘Collision Sound’.
Tutorial: Create a Bouncing Ball

In this example, we will walk through the steps to create a bouncing ball that emits a sound every time it hits a wall.

  1. Create a wall to bounce your ball off of:
    1. Add a cube entity to your domain.
    2. Resize the entity to approximately 10m wide, 10m high and 1m deep (X:10, Y:10, Z:1).
  2. Create a ball by adding a sphere entity to your domain. Optionally, change the color of your ball, so that it is different than your wall.
  3. In the Create app, click on ‘Properties’ and scroll down to the ‘Collision’ settings. Check the box for ‘Collides’ and ‘Dynamic’.
  4. For ‘Collision Sound’, enter the URL of your sound file. The sound must be a .wav file, uncompressed, 48Khz, 16 bit. The URL can be either a web address, or an ATP reference to the assets on this domain server.
  5. Scroll down to the ‘Physics’ settings. Set the ‘Gravity’ for Y to -5. This will cause your ball to fall a little more slowly than things on earth (use -9.8 if you want that). Gravity is in units of m/s2.

As soon as you click off the ball, the gravity will cause the ball to fall downwards. When it hits the floor, it should stop or bounce a little and the sound should play.

See Also

Define Interactions with Avatars

In real life, you interact with objects on a daily basis. In 8 agora, your avatar can also interact with objects (entities) in the metaverse. There are a number of ways you can define the interactions you have with objects: you can write scripts to change the properties of an entity. You can create entities that are unique to your avatar (we call these “avatar entities”). And don’t forget that you can set an entity’s behavior and collision properties, so that objects are grabbable, triggerable, or dynamic.

On This Page:

Control Interactions with Entities using Scripts

When your avatar comes in contact with an entity, you can control its interactions with the entity using simple scripts.

An interaction between an avatar and an entity occurs when the avatar comes in contact with an entity’s bounding box. The bounding box (or bounds) is the frame that is around the outside of the entity. In the case of a cube, the bounds are the exact size and shape as the entity. However, in the case of more complex objects, the bounds might be larger than the actual mesh model.

There are two methods you can use to script these interactions. Entities.enterEntity() occurs when the avatar contacts the bounding box, not the model itself. Similarly, Entities.leaveEntity() occurs when the avatar exits the bounding box.

Tutorial: Enter a Box to Change Its Color

The following example walks you through the process of creating a simple entity, and scripting an interaction between the entity and your avatar. When your avatar comes in contact with the box, the box will change color. When your avatar moves away, the box will return to its original color.

  1. Create a cube entity. _images/add-entity.png

  2. The following script changes the color of the cube as you approach (yellow) or leave (pink) its bounding box. Save it to a file called interactions-example.js.

    (function(){
    this.enterEntity = function(entityID) {
        Entities.editEntity(entityID, {
            color: { red: 255, green: 64, blue: 64 },
        });
    };
    this.leaveEntity = function(entityID) {
        Entities.editEntity(entityID, { 
            color: { red: 255, green: 190, blue: 20}
        });
    };
});

  3. In the Create app, click on ‘Properties’ and scroll down to the ‘Script’ settings. Enter the path and file name to interactions-example.js that you created above. Press ‘Enter’.

A full range of entity parameters are controllable with these functions. Entities can be used as invisible sensors or expanded to cover an entire building with the functions running while you are inside, and stop when you walk out.

Create Avatar Entities

Your avatar will also interact with avatar entities. Avatar entities are entities that are attached to your avatar, and unlike domain entities, they travel with your avatar when you go to other domains. Examples of avatar entities include wearables such as glasses or hats.

Avatar entities live on the Avatar Mixer, so they are connected to (and move with) your avatar. We’ve listed the ways you can create avatar entities with some examples:

  1. Create a wearable: All wearables are avatar entities.

  2. Clone as an avatar entity: When you clone an entity as an avatar entity, you make a copy of the entity and attach it to your avatar. Every copy of that entity will now leave with the avatar when they leave the domain. For example, if you have a coffee shop in your domain, you can set all coffee cups to be cloned as avatar entities. Any user who clones a coffee cup will take the avatar entity with them when they exit the domain. You can keep your domain free of clutter using this property.

  3. Add an avatar entity using a script: You can add an avatar entity using scripts. For example, you can create a script to have a pet (avatar entity) follow you around as you explore 8 agora.

    This example script adds a cube as an avatar entity to your domain.

    var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Quat.getFront(MyAvatar.orientation))},
    "avatar");

See Also

Prioritize Zones Within Your Domain

Whenever someone enters your domain, they must load all domain content, including avatars, models, textures and external resources that are used in the domain. Many of these resources are not optimized and can take a while to load, especially in large domains or events with lots of avatars. In these situations, you can prioritize a zone so that all avatars within that zone move smoothly to all observers. The avatars within the zone are known as “heroes”. Examples of heroes include a keynote speaker at an event or performers at a concert.

Avatar Hero Zones

All avatars in hero zones are allocated additional bandwidth, allowing them to load completely and move smoothly within the zone. You can set the amount of bandwidth that is dedicated to your hero zones in your domain settings. Go to http://localhost:40100/settings and scroll to Avatar Mixer > Advanced Settings > Hero Bandwidth to set the bandwidth.

To create an avatar hero zone:

  1. In Interface, pull up your HUD or Tablet and go to Create.

  2. Click the ‘Zone’ icon to create a zone entity. You’ll see a wireframe shape showing the zone’s bounding box.

  3. If you are unable to view the zone’s bounding box, go to Edit > Show Zones in Create mode and select the option. Your zone should now be visible.

  4. Go to the ‘Properties’ tab. Here, we recommend that you add a name to your zone.

  5. For ‘Avatar Priority’, choose the desired setting:

    • Inherit: If the zone is nested within another zone, then it will inherit the priority of the parent zone. For single zones that are not nested, this option defaults to “Crowd”.
    • Crowd: The zone will not be prioritized in any way.
    • Hero: The zone will be given preferential treatment, and additional bandwidth will be given to heroes within the zone. This ensures that all avatars within the zone will load completely and move smoothly.

  6. Like all entities, you can customize your zone by changing the lighting, size, or shape of the zone.

At any point, you can change the properties of your hero zone. These changes will take place immediately, and the zone will be updated to match your new settings.

Entity Tutorials

Walk through our online tutorials to get a deeper understanding of entities and their role in the metaverse.

Tutorial: Create a Gold Spotlight

In this tutorial, you will learn how light entities work by creating a gold spotlight that shines down a wall. A light entity behaves like a ball or a beam of light, and is used to add local lighting effects or spotlights to an area.

On This Page:

Prerequisites

Consider getting familiar with the following concepts before starting this tutorial:

Create a Wall to Shine the Light On

Your gold spotlight needs a surface to shine on. Create this surface or wall in the Create app:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Click the ‘Cube’ icon to create a cube entity.
  3. Go to the ‘Properties’ tab and make the following changes:
    1. Change the color of the cube to teal (Red = ‘0’, Green = ‘128’, Blue = ‘128’).
    2. Change the dimensions of the cube to make it bigger and look more like a wall. We’ve used the following local dimensions:
      • X = ‘0.1300’
      • Y = ‘2.4000’
      • Z = ‘3.2000’

You’ve made your wall! _images/teal-wall-prop.PNG

Create the Gold Spotlight

Create and edit the light entity to get a soft gold spotlight.

Note

The domain sun shines from one side, so one side of the wall is already bright. Light from the light entity won't show up on the bright side of the wall.

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Click the ‘Light’ icon to create the light entity.
  3. Grab and move the entity to the top and center of the wall. You’ll notice there is a white light shining on the wall. The light is small because of low brightness. This type of light is a point light and it emanates in all directions equally. It is meant for general area lighting as it has a bright point in the middle and fades as it radiates out.
  4. Go to the ‘Properties’ tab and modify the light entity to make a gold spotlight:
    1. Change the color of the light to gold (R = ‘255’, G = ‘215’, B = ‘0’).
    2. You can make the light entity brighter by changing its intensity. Change the ‘Intensity’ to ‘100’. You’ll see that the light is now covering a larger area and is much brighter.
    3. You can modify the light entity’s ‘Fall-off Radius’ so that the it dims gradually towards the edges. The ‘Fall-off Radius’ defines the shape of the light curve of a light. A larger radius will simulate a larger light, which will “fall-off”, or dim, more gradually. It is the distance from the light at which the intensity is reduced by ‘25%’. Change this value to ‘0.5’.
    4. Select the ‘Spotlight’ checkbox to convert the light entity to a spotlight.
    5. Change the ‘Spotlight Cut-off’ to ‘50’. This property determines the radius of the spotlight. A higher cut-off value corresponds with a larger spotlight radius. You should see the beam tighten get smaller.
    6. Change the ‘Spotlight Exponent’ to ‘5’. This property affects the softness of the beam. You should see the edge of the beam soften.
    7. Rotate the spotlight so that it’s facing down the wall by changing the ‘Local Rotation’s’ X value to ‘-90.0000’. A spotlight positioned like this can be used for a soft lighting effect over paintings or wall hangings in your world. _images/spotlight-prop.PNG

Congratulations! You’ve created a soft gold spotlight! You can experiment with different spotlight exponents, cutoff values, and intensity combinations for varied effects.

_images/spotlight.PNG

See Also

Tutorial: Create a Smoke Fountain

In this tutorial, you will learn how particle entities work by creating a smoke fountain that emits multiple colors. Particle entities are used to create effects made up of many small particles, such as smoke, confetti, or falling leaves.

On This Page

Prerequisites

Consider getting familiar with the following concepts before starting this tutorial:

Create a Smoke Fountain

Particle entities are used to create effects that are made up of smaller parts such as smoke, confetti, or falling leaves. The entity’s effect and appearance is defined by its texture. The default texture is a wispy smoke texture, but you can replace this texture with your own to create your desired effect.

To create your smoke fountain using a particle entity:

  1. In Interface, pull up your HUD or Tablet and go to Create.

  2. Click the ‘Particle’ icon to create the particle entity. By default, the particle entity emits smoke.

  3. Go to the ‘Properties’ tab, and set the following values:

    Property Value Description
    Lifespan 1.20 This property defines how long each particle lives, in seconds.
    Max Particles 356 Max particles defines how many particles are rendered at one time. Older particles, whose lifespans are completed, are swapped out for newer ones. Increase this value to increase the number of particles for your effect.
    Emit Rate 524 The emit rate defines how many particles are emitted per second.
    Speed Spread 2.10 This defines the range of speeds the particles will emit, which changes as per the Emit Speed. For example, if Emit Speed is 5 and Speed Spread is 1, the particles will have speeds that range from 4 to 6.
    Emit Dimensions x = 0.60, y = 10.00, z = 0.30 Particles are emitted from a radius. This property defines the outer limit of that radius.
    Size Start = 0.40, Middle = 0.80, Finish = 0.80 This property determines the size of each particle and how it changes from emission to end of life. Here, it starts at 0.4 and when its life is completed, the particle has increased in size to 0.8.
    Color Start = #000000, Middle = #FFFFFF, Finish = #000000 This determines the colors the particles will emit. Start, middle, and finish define the color spectrum to be emitted.
    Color Spread #FFFFFF This determines the color spectrum of the particles.
    Emit Acceleration x = 0, y = -9.09, z = 0 This is the acceleration of each particle during its lifetime.
    Spin Spread 147.40 The spread in spins for the particle entity. Changing this value results in a variety of spins for different particles.
    Horizontal Angle Start = 0, Finish = 180 This is the angle range in degrees at which the particles are emitted along the z axis and rotated around on the y axis.
    Vertical angle Start = 150, Finish = 180. This is the angle range in degrees at which the particles are emitted along the x axis and rotated around on the z axis.
_images/smoke-fountain.gif

Congratulations! You’ve created a multi-colored smoke fountain! You can experiment with different settings to simulate particle movement, such as a waterfall, confetti gun, or falling leaves.

See Also

Tutorial: Modify a Zone Entity

A zone entity is a 3D area where you can create custom lighting environments. You can define zone boundaries using shapes and customize the zone’s light properties such as its intensity, direction, and color to create different effects.

The mini tutorials on this page show you how zone entities work and how you can edit their properties to create areas with different lighting effects.

On This Page:

Prerequisites

Consider getting familiar with the following concepts before starting this tutorial:

Create a Zone Entity

To create a zone entity:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Click the ‘Zone’ icon to create a zone entity. You’ll see a wireframe shape showing the zone’s bounding box.
  3. If you are unable to view the zone’s bounding box, go to Edit > Show Zones in Create mode and select the option. Your zone should now be visible.
  4. Go to the ‘Properties’ tab, and add a name ‘Zone-1’ for your zone.
Create Nested Zones with Different Lighting

Each zone entity you create can have different properties. When your avatar moves through different zones, you will experience each zone’s properties. In the case of nested or overlapping zones, you will experience the properties of the smallest zone you are currently inside.

You can understand how an avatar experiences lighting in a zone using this mini tutorial:

  1. Create Two Zone Entities
  2. Nest One Zone Inside the Other
  3. Add Different Lighting Effects to Each Zone
Create Two Zone Entities

Follow the steps to create a zone entity to create two zone entities named ‘Zone-1’ and ‘Zone-2’.

Note

By default, zone entities are created at your current position, so to see the zone entities you just created, you may need to reposition your avatar.

Nest One Zone Inside the Other

To nest a zone, you have to resize one zone to make it smaller than the other, and change its position to bring it inside the larger zone.

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Select ‘Zone-1’ either from the Entity List or directly in Interface.
  3. In the ‘Properties’ tab, change the dimensions of ‘Zone-1’ to x=5, y=10, z=5.
  4. If you created both zones without moving your avatar, you don’t need to change the zone’s position. ‘Zone-1’ will already be inside ‘Zone-2’. If you moved while creating the zones, select ‘Zone-1’ and move it inside ‘Zone-2’.
Add Different Lighting Effects to Each Zone

When you create a zone, it inherits the properties of the zone your avatar was standing in. This means that both zones inherit the lighting properties of your domain. You won’t notice when you are entering or leaving a zone.

All lighting effects have three modes:

  • Inherit: The property is inherited from the zone bounding the current zone.
  • Off: The lighting effect is turned off.
  • On: The lighting effect is turned on and can be changed to values of your choice.

The keylight represents a parallel source of light, such as the sun. Let’s change the keylight properties for each zone:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Select ‘Zone-1’ either from the Entity List or directly in Interface.
  3. In the ‘Properties’ tab, change the ‘Key Light’ property to ‘On’ from the drop-down.
  4. Click on ‘Key Light’ color, and add these RGB (255,0,0) values to add a red key light.
  5. Select ‘Zone-2’ either from the Entity List or directly in Interface.
  6. In the ‘Properties’ tab, change the ‘Key Light’ property by selecting ‘On’ from the drop-down.
  7. Click on ‘Key Light’ color, and add these RGB (0,0,255) values to add a blue key light.

When your avatar walks from Zone-1 to Zone-2, you will see the lighting around change from red to blue.

Change a Zone’s Shape

By default, a zone’s shape is a cube, like its bounding box. You can change a zone’s shape to the following:

  • None: This will be the default shape (cube).
  • Box: The zone’s shape will be a box.
  • Sphere: The zone entity’s shape will be a stretched sphere.
  • Ellipsoid: The zone entity will take the shape of an ellipsoid.
  • Cylinder: The zone entity’s shape will be a cylinder.
  • Compound: The zone entity’s shape will be a convex mesh that is an FBX or OBJ file. These complex convex shapes must be composed of multiple shapes. We can’t check against hollowed out interior volumes. For example, if you want a zone shaped like a bowl, you’ll have to build it up from other elements. You can include elements like sides and a floor, especially if you want a user to experience the right collision properties when in the center of the bowl. Upload your FBX or OBJ file to a cloud server, copy the URL, and paste it in ‘Compound Shape URL’.

All shapes will be stretched to fit the zone entity’s dimensions.

Add a Skybox to a Zone

A skybox determines the texture of the sky in your domain. The skybox can be just a color, or an image from a URL. For example, you can have a blue sky or use an image of the night sky with stars as a skybox.

To add a blue sky to your zone:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Select ‘Zone-1’ either from the Entity List or directly in Interface.
  3. In the ‘Properties’ tab, change the ‘Skybox’ property by selecting ‘On’ from the drop-down.
  4. Click on ‘Skybox’ color, and add these RGB (0,0,255) values to add a blue key light.

To add an image of the night sky to your zone:

  1. Host your image on a cloud service and copy the URL.

  2. Create a JSON file that refers to the URL and other skybox properties.

    {
   "Entities": [
       {
           "skybox": {
               "color": {
                   "blue": 255,
                   "green": 255,
                   "red": 255
               },
               "url": SKYBOX_IMG_URL
           },
           "skyboxMode": "enabled",
           "type": "Zone",
           "userData": "{\"grabbableKey\":{\"grabbable\":false}}"
       }
   ],
   "Id": ENTITY_ID,
}

  3. Host the JSON file on a cloud service. Copy its URL.

  4. Select ‘Zone-1’ either from the Entity List or directly in Interface.

  5. In the ‘Properties’ tab, change the ‘Skybox’ property by selecting ‘On’ from the drop-down.

  6. In ‘Skybox source’, add the JSON file’s URL.

You’ll see your zone’s lighting change to the image you specified in the skybox.

Add Ambient Light to a Zone

The ambient light in a zone is a source of light different from the key light and provides background lighting. For example, warm sunlight coming from a sunset in your domain is ambient light.

Similar to the skybox, your ambient light image can be added as a JSON file.

  1. Select ‘Zone-2’ either from the Entity List or directly in Interface.
  2. Change the ‘Ambient Intensity’ to 1.00.
  3. In ‘Ambient Source’, add your ambient light JSON file, or click ‘Copy from Skybox’ to use the same image as the skybox.

Your zone’s ambient lighting will change to the image you’ve provided.

See Also

Tutorial: Display a YouTube Channel

In this tutorial, you will learn how web entities work by creating one displaying a YouTube channel. You can watch videos in 8 agora using this web entity.

On This Page:

Prerequisites

Consider getting familiar with the following concepts before starting this tutorial:

Create a Web Entity

A web entity is a flat object on which you can view any website of your choosing. A web entity lets you access the internet from inside your domain.

To create a web entity:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Click the ‘Web’ icon to create a web entity. By default, a web entity always displays 8 agora’s home page.

Note

Currently, only 20 web entities can run at the same time in a domain to avoid performance issues.

Display 8 agora’s YouTube Channel

You can make the web entity display 8 agora’s YouTube channel.

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Select your web entity and go to the ‘Properties’ tab.
  3. Scroll down until you see the ‘Source URL’ option. Enter the 8 agora YouTube channel URL: https://www.youtube.com/@8agora366. You should see the new page as soon as you hit ‘Enter’.

See Also

Tutorial: Create a Portal

Portals in 8 agora transport you to the domain of your choice. You can use these portals to travel to a domain you visit frequently instead of using the GoTo app on your HUD or Tablet.

On This Page:

Prerequisites

Consider getting familiar with the following concepts before starting this tutorial:

Write a Script for the Portal

A portal is an entity with a script attached (entity script). This attached script defines what happens when a user comes in contact with the portal. We’ve used portal.js, the script used to teleport in 8 agora domains. You can also write your own script to suit your needs.

The portal.js script we’ve used:

  • Uses 8 agora’s JavaScript API to determine when a user walks into the entity and the teleport destination.
  • Includes a sound that will played every time a user uses the portal.
  • Teleports a user to the specified destination.
Create and Edit an Entity to Use as a Portal

Any entity you create to be used as a portal has to be collisionless so that the script can detect when you walk into the entity.

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Create an entity to be used as a portal. This can be a 3D model or a box or sphere entity.
  3. Go to the ‘Properties’ tab and scroll down to ‘Behavior’.
  4. Next to ‘Script’, paste the script URL. In this case, it is ‘portal.js’.
  5. The script takes the location you want to teleport to from the ‘User Data’ field under ‘Behavior’.
  6. Add hifi:// welcome (8 agora’s welcome domain) to the ‘User Data’ field.
  7. Scroll down to ‘Collision’ and uncheck ‘Collides’. This is so that a user can walk into the entity and trigger the script.
  8. Exit Create mode and walk into the entity.

_images/create-portal.png

You will be teleported to 8 agora’s welcome domain.

See Also

Tutorial: Create an Avatar Scaling Button

You can build content in 8 agora that breaks the laws of physical boundaries by making them oversized or extremely small. To give any visiting users access to such an experience, you can add an avatar scaling button to your domain. This will help users fit into the spaces you design.

On This Page:

Prerequisites

Consider getting familiar with the following concepts before starting this tutorial:

Write an Avatar Scaling Script

To define the behavior of your avatar and the button, you need to write a client entity script that:

  • attaches to an entity (a button in your domain).
  • shrinks or increases the size of an avatar.
  • defines what happens when a user clicks on or triggers the entity.

In this tutorial, we’ve used shrink-avatar.js, an avatar scaling script used to shrink an avatar down to a tiny size. You can use this script, modify it, or write your own to suit your needs.

The shrink-avatar.js uses 8 agora’s JavaScript API to determine when a user clicks with the mouse or triggers the entity with their hand controllers. It then scales the avatar to one-tenth its original size.

Create an Entity to Use as a Button

The entity you create for your button has to be triggerable so that the script can detect when you trigger or push the button with your hand controllers.

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Create an entity to be used as a button. This can be a 3D model, cube, or sphere entity.
  3. Go to the ‘Properties’ tab and scroll down to ‘Behavior’.
  4. Next to ‘Script’, paste the script URL. In this case, it is ‘shrink-avatar.js’.
  5. Ensure that ‘Triggerable’ is selected.
  6. After you exit the Create app, test your script by clicking or triggering the button to observe your avatar scale down.

_images/shrink-avatar.gif

See Also

Tutorial: Open Web Page with Entities

Entities are often used to add objects to your environment. However, you can do so much more with this when you use scripting to define their behavior. In this tutorial, we will use an entity as a button to open a web page on your tablet.

On This Page:

Prerequisites

Consider getting familiar with the following concepts before starting this tutorial:

Write a Script to Open a Web Page

The script used here opens a web page on the Tablet when a user clicks or triggers an entity.

You can get the script here.

Create an Entity to Use as a Button

The entity you create for your button has to be triggerable so that the script can detect when you trigger or push the button with your hand controllers.

  1. In Interface, pull up your HUD or Tablet and go to Create.

  2. Create an entity to be used as a button. This can be a 3D model, cube, or sphere entity.

  3. Go to the ‘Properties’ tab and scroll down to ‘Behavior’.

  4. Paste the following JSON data into the ‘User data’ field for your entity:

    {
  "url": "your_marketplace_url_in_quotes_here",
  "grabbableKey": {
    "grabbable": false,
    "triggerable": true
  }
}

  5. Next to ‘Script’, paste the script URL. In this case, it is openTabletPageButton.js.

  6. Scroll down and ensure that ‘Triggerable’ is selected.

_images/open-page.gif

See Also

Tutorial: Build a Painting Set

There are different ways to create games and experiences in 8 agora. In this tutorial, we’ll cover how to make a pixel-like painting set to allow users to “paint” pictures on a canvas made out of “pixels” that are box entities.

On This Page:

Prerequisites

Consider getting familiar with the following concepts before starting this tutorial:

Create a Painting Set

Our painting set comprises three elements:

All of the logic for our painting set is contained in the brush head. The rest of the content is made by parenting entities to one another to make our brush, palette, and canvas.

Create a Paint Brush

We’ll start by creating the paint brush. The brush is comprised of two parts, the handle and the brush head. The brush handle is the parent of the brush head, so we can control the movement and color of the brush head using only the handle.

To create the brush handle:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Create an entity to be used as the handle. This can be a box or sphere entity.
  3. Go to the ‘Properties’ tab and select the ‘Shape’ drop down. Change the shape of the entity to a ‘cylinder’.
  4. Name your entity ‘Paint-Paintbrush-Tube’ by selecting the text box at the top of the ‘Properties’ tab.
  5. Select your desired handle color from the ‘Color’ picker.
  6. Scroll down to the ‘Spatial’ section. Change the local dimensions to: {x: 0.025, y: 0.5, z: 0.025}.

To create the brush head:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Click on the ‘SPHERE’ icon to create a sphere entity to be used as the brush head.
  3. Go to the ‘Properties’ tab and select your desired brush head color from the ‘Color’ picker.
  4. Name your entity ‘Paint-Paintbrush-Head’ by selecting the text box at the top of the ‘Properties’ tab.
  5. Scroll down to the ‘Spatial’ section. Change the local dimensions to {x: 0.05, y: 0.1, z: 0.05}.

Once you’ve created the brush head, you can parent the brush handle to it:

  1. In Create Tools app, select your brush handle and go to the ‘Properties’ tab.
  2. Copy the ‘entityID’.
  3. From the Entity List window, select the brush head and go to the ‘Properties’ tab.
  4. In the ‘Parent’ text box, paste the entityID of the brush handle (Paintbrush-Tube) entity.
  5. Scroll down to the ‘Spatial’ section. Change the local position to {x: 0, y: 0.2, z: 0}.

We’ve detailed how you can add a script to use the brush to transfer color to other objects in Add a Paint Brush Script.

Create a Paint Palette

The second part of our painting set is the palette. This is where you can get creative, and add as many (or as few) paint colors as you’d like. Once you have the base of the palette created, you can repeat the process of adding paints until you are satisfied with the end result.

To create the palette base:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Create an entity to be used as the palette base. This can be a box or sphere entity.
  3. Go to the ‘Properties’ tab and select the ‘Shape’ drop down. Change the shape to an ‘octagon’.
  4. Name your entity ‘Paint-Palette-Base’ by selecting the text box at the top of the ‘Properties’ tab.
  5. Select your desired palette color from the ‘Color’ picker.
  6. Scroll down to the ‘Spatial’ section. Change the local dimensions to {x: 0.55, y: 0.5, z: 0.55}.
  7. Scroll down to the ‘Behavior’ section. Check ‘Grabbable’.

To create the paint colors:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Create a sphere entity to be used as your first paint color.
  3. Go to the ‘Properties’ tab and name your entity ‘Paint-Color’ by selecting the text box at the top of the tab.
  4. Select your desired paint color from the ‘Color’ picker.
  5. Scroll down to the ‘Spatial’ section. Change the local dimensions to {x: 0.1, y: 0.05, z: 0.1}
  6. In the Create Tools app, select your palette base and go to the ‘Properties’ tab.
  7. Copy the ‘entityID’.
  8. Select your paint color and go to the ‘Properties’ tab.
  9. In the ‘Parent’ text box, paste the palette base entityID.
  10. Use the grab handles to adjust the position and size of the paint on the palette.
  11. Scroll down to the ‘Behavior’ section and uncheck ‘Grabbable’.

Repeat the above steps to create additional paint colors for your palette.

Create a “Pixel” Canvas

The last component that makes up our painting set is the canvas we’ll use for our “pixel” style painting. We’ve provided a JSON file for you to import a canvas so you don’t need to go through each step individually, but you can import the grid multiple times to make a larger painting space, if desired.

  1. In Interface, go to Menu > Edit and select ‘Import Entities from URL’.
  2. Paste this URL into the dialog window and select ‘OK’.

The canvas is made up of box entities parented to a single backplate, but you could use any entities to create a scene that could be painted this way.

Add a Paint Brush Script

To start painting on the canvas, you have to write a paint brush script that serves as our ‘painting’ logic. This script will:

  • Check if the paint brush head has collided with another entity.
  • Check if this entity is a paint color, and change the color of the brush head.
  • Check if the entity is a different entity. If it is not a paint color, the script will “transfer” it’s color over to the other entity.

To add the paint brush script:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Select the Paint-Brush-Head entity.
  3. Go to the ‘Properties’ tab and scroll down to ‘Behavior’.
  4. Next to ‘Script’, paste the script URL. In this case, it is ‘brushScript.js’.
  5. After you close the Create app, test it out by painting on the canvas in your domain!

See Also

Prerequisites

Consider getting familiar with the following concepts before starting this tutorial:

See Also

Tutorial: Create a Boombox

You can create a music player that plays all your favorite tracks and also syncs the audio for other users in your domain.

On This Page

Create a Boombox Entity

Your BoomBox will consist of:

  • A boombox base model: A model entity that runs an entity server script.
  • An ‘ON/OFF’ button: A child entity runs a client entity script to allow users to interact with the boombox.

The boombox will start playing when users click or trigger the ON/OFF button.

To create a boombox:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Use the Create app to import the 3D model entity. You can create your own 3D model for the boombox base or use one we’ve created.
  3. Next, create the button entity that users will interact with. This can be a cube entity.
  4. Go to ‘Properties’ tab for the button entity. Change the ‘Shape’ property from ‘Box’ to ‘Octagon’ or ‘Cylinder’ depending on your aesthetic preferences.
  5. Scroll down to the ‘Behavior’ section and ensure that ‘Grabbable’ and ‘Triggerable’ are checked.
  6. Scale, rotate, and move your button to align it to the desired position on the model.
_images/boombox.png
  1. With the Create app open, select the 3D model of the boombox. Go to the ‘Properties’ tab and copy the ‘ID’ under ‘Name’.
  2. Select the cube entity you created, go to the ‘Properties’ tab, and paste the copied entity ID in the ‘Parent’ field. This makes your boombox model entity the parent of your button entity.
Add User Data to Your Boombox

The User Data property is a JSON object that can be customized to fit the needs of a script. User Data also helps in synchronizing and keeping variables the same for all users in a domain. In this case, User Data will contain:

  • Song List: All URLs of the songs you want played on your boombox. You can also use MP3 or WAV files stored on your local machine.
  • Music player volume information: You can change this as per your preference.

Note

User Data can store information only up to a certain size. We recommend keeping the limit of 10 songs. We support the following formats:

  • WAV: 16-bit uncompressed WAV at any sample rate, with 1 (mono), 2(stereo), or 4 (ambisonic) channels.
  • MP3: Mono or stereo, at any sample rate.
  • RAW: 48khz 16-bit mono or stereo. Filename must include “.stereo” to be interpreted as stereo.

To add User Data to your boombox:

  1. In Interface, pull up your HUD or Tablet and go to Create.

  2. Select your boombox entity, not the button.

  3. Go to the ‘Properties’ tab. Scroll down to ‘User Data’ and paste the following JSON information. This JSON data consists of 10 songs and the volume setting. You can use your own songs and change the volume setting:

    {
  "grabbableKey": {
    "grabbable": false
  },
  "music": {
    "All That": "https://hifi-content.s3-us-west-1.amazonaws.com/liv/dev/BoomBox/music/bensound-allthat.mp3",
    "Country Boy": "https://hifi-content.s3-us-west-1.amazonaws.com/liv/dev/BoomBox/music/bensound-countryboy.mp3",
    "Cute": "https://hifi-content.s3-us-west-1.amazonaws.com/liv/dev/BoomBox/music/bensound-cute.mp3",
    "Happiness": "https://hifi-content.s3-us-west-1.amazonaws.com/liv/dev/BoomBox/music/bensound-happiness.mp3",
    "Happy Rock": "https://hifi-content.s3-us-west-1.amazonaws.com/liv/dev/BoomBox/music/bensound-happyrock.mp3",
    "High Octane": "https://hifi-content.s3-us-west-1.amazonaws.com/liv/dev/BoomBox/music/bensound-highoctane.mp3",
    "Hip Jazz": "https://hifi-content.s3-us-west-1.amazonaws.com/liv/dev/BoomBox/music/bensound-hipjazz.mp3",
    "Pop Dance": "https://hifi-content.s3-us-west-1.amazonaws.com/liv/dev/BoomBox/music/bensound-popdance.mp3",
    "Sci-Fi": "https://hifi-content.s3-us-west-1.amazonaws.com/liv/dev/BoomBox/music/bensound-scifi.mp3",
    "Sample": "sample.com"
  },
  "volume": 0.7
}
Write Music Player Scripts

The boombox system contains the following scripts and files that allows a user to control audio playback:

File Description URL
Entity Server Script This server script handles the state of the music player and plays audio back so that it is synchronized across all users. Actions and behaviors of entities that need to be in the same state for all users, should run on the server. The client script that runs on the button relays the requests for each remotely callable function to execute on the server, and the server script handles the audio playback accordingly. boomBoxEntityServerScript.js
Client Entity Script This client script handles the interactions between users and displays the UI for controlling the boombox via an HTML page using the Tablet Scripting Interface. It listens for mouse clicks and controller triggers, displays the controls, and serves as a relay mechanic between the HTML page and the boombox entity server script. boomBoxEntityScript.js
HTML and CSS The HTML page displays the controller UI for the boombox through the Tablet Scripting Interface and is styled with CSS. It uses the EventBridge to send the user input from the HTML elements to the boombox entity script, which in turns calls entity server methods depending on the EventBridge message contents.

boomBoxController.html

styles.css

You can use the existing versions of our scripts, modify them, or write your own scripts.

If you’re using the existing versions of our scripts:

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Select your boombox model and go to the ‘Properties’ tab.
  3. Scroll down to the ‘Behavior’ section and paste the entity server script’s URL into the ‘Server Script’ field.
  4. Select your button entity and go to the ‘Properties’ tab.
  5. Scroll down to the ‘Behavior’ section and paste the client entity script’s URL into the ‘Script’ field.

If you’re writing your own scripts or modifying the existing ones, and want to host these in the ‘Asset Browser’:

  1. On your computer, create a folder called ‘BoomBox’. You’ll save your files here with the following structure.
_images/boombox-folder.png
  1. Save the entity server script, client entity script, HTML file, and CSS file to the folder in your computer.
  2. In Interface, pull up your HUD or Tablet and go to Create.
  3. In the Create app, click ‘Open This Domain’s Asset Server’ to view the Asset Browser.
  4. Create the same boombox directory in your ‘Asset Browser’ and upload your files.
  5. Use the Create app and select your boombox model and go to the ‘Properties’ tab.
  6. Scroll down to the ‘Behavior’ section and paste the entity server script’s URL into the ‘Server Script’ field.
  7. Use the Create app and select your button entity and go to the ‘Properties’ tab.
  8. Scroll down to the ‘Behavior’ section and paste the client entity script’s URL into the ‘Script’ field.

Note

Some additional notes:

  • The scripts linked above use relative paths to link to one another, so it’s important to preserve the folder structure given. If you want to move things around, make sure you also update the links in the scripts themselves to reference the new file location.
  • If you want to make modifications to your script files, you will need to re-upload them to the asset browser. Reload all content and reload your entity server scripts to see changes take effect after modifying files.
  • Entity server scripts do not have access to mouse press or controller events, since these are all handled on the client side.
  • HTML pages will not render in the Oculus Quest, so only desktop users will be able to interact with the boombox controls.

See Also

3D Models

3D models are entities that represent objects you’d like to see in-world such as a water fountain, a castle, or a coffee mug. You can get your 3D model by creating your own, sourcing it externally. We only support 3D models in the OBJ and FBX formats.

The appearance of a 3D model is controlled by its materials. The materials supported in 8 agora are Physically-based Rendering (PBR) materials. This means that a 3D model’s materials will reflect or absorb light as they would (approximately) in real life.

In This Section:

Get Your 3D Model

On This Page

Get Your 3D Model from 3D Content Stores

There are many online 3D content websites that contain models that you can purchase or get for free. Keep the following in mind when sourcing 3D models from such sites:

  • Check Licensing Terms: Make sure you check a model’s licensing terms before you use it. It is your responsibility to ensure that you have sufficient rights to upload the content. When you make a 3D model available on your 8 agora server, visitors are getting the links to those files in the same way as they would when viewing an image on a website.
  • Check Materials: You might find that the model may be missing its textures. If that happens, first check to see if the textures are included. If a model loads into 8 agora and doesn’t look right, you may also find error information in the Interface logs.
Create Your Own 3D Model

You can create your own 3D model using 3D modeling software such as Blender or Maya. Use any software of your choice as long as:

  • The 3D model is in the OBJ, GLTF & BIN, GLB or FBX format.
  • The 3D model materials are supported by 8 agora. Use our materials guide to make sure that your materials load correctly.
Best Practices

Making 3D models for 8 agora (and VR) is different than making models for films, videos, and games.

  • 3D models for VR are rendered twice (for both right and left eyes): This means that the number of polygons on your model and the number of materials you use will affect your performance.
  • All VR headsets run at 90Hz: You’ll have to keep your framerate at 90fps and be cautious about your model’s size. Models that are too big or very complex can slow down the framerate and make people feel nauseous.

We’ve listed the best practices for creating 3D models for 8 agora (and VR).

Property Best Practice
Polycount Your count should resemble that of a model for a tablet game, not too high, but not too low either.
Edge Loops Remove edge loops that are not needed.
Mesh Clean the mesh to make sure there are no N-gons and no coplanar faces.
Materials Always try to create Atlas maps. When every piece of your content shares the same material and UV space, it is an Atlas map. For example, if you create a robot, all its pieces should share one UV map, instead of giving its hands, feet, or face separate materials and UV maps.
Materials 8 agora’s engine only supports one UV mapping per material.
Textures PNG, JPEG and JPG files are recommended, but we also support TGA, TIF and TIFF formats.
Textures Choose the color types wisely to minimize the size of the final file.
Textures PNG-8 has only ON/OFF transparency, has a palette of colors (256 colors, like GIF), and can be used to mask transparency.
Textures For more color resolution, you can use PNG-24. For translucent mask or transparent textures, use PNG-32.
Textures Do not use PNG-48 or PNG-64, as neither are supported by 8 agora.
Textures When loaded in the engine, textures are automatically resized to a grid of 128x128. Pick sizes which are multiples of 128.
Draw Calls

Draw calls happen before something gets rendered on screen.

1 model w/ 1 material = 1 draw call

There are no definitive measures for a desirable polycount. You need to balance between draw calls and polys. Fewer draw calls means more room for polys. Smaller textures means more room for higher poly models.
Import a 3D Model

You can import a 3D model into 8 agora that is hosted online or on your domain’s Asset Server. Importing your model rezzes it into your domain and adds it to your virtual world.

On This Page

Import Models from the Cloud

If you want your model available to users in other domains, we recommend uploading it to a cloud hosting service of your choice.

  1. Locate and copy the URL of the model you would like to import. The model should be a OBJ or FBX format.
  2. In Interface, pull up your HUD or Tablet and go to Create.
  3. Select the ‘Model’ icon.
  4. Paste the model’s URL and click ‘Add’.
_images/import-model.png
Import Models from the Asset Server

The Asset Server hosts files or assets that can either be added as-is to a domain or that are referenced by existing entities and scripts already in a domain. To import assets from the Asset Server, you must have permissions to rez entities in the domain that the Asset Server is running on.

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Click ‘Open this Domain’s Asset Server’.
  3. In the Asset Browser, browse to the model you would like to import.
  4. Click ‘Add to World’. Then click ‘Add’ on the confirmation window that opens.

See Also

PBR Materials Guide

The appearance of a 3D model is controlled by its materials. The materials supported in 8 agora are physically-based rendering (PBR) materials. This means that a 3D model’s materials will reflect or absorb light like how they would (approximately) in real life.

On This Page

Introduction to Materials, Textures, and Shading

A 3D model’s appearance is controlled by its materials. For example, a 3D model of a key will use a material that determines its color, how metallic it looks, and if its surface is bumpy or smooth. A 3D model of a brick wall will have material that determines its roughness and color.

8 agora supports physically-based rendering (PBR) materials. This means that your model will behave like a real world object when exposed to light. For example, the same 3D model of a key will shine and reflect any light that falls on it. The 3D model of a brick wall will not shine, but will reflect enough light for you to observe its colors and surface.

A material contains texture and shading information.

Textures

Textures are flat images that are applied to 3D models. These add detail on how a 3D model’s material looks. For example, a 3D model of a tree trunk will use a texture of bark to show what the surface looks like.

8 agora supports the use of the following texture formats:

  • PNG (recommended)
  • JPEG, JPG (recommended)
  • TGA
  • TIFF, TIF

For best performance, we recommend baking all 3D models (including textures) before uploading it to 8 agora.

Shading

Since 8 agora supports PBR materials, the shading used depicts an accurate representation of a how light interacts with different material surfaces. This means that your 3D model will not look the same under different light settings. The PBR shader has a set of material parameters or channels that can be modified to create different types of materials.

Note

You can combine shaders with material entities on shape and zone entities to apply shaders to models and avatars. This feature was released as an experimental feature and has not been thoroughly tested through our normal channels. If you wish to try applying procedural materials to models or avatars at your own risk, then you can find more information at Procedural Shaders for Models and Avatars.

Material Channels

Material channels determine various parameters such as the roughness or color of a material. You can determine the value of each channel in two ways:

  • Setting a Value: The value of a channel is a value set on a slider. Setting a value is like turning off or turning on a switch. For example, if you look at your phone, some parts of it are shiny and some are matte. When you use a value, the entire object reflects that value. If you want different parts of an object to reflect varied roughness, you’ll need to use a map.
  • Using a Map: The map is an image which you can import to define a property. You will use a map to apply a texture to your 3D model. For instance, your phone may have a case that is matte, but the rest of your phone is shiny. You can use a map to set the case as matte and the phone as shiny.

All materials in 8 agora have the following channels that determine how they look:

Channel Type Description Value Map
Albedo This channel defines the material’s color. You can pick any color value of your choice. sRGB sRGB
Metallic This channel determines if the material is metallic or not. You cannot have a material that is half metallic, it is either metallic or it isn’t. [0,1] [0,1]
Roughness This determines how rough/matte or glossy/shiny an object is, using brightness levels. [0,1] [0,1]
Normal Normal is a channel that renders an object like there is actual geometry. For instance, normal would add bumps and other irregularities to a stone or ridges to a sea-shell. xyz bump
Opacity Opacity determines if an object is transparent or opaque. [0,1] mask, alpha
Occlusion This property approximates the shading to be as natural as possible. This means that it will reproduce how objects interact with light. — [0,1]
Emissive This channel controls the amount of light being reflected from an object. sRGB sRGB
Scattering Scattering determines how light will behave when it hits human skin. This channel details how light is reflected or absorbed by human bodies. [0,1] [0,1]
Material Type This channel decides if an object is lit or unlit. [lit, unlit] —

Notes:

  1. If you set transparency with a texture, the transparency (alpha) should be in the material’s albedo texture, as a PNG file with transparency and not as a separate transparency texture.
  2. 8 agora’s renderer can draw two different kinds of transparency: “alpha” (255 graduates steps of transparency, no shading on surface, casts no shadows,) and “mask” (binary transparency, full shading of opaque surface, whole surface casts shadow.)
  3. To determine whether a texture is treated as a mask or as alpha, the engine looks for alpha values between 2% and 98%. An easy way to create a mask texture is to save your image as a PNG-8 since it only supports binary transparency, while PNG-24 supports a range of transparency levels.
  4. We support using a second UV set with the following texture channels only: Light Map and Ambient Occlusion.
Sample Materials and Their Textures and Shading

8 agora supports different types of materials. We’ve created sample objects with each material type. You can download each object from this repository on GitHub, or run this script in 8 agora to upload all sample objects in your domain.

We’ve listed all material information (including textures, shading, and channel values and maps) for these sample objects here.

Set Material Values in Blender

When you create a model in Blender, you have to export it in the FBX format to use in 8 agora. Additionally, you have to modify material properties and textures in Blender to match the PBR material textures in 8 agora.

Doing so ensures that your model appears like how you want it to.

By default, any material property set with a texture will override a property set with a value. The only exception to this is in the case of the albedo color set with an RGB color value and a texture, in which case the albedo value and texture will multiplied together.

We’ve included images where the fields corresponding to each supported PBR channel in Blender are highlighted, along with details about which values and colors correspond to the range corresponding with that channel. It should be noted that all of the Blender material properties below only relate to exported FBX format models. Models exported as OBJ or other formats do not have full PBR material support in 8 agora yet.

_images/material-textures-b.jpg _images/material-values-b.jpg
Set Material Values in Maya

Use the graphics below to set the right material values and textures in Maya.

_images/material-values-m.jpg _images/material-textures-m.jpg

See Also

Import Animations

Enrich your 8 agora experience by having 3D models in your domain with animations. For example, you can import the 3D model of a flag that appears to flutter with the wind using this feature.

On This Page

Prerequisites

You need to be familiar with creating animations in 3D modeling tools such as Blender and Maya before importing an animation into 8 agora.

Prepare a 3D Model Animation

Before you import an animation into 8 agora, adjust some settings in the 3D modeling tool of your choice to ensure that it plays smoothly.

  1. Set the framerate to 30 fps for the best results (our recommendation).
  2. Bake your animation channels, key frames, and inbetweens to ensure that 8 agora reads everything. This is to ensure that your animation doesn’t stop and start, but appears smooth and flows through each movement.
  3. Prepare to export the skeleton and frames that are being used in the animation.
  4. Export your animation as an FBX file.
  5. Upload this FBX file to a cloud server. Copy the URL.
Import an Animation

Once you complete uploading your animation’s FBX file, you can import the 3D model and it’s animation into 8 agora.

  1. In Interface, pull up your HUD or Tablet and go to Create.
  2. Click on the ‘MODEL’ icon and enter your 3D model’s URL. If you have saved your 3D model’s FBX file with the animation, the model’s URL and the animation’s URL will be the same. Otherwise, your animation is saved as a separate FBX file.
  3. In the ‘Properties’ tab, scroll down to ‘Animation’ and paste the animation’s URL.
_images/animation-prop.png

  1. You can edit the following animation properties:

    Property Description
    Play Automatically Enable this to play your animation automatically when a user loads a domain.
    Loop Select this property to play your animation in a continuous loop.
    Allow Transition Enable this to let the animation move through space. This means that the joints will not only rotate, but translate through three dimensions.
    Hold Select to pause your animation at a particular frame.
    Animation Frame Enter the frame at which you want to pause or hold your animation.
    First Frame This is the first frame from when your want your animation to start.
    Last Frame This is the last frame where you want your animation to stop. It will not play beyond this specified frame.
    Animation FPS This is the animation’s framerate.

  2. You can also control an animation’s properties and when it starts playing with an entity script.

See Also

Environments

A 8 agora domain can have an environment to express a theme. Environments include all the domain content, such as entities, skyboxes, assets, and more. You could have a domain with a deserted island environment or a cyberpunk apartment environment.

Create an Environment

An environment consists different types of 3D models and a skybox following the theme of your choice. You can create an environment using:

Method Description
3D Models Available You can purchase or get 3D models from online 3D content websites. Then, you can import these models using the Asset Server.
Your 3D Models You can use 3D modeling software like Blender or Maya to create your own 3D models and import them into your 8 agora domain.
A Content Archive File 8 agora domain settings have downloadable content archives. These archives are zip files containing all domain content information. You can use a backup file of your own or one sent to you by a user.

See Also

Tablet Apps

Tablet apps (or simply “apps”) in 8 agora are customizable programs that expose functionality in an easy-to-use user interface. Apps let you take complex code from our JavaScript API and simplify it into a window with controls for others to use.

Note

To create custom apps, you must have a basic knowledge of web development (HTML, CSS and JavaScript) and be able to navigate our API.

The steps involved in creating a tablet app are:

  1. Create icons to show up on the tablet and HUD

  2. Design your app’s UI in HTML and CSS

  3. Add event handlers to your HTML file

  4. Write a JavaScript file that:

    • Adds a button to the tablet and HUD
    • Loads your app
    • Closes your app
    • Listens for events
    • Runs your code (in this case, create some gemstones)
Tutorial: Create Gemstone Switching Tablet App

In this tutorial, we will walk through the above steps to create an app called “Gemstone Magic Maker”. This simple app lets you spawn colorful little gemstones in VR that you can share with your friends.

Create icons to show up on the tablet and HUD

You need two icons to show up on the tablet and HUD: an SVG or PNG image to display on the app button when the app is active, usually named <appName>-a.svg and another to display when the app is inactive, usually named <appName>-i.svg.

_images/app-icons.png

We recommend the following specs for your icons:

  • Size: 50px by 50px
  • Color: White on a transparent background (for inactive icons) and black on a transparent background (for active icons)
  • File format: SVG or PNG

You can create your own icon using graphic design software or any other online resources.

Design your app’s UI in HTML and CSS

Your app’s UI should provide text on how the app works and use familiar UI elements that a user knows how to interact with (such as buttons, scroll bars, and links). Keep in mind that the tablet screen dimensions are 480 x 720, so all of your UI should be confined to this space.

To help you get started, we’ve put together a quick start HTML template that you can reuse. It contains the same layout, styling and font as the main menu screen, and has a header bar for your app title. With just a few simple modifications, you can create have a simple app UI within minutes.

_images/app-ui.png
Add event handlers to your HTML file

The Tablet UI framework provides a communication channel called EventBridge. It allows you to send and receive events between the client script (gemstoneApp.js) and JavaScript in your web app (gemstoneMagicMaker.html). Use the following EventBridge code inside of <script> </script> tags in the body of your HTML file to handle the button clicks:

function main() {
    // Send an event to gemstoneApp.js when the page loads
    // and is ready to get things rolling
    console.log("document ready");
    var readyEvent = {
        "type": "ready",
    };

    // The event bridge handles events represented as a string the best.
    // So we first create a JavaScript object, then convert to string
    EventBridge.emitWebEvent(JSON.stringify(readyEvent));

    // Send an event when user click on each of the gemstone buttons
    $(".gemstone-button").click(function(){
        console.log(this.value + " button click");
        var clickEvent = {
            "type": "click",
            "data": this.value
        };
        EventBridge.emitWebEvent(JSON.stringify(clickEvent));
    });
}
$(document).ready(main);
Write a JavaScript file

Your JavaScript file will contain all of the core functionality of your app. At a minimum, we require that you have code that adds a button to the tablet and HUD, loads your app, closes your app gracefully, and listens for events. Below, you will find code samples to do each of these things.

Add buttons to the tablet and HUD

Use the AppUI module to automatically add your app’s button to the tablet and HUD, and to wire button click handlers:

(function () { // BEGIN LOCAL_SCOPE
var AppUi = Script.require('appUi');

var ui;
function startup() {
    ui = new AppUi({
        buttonName: "APP-NAME", // The name of your app
        home: Script.resolvePath("app.html"), // The path to your app's UI
        graphicsDirectory: Script.resolvePath("./") // The path to your button icons
    });
}
startup();
}()); // END LOCAL_SCOPE

Determine the app’s startup behavior

If you want your app to do something specific when it is opened, use the AppUI module’s onOpened functionality. For example, you could:

  • Query a server to get a response and determine what to show on the UI
  • Start displaying a 3D interface separate from the tablet
  • Determine the display mode (VR/Desktop) and change things to show on the UI
(function () { // BEGIN LOCAL_SCOPE
var AppUi = Script.require('appUi');

function onOpened() {
    console.log("hello world!");
}

var ui;
function startup() {
    ui = new AppUi({
        buttonName: "APP-NAME", // The name of your app
        home: Script.resolvePath("app.html"), // The home screen of your app that appears when clicking the app button
        graphicsDirectory: Script.resolvePath("./"), // Where your button icons are located
        onOpened: onOpened // See the simple function above
    });
}
startup();
}()); // END LOCAL_SCOPE

Close the app gracefully

The AppUI module ensures that your app closes gracefully. However, if you want to do something else when you close the app, you can with the onClosed functionality built into the AppUI module. For example, you could:

  • Remove 3D interfaces
  • Stop secondary scripts
(function () { // BEGIN LOCAL_SCOPE
var AppUi = Script.require('appUi');

function onOpened() {
    console.log("hello world!");
}

function onClosed() {
    console.log("hello world!");
}

var ui;
function startup() {
    ui = new AppUi({
        buttonName: "APP-NAME", // The name of your app
        home: Script.resolvePath("app.html"), // The home screen of your app that appears when clicking the app button
        graphicsDirectory: Script.resolvePath("./"), // Where your button icons are located
        onOpened: onOpened // See the simple function above
        onClosed: onClosed // See the simple function above
    });
}
startup();
}()); // END LOCAL_SCOPE

Listen for events

In step 3 above, we added event handlers to your HTML file. Now, you need to add code to your JavaScript file to listen for the events:

function onWebEventReceived(event) {
   print("gemstoneApp.js received a web event: " + event);
}
tablet.webEventReceived.connect(onWebEventReceived);
Create gemstones

The final step is to code the behavior of your JavaScript file. In this case, we’ll create gemstones using 8 agora’s JavaScript API. Each gemstone will be created as an entity, and we can change the gemstone’s properties using the Entity namespace.

Calculate the position of each new gemstone

The following code gives us a position right in front of the user:

// Helper function that gives us a position right in front of the user
function getPositionToCreateEntity() {
  var direction = Quat.getFront(MyAvatar.orientation);
  var distance = 0.3;
  var position = Vec3.sum(MyAvatar.position, Vec3.multiply(direction, distance));
  position.y += 0.5;
  return position;
}

Set the gemstone’s properties and add it

The gemstone will be created when gemstoneApp.js receives click events from each of the buttons:

// Handle the events we're receiving from the web UI
function onWebEventReceived(event) {
    print("gemstoneApp.js received a web event:" + event);

    // Converts the event to a JavasScript Object
    if (typeof event === "string") {
        event = JSON.parse(event);
    }

    if (event.type === "click") {
        // Define the entity properties of for each of the gemstone, then add it to the scene
        var properties = {
            "type": "Shape",
            "position": getPositionToCreateEntity(),
            "userData": "{\"grabbableKey\":{\"grabbable\":true}}"
        };
        if (event.data  === "Emerald") {
            properties.name = "Emerald";
            properties.shape = "Dodecahedron";
            properties.color = {
                "blue": 122,
                "green": 179,
                "red": 16
            };
            properties.dimensions = {
                "x": 0.20000000298023224,
                "y": 0.26258927583694458,
                "z": 0.20000000298023224
            };
            Entities.addEntity(properties);
        } else if (event.data  === "Ruby") {
            properties.name = "Ruby";
            properties.shape = "Octagon";
            properties.color = {
                "blue": 160,
                "green": 52,
                "red": 237
            };
            properties.dimensions = {
                "x": 0.20000000298023224,
                "y": 0.24431547522544861,
                "z": 0.12547987699508667
            };
            Entities.addEntity(properties);
        } else if (event.data  === "Sapphire") {
            properties.name = "Sapphire";
            properties.shape = "Icosahedron";
            properties.color = {
                "blue": 255,
                "green": 115,
                "red": 102
            };
            properties.dimensions = {
                "x": 0.160745769739151,
                "y": 0.20000000298023224,
                "z": 0.23340839147567749
            };
            Entities.addEntity(properties);
        } else if (event.data  === "Quartz") {
            properties.name = "Quartz";
            properties.shape = "Octahedron";
            properties.color = {
                "blue": 245,
                "green": 142,
                "red": 216
            };
            properties.dimensions = {
                "x": 0.20000000298023224,
                "y": 0.339866042137146,
                "z": 0.20000000298023224
            };
            Entities.addEntity(properties);
        }
    }
}

Congratulations, you have successfully created an app in 8 agora! To use your app, upload it to a cloud platform, such as Amazon S3, Google Cloud Storage, Microsoft Azure, etc. Once hosted, you can install it and use it:

  1. In Interface, go to Edit > Running Scripts.
  2. Under Load Scripts, click ‘From URL’ and enter the URL to your hosted JavaScript file.
  3. Click the app icon on the tablet or HUD to open the app.

See Also

Script

8 agora uses scripts (written in JavaScript) for a number of different things: creating content, moving your avatar, playing audio at a specific location, wearing an avatar attachment, and much more.

Throughout this chapter, learn about the different types of scripts and how you can use them to create new experiences:

Get Started with Scripting

Many of the scripts in 8 agora run behind the scenes, so that you don’t even know they’re running. However, if you want to create some advanced behavior, you may need to write your own scripts to make sure everything works correctly.

This page ensures that you know what type of script to use and helps you get started running your own simple scripts.

On This Page

JavaScript Basics in 8 agora

8 agora scripting runs on a JavaScript engine that is provided with Qt.

Note

Note that any functionality that runs around web pages (such as cookies, local storages, or databases) does not work with 3D environments such as 8 agora. For this reason, you cannot use JavaScript frameworks such as Angular, React, Express, jQuery, Vue, etc.

You are likely to interface most with these 8 agora APIs:

API(s) Description
Entities Lets you manipulate the entities around you, as long as you have permissions to do so. This means you can add, remove, and edit entities. Everyone has access to get properties of an entity, and can be used to find Entities in range, direction, collision, or raytrace.

AvatarList

AvatarManager

MyAvatar

 Lets you get information on an Avatar, or manipulate your own client-only MyAvatar. The information here will be always the avatar information of the client running the script. AvatarList and AvatarManager are basically the same.
Script Lets you to connect callbacks from your client to script, such as functionality that is dependent on time (Script.update, Script.setTime, Script.setInterval etc), connect paths relatively to Assets (Script.relativePath), refer to other scripts (Script.include), or create events which occur when the script is turned off (Script.scriptEnding).

There are many other APIs available, and we encourage you to make sure use of them as you become more comfortable scripting in 8 agora.

Types of Scripts
Script Type Description
Interface Script Interface scripts run as long as you have Interface running. With these scripts, you can perform one-time creation tasks or modify the user experience with new menus, overlays, tweaks, plugins, and extensions.
Assignment Client Script Assignment client scripts coordinate the actions between entities and avatars in your domain. These scripts continue to run even when you shut down Interface.
Avatar Script Avatar scripts run on an avatar and can give it unique effects, such as flowing hair.
Client Entity Script Client entity scripts are scripts attached to entities that run locally in response to a user in a domain. With these scripts, you can customize what happens when a user encounters an entity.
Server Entity Script Server entity scripts are scripts attached to entities that do not require a user to trigger. These scripts control entities so that their behavior is seen and heard by everyone in the domain.
Scripting Permissions

Each domain owner has the ability to restrict create and edit permissions. If the script you want to run adds or edits entities and you don’t have the permission to do so, you won’t see any objects created or changed. However, you will still see the script listed in the Running Scripts window.

Running Scripts Window

The Running Scripts window can be used to load, run and stop scripts from a URL or from a disk drive. 8 agora also provides a number of sample scripts for you to try out.

To open the Running Scripts window, go to Edit > Running Scripts or press Ctrl + J on your keyboard.

Sample Scripts

8 agora comes with a collection of scripts designed to improve your experience as a user and provide tools for developing your own content. We encourage you to look at these scripts as a resource to learn how to code your own.

Note

Loading (or running) a script lets you test the functionality and see how it behaves. If you want to view the actual code, you will need to open the file in the text editor of your choice. In the ‘Running Scripts’ window, click the ‘Reveal Scripts’ folder and browse to the JavaScript file that you want to view.

These are the scripts we have available:

Scripts Folder Description
android These scripts were built to run on Android devices.
developer These scripts were created for internal use and debugging, but are available as advanced developers may find them useful when creating content. These scripts are not “entry-level” and are not guaranteed to work or be documented.
modules These scripts create external tools that simplify scripting in 8 agora. For example, the AppUI module helps you create a tablet app, while the Request module processes HTTP requests.
system These scripts are critical to the stability and usability of 8 agora. Making changes to these scripts is not recommended, nor is it easy, as you may need ‘administrative’ privileges.
tutorials These scripts provide examples of what you can do using scripts in 8 agora. Examples include: creating butterflies, making your avatar clap, and adding ambient sound to your domain.
Load and Run a Script

To run a script:

  1. Open the ‘Running Scripts’ window.
  2. For scripts hosted in the cloud, click ‘From URL’. Enter the URL of your script file and click ‘OK’.
  3. For scripts on your local computer, click ‘From Disk’. Browse to your script file and click ‘Open’.
  4. To load a sample script, browse to the script at the bottom of the ‘Running Scripts’ window.
Reload or Stop a Script

To reload or stop a script, open the ‘Running Scripts’ window and do one of the following:

  • To reload all running scripts, click the ‘Reload All’ button at the top of the ‘Running Scripts’ window.
  • To reload a specific script, click the circular arrow next to the script.
  • To stop all running scripts, click the ‘Stop All’ button at the top of the ‘Running Scripts’ window.
  • To stop a specific script, click the ‘X’ next to the script.
Add a Script to the Default Scripts

You can add a script to the default scripts to run every time you start Interface.

  • In Interface, pull up your Tablet or HUD and go to Menu > Edit > Running Scripts.
  • Click ‘Reveal Scripts Folder’ at the bottom.
  • In the file explorer window, open the ‘defaultScripts.js’ file.
  • Add your script to this file to make it run with other default scripts. Ensure the folder path to your script is correct.

Note

The ‘defaultScripts.js’ file is updated every time you update Interface to the latest release version. This means that any changes you make to the file will be overwritten. You can avoid this by writing and running a ‘loader’ script to load scripts on start up.

Scripting Console

The Scripting Console lets you test and run short script snippets quickly in 8 agora to see how they work. To open the console, go to the ‘Developer menu’, then Scripting > Console. If the ‘Developer’ menu is not visible, first go to the ‘Settings’ menu and click ‘Developer’ Menu.

_images/scripting-console.png
Debug Window

The Debug Window shows the output generated by your running scripts. This lets you watch the script(s) in action and make sure that it is running as you intended. If the script fails, the debugger can help you identify what went wrong, and point you to specific lines of code where the error occurred. To open the Debug Window, go to the ‘Developer’ menu, then Scripting > Script Log (HMD Friendly). If the Developer menu is not visible, first go to the ‘Settings’ menu and click ‘Developer’ Menu.

_images/debug-window.png

See Also

Write Your Own Scripts

8 agora’s robust JavaScript API provides the tools for you to build great content and user experiences in VR.

In this section, you can find simple code samples to do common tasks in 8 agora. To see these code samples in action, copy the code to a file, testScripts.js, saved somewhere on your computer.

Note

Entity scripts, unlike interface scripts, are in containing functions. The example scripts here cannot be attached to an entity (and be used as an entity script) unless they are in a containing function ``function() {}``.

On This Page:

Write to the Debug Window

This is an example of an interface script and cannot be attached to an entity. It shows you how to print something to the debug window . In this example, we’ll start with a simple “Hello, World” script.

print("Hello, World");
  1. Copy and paste this in a file testScript.js and save it on your computer.
  2. When you load and run this script, it will write the words “Hello, World” to the ‘Debug Window’ in 8 agora. _images/hello-world.png
Create an Entity

Instead of using the Create app to add an entity, you can create one using an interface script.

// Get your position in the domain, so that the cube is spawned in front of you
var position = Vec3.sum(MyAvatar.position, Quat.getFront(MyAvatar.orientation));
var properties = {
    type: "Box",
    name: "ScriptBox",
    position: position,
    color: { red: 255, green: 0, blue: 0 }
};
var entityID = Entities.addEntity(properties);
print("Entity added");
  1. Copy and paste this in a file testScript.js and save it on your computer.
  2. When you load and run this script, it will locate your avatar in the domain, create a new entity based on the customized properties that you set, then print a line to the ‘Debug Window’. In this case, the entity will be a red box._images/add-entity1.png
Edit an Entity

To manipulate an entity’s properties, you can use Entities.editEntityin an interface script.

var entityID = Entities.addEntity({
    type: "Box",
    position: Vec3.sum(MyAvatar.position, Quat.getFront(MyAvatar.orientation)),
});

var properties = Entities.getEntityProperties(entityID, ["color"]);
print("Entity color: " + JSON.stringify(properties.color));

Entities.editEntity(entityID, {
    color: { red: 255, green: 0, blue: 0 }
});
properties = Entities.getEntityProperties(entityID, ["color"]);
print("Entity color: " + JSON.stringify(properties.color));
  1. Copy and paste this in a file testScript.js and save it on your computer.
  2. When you load and run this script, it will locate your avatar in the domain, create a new entity based on the customized properties that you set, then print the color of that entity to the ‘Debug Window’. Then, the script changes the color of the entity to red, and prints the new color in the ‘Debug Window’. _images/edit-entity.png

See Also

JavaScript Tips & Tricks

8 agora’s robust JavaScript API provides the tools for you to build great content and user experiences in VR. We’ve compiled some advanced JavaScript tips you can use while scripting for 8 agora.

You can use the Scripting Console in Interface to try out the examples on this page. The output will be visible in the console itself.

On This Page:

Compute 3D Math Operations

When you script for VR worlds like 8 agora, you need 3D math operations to compute the position and orientation of 3D objects and avatars in-world. We cannot simply add two vectors. To script 3D math operations and to determine position and orientation information of avatars, you can use the following namespaces in our JavaScript API:

  • Vec3: The Vec3 API has facilities for generating and manipulating 3-dimensional vectors.
  • Quat: The Quat API provides facilities for generating and manipulating quaternions.
  • MyAvatar: The MyAvatar API provides facilities for manipulating avatars.
Get Your Avatar’s Position

When creating objects in world, it’s often very helpful to know where your avatar currently is.

8 agora uses a 3D Cartesian coordinate system where the position vector of an entity or avatar looks like this:

{ x: 0, y: 0, z: 0 }

To get your avatar’s current position, use the MyAvatar namespace. MyAvatar contains properties with information related to your avatar. Use the position property, MyAvatar.position, which returns an object.

In the following example, we are using the JSON.stringify method to convert the JavaScript object (returned by MyAvatar.position) to a data string that can be sent over the server.

Open your Scripting Console and find your avatar’s position.

JSON.stringify(MyAvatar.position);
// {"x":-10.349810600280762,"y":-9.55379867553711,"z":11.861204147338867}
Get Your Avatar’s Orientation

If you want an object to appear in front of you, you need to know how your avatar is currently oriented in-world.

Rotations are handled are by a number-system called Quaternions. Quaternions help simplify calculations in three dimensional space. They add an extra dimension of ‘w’ and the values are normalized (-1,1).

Quaternions are represented in the form:

{ x: 0, y: 0, z: 0, w: 1 }

Get your avatar’s orientation in the Scripting Console by using the MyAvatar.orientation property:

JSON.stringify(MyAvatar.orientation);
// {"x":0,"y":-0.4974651634693146,"z":0,"w":0.8674839735031128}
Get the Direction Your Avatar is Facing

You can use the Quat namespace to get the direction which your avatar is facing. Pass your avatar’s orientation to Quat.getForward to get a vector describing which direction you are facing on the world axis.

{ x: 0, y: 0, z: 1 } // Backward
{ x: 0, y: 0, z: -1 } // Forward
{ x: -1, y: 0, z: 0 } // Left
{ x: 1, y: 0, z: 0 } // Right
Make an Entity Appear Before Your Avatar

You can make an entity appear before your avatar and also control the distance at which it appears.

Use the Vec3 namespace and the direction your avatar is facing to return the position at which you can make your entity appear. This position is 1m away from your avatar.

Vec3.sum(MyAvatar.position, Quat.getForward(MyAvatar.orientation)); // This will add your position vector to the direction vector returned from Quat.getForward. This will represent a position that is 1 meter in front of your avatar.

You can also control the distance at which an entity appears rather than using the default distance of 1m. First, multiply the vector representing the direction your avatar is facing and the distance.

Vec3.multiply(Quat.getForward(MyAvatar.orientation), 2.0); // if we are facing forward, that means our vector { x: 0, y: 0, z: -1 }, get's multiplied by 2.0 giving us a vector of { x: 0, y: 0, z: -2 }

Use Vec3.sum to return a new vector representing how far away an entity will appear from your avatar.

Vec3.sum(MyAvatar.position, Vec3.multiply(Quat.getForward(MyAvatar.orientation, 2.0))); // this will give us a final vector representing where in the world a point 2 meters directly in front of our avatar is

We’ve included the above operations in a function below for you to save and run as a script.

var myPosition = MyAvatar.position;   
var myOrientation = MyAvatar.orientation;
var myDirection = Quat.getForward(myOrientation);
var distanceInFrontOfMe = 2.0;
var distanceVectorOfObjectInFrontOfMe= Vec3.multiply(myDirection, distanceInFrontOfMe);
var positionOfObjectInFrontOfMe = Vec3.sum(myPosition, distanceVectorOfObjectInFrontOfMe);

// we can even wrap this all up in a function to help simplify this any time we want the position of an object to appear in front of us
function getPositionInFrontOfMe(distanceInFrontOfMe){
  var myPosition = MyAvatar.position;
  var myOrientation = MyAvatar.orientation;
  var myDirection = Quat.getForward(myOrientation);
  var distanceVectorOfObjectInFrontOfMe= Vec3.multiply(myDirection, distanceInFrontOfMe);
  var positionOfObjectInFrontOfMe = Vec3.sum(myPosition, distanceVectorOfObjectInFrontOfMe);
  return positionOfObjectInFrontOfMe;
}

getPositionInFrontOfMe(4.0); // { x: 0, y: 0, z: -4 }
getPositionInFrontOfMe(8.0); // { x: 0, y: 0, z: -8 }
Include External JS and JSON Files

When writing a script in 8 agora, you might need to access the methods or objects in an external JS file or get information from a JSON file. For example, if you’re writing a script to make your avatar wave, you might need to use some methods that already exist in an external JS file. You can do this using the require method in the Scripts namespace of our API.

Any script that you try to retrieve using this method must export either a function or an object. Let’s try this using an example.

Create a JS script that you want to access from your main script.

example.js

module.exports = {
    sayHello: function () {
        console.log("Hello!");
    },
    sayGoodbye: function () {
        console.log("Goodbye!");
    }
};

In example.js, you are exporting two functions that print either Hello or Goodbye, depending on which function you call, to the console. Now, let’s use require in your main script.

Create a JS script called main.js.

var greet = Script.require(Script.resolvePath("example.js"));
greet.sayHello(); // prints Hello to the console

When you use the require method, you are making any function or object exported from example.js available to main.js. This means that main.js now has access to functions that will print either Hello or Goodbye to the console. In the above example, we are printing Hello to the console when we run main.js.

Note

We recommend using relative paths in your development so that you can easily move content without having to update absolute paths. However, in JSON files, you have to use absolute paths .

Equip an Item

You can equip an item by grabbing and holding an entity without pressing the grab button or trigger continuously. For example, you could equip a paint brush to your avatar’s hand and drop it only when you’re done painting.

You can equip an item using a script:

Messages.sendLocalMessage('Hifi-Hand-Grab', JSON.stringify({hand: 'XXX', entityID: 'YYY'})); \\ where XXX is either the left or right hand and YYY is entityID to equip

To drop the entity from your avatar’s hand:

Messages.sendLocalMessage('Hifi-Hand-Drop', 'XXX'); \\ where XXX is either the left or right hand
Connect a Signal to a Function

Signals can be connected to functions. This means that every time a signal is triggered, a function is executed. For example, if your avatar changes when collisions are enabled or disabled, you can connect a function to react to this specific event such as:

function collisionChanged(enabled) {
  if(enabled) {
    console.log("avatar collision is enabled");
  } else {
    console.log("avatar collision id disabled")
  }
}

MyAvatar.collisionsEnabledChanged.connect(collisionChanged);

Each signal usually gets passed in arguments, and you can refer to the API documentation to see what a signal will provide you, such as the enabled property passed into collision changed.

It’s good practice to disconnect from signals, but you can only do that if you name your function.

MyAvatar.collsionEnabledChanged.disconnect(collsionChanged);

See Also

Interface Scripts

Interface scripts run on your local machine, as long as you have Interface up and running. Each user has full control over when interface scripts are started and stopped. The results (such as when your script changes the color of a box) can be seen by everyone in your domain, but the script itself is running on your local machine. Your Interface will communicate that information to the Entity Server, which will communicate it to whoever is visiting the domain.

With interface scripts, you can do things like add new menus to the Interface, add plug-ins, or add 3D overlays that you have control over.

On This Page

Load an Interface Script

To load and run an interface script:

  1. In Interface, go to Edit > Running Scripts or press Ctrl + J on your keyboard.
  2. For scripts hosted in the cloud, click ‘From URL’. Enter the URL of your script file and click ‘OK’.
  3. For scripts on your local computer, click ‘From Disk’. Browse to your script file and click ‘Open’.
Example of an Interface Script

The following script automatically enters a first person perspective when you enter VR mode with a HMD.

(function() { 

// Automatically enter first person mode when entering HMD mode
HMD.displayModeChanged.connect(function(isHMDMode) {
    if (isHMDMode) {
        Camera.setModeString("first person");
    }
});

}());

See Also

Assignment Client Scripts

Assignment Client (AC) scripts (also known as “persistent scripts”) run persistently in a domain and aren’t affected by other scripts. These scripts run on an assignment client separate from the Interface, so the script will continue to run until you either remove the script from the domain or you shut down the domain entirely.

With AC scripts, you can do things like coordinate actions between entities and avatars, and add virtual pets to greet visitors to your domain.

On This Page

Add an AC Script

Once you’ve written and hosted your script, you need to add it to a domain, either your own or one where you have permissions to run an AC script.

  1. Open your ‘Domain Administration Panel’. If you are on a local sandbox, open it by clicking on the 8 agora icon in the taskbar notifications and ‘click Settings’.
  2. From the menu, go to Content > Scripts.
  3. In the Persistent Scripts section, click + and paste the URL to your script under ‘Script URL’. _images/ac-script.png
  4. At the top of the page, click ‘Save and Restart’. Now, every time you enter that domain, the AC script will be running.
Example of an AC Script

The following script counts the number of entities found in a domain using 8 agora’s EntityViewer.

var SEARCH_CENTER = {x: 0, y: -10, z: 0};
var SEARCH_RADIUS = 100;

var isInitialized = false;
var timeout = 1000;

var update = function(deltaTime) {
    if (!isInitialized) {
        if (Entities.serversExist() && Entities.canRez()) {
            EntityViewer.setPosition(SEARCH_CENTER);
            EntityViewer.setCenterRadius(SEARCH_RADIUS);
            EntityViewer.queryOctree();

            Script.setTimeout(function(){
                var foundEntities = Entities.findEntities(SEARCH_CENTER, SEARCH_RADIUS).length;

                print("AC Script found: " + foundEntities + " entities within " + SEARCH_RADIUS + "m of " + JSON.stringify(SEARCH_CENTER));
    
            }, timeout);
         
            isInitialized = true;
            Script.update.disconnect(update);
        }
    }
};

Script.update.connect(update);

See Also

Avatar Scripts

Avatar scripts are bound to an avatar. This means that they run when a user puts on a specific avatar. Likewise, avatar scripts stop running when the avatar is removed or changed. Other users in the domain will be able to see the script in action, but they will not be able to run the script themselves.

With avatar scripts, you can do things like make your hair flow or create particle clouds around your avatar.

On This Page

Add an Avatar Script

There are two different ways you can add an avatar script to your FST file: either by using our Package Model tool or by manually adding the script.

Note

To add an avatar script using the Package Model tools:

  1. Create a folder called scripts in the same location as your FBX file.
  2. Copy your avatar script into this new folder.
  3. In Interface, go to Edit > Package Model as .fst
  4. For ‘Script Directory’, enter the path to the scripts folder you created above.

To add an avatar script manually:

  1. Open the FST file for your avatar in the text editor of your choice.
  2. Add a line telling the avatar where to find the script file using the syntax script = [SCRIPT URL]._images/add-script.png

You can add multiple scripts to your avatar by adding multiple script = url lines.

Example of an Avatar Script

The following script makes your avatar throw balls when its right hand moves.

function(){
    var triggerDistance = 0.0;
    var TRIGGER_THRESHOLD = 0.9;
    var LOAD_THRESHOLD = 0.6
    var init = false;
    var rightHandIndex = MyAvatar.getJointIndex("RightHand");
    var rightArmIndex = MyAvatar.getJointIndex("RightArm");
    var distance = 0.0;
    var triggered = false;
    function fireBall(position, speed) {
        var baseID = Entities.addEntity({
            type: "Sphere",
            color: { blue: 128, green: 128, red: 20 },
            dimensions: { x: 0.1, y: 0.1, z: 0.1 },
            position: position,
            dynamic: true,
            collisionless: false,
            lifetime: 10,
            gravity: speed,
            userData: "{ \"grabbableKey\": { \"grabbable\": true, \"kinematic\": false } }"
        }); 
        Entities.editEntity(baseID, { velocity: speed });
    }
    Script.update.connect(function() {
        rightHandPos = MyAvatar.getJointPosition(rightHandIndex);
        rightArmPos = MyAvatar.getJointPosition(rightArmIndex);
        fireDir = Vec3.subtract(rightHandPos, rightArmPos);
        var distance = Vec3.length(fireDir);
        triggerDistance = distance > triggerDistance ? distance : triggerDistance;
        if (!triggered) {
            if (distance < LOAD_THRESHOLD * triggerDistance) {
                triggered = true;
            }
        } else if (distance > TRIGGER_THRESHOLD * triggerDistance) {
            triggered = false;
            fireBall(rightHandPos, Vec3.normalize(fireDir));
        }     
    });
    MyAvatar.scaleChanged.connect(function () {
        triggerDistance = 0.0;
    });
})()

This example script uses the MyAvatar namespace to determine if your avatar’s hand moves. Upon detecting movement, the script makes your avatar launch balls. It also uses some other namespaces such as Entities (to create the ball you will launch) and Vec3 (to determine the right positions and distances). Add it to your avatar to see how it works.

See Also

Client Entity Scripts

You can make content in 8 agora interactive by attaching scripts to entities. Client entity scripts are entity scripts that run locally on each user’s computer. When a user comes into contact with the entity, it will “preload” (or run) the script, then “unload” (or stop) the script when the user leaves.

There can be (and typically are) multiple entities in a domain, and each one can have a different client entity script associated with it.

On This Page

Attach a Client Entity Script to an Entity

To attach a client entity script to an entity:

  1. In Interface, pull up your tablet or HUD and go to Create.
  2. Select the entity you’d like to script by either clicking on it in Interface or finding it in the ‘Entity List’.
  3. In the Create app, go to the ‘Properties’ tab and scroll down to the ‘Behavior’ section.
  4. For Script, enter the URL to your client entity script.

Note

For client entity scripts, the URL content must be available to every user who visits the domain. This means the URL should be a public http(s) URL, or an Asset Server (ATP) URL for the domain. It cannot be a file URL. The script property also accepts a string as input, allowing you to insert the code directly.

Example of a Client Entity Script

The following script changes the color of a non-model entity (such as a box or a sphere) when you click on it:

(function () {
    var clicked = false;
    this.clickDownOnEntity = function (entityID, mouseEvent) {
        if (clicked){
            Entities.editEntity(entityID, { color: { red: 0, green: 255, blue: 255} });
            clicked = false;
        } else {
            Entities.editEntity(entityID, { color: { red: 255, green: 255, blue: 0} });
            clicked = true;
        }
    };
})

This example is written as a JavaScript class prototype function, and it uses the mouse event clickDownOnEntity(). When the user clicks on an entity, clickDownOnEntity() triggers the function associated with that click event. In this case, it changes the entity’s color back and forth between yellow and magenta.

See Also

Server Entity Scripts

You can make content in 8 agora interactive by attaching scripts to entities. Server entity scripts are entity scripts that run on the server (or domain) that hosts the entity. These scripts run persistently in a domain, even if there are no users present. This means that there is only one instance of the script is running at a time, and it is running on the server. Any behavior that is controlled by your script will be seen and heard by everyone in the domain.

On This Page

Attach a Server Entity Script to an Entity

To attach a server entity script to an entity:

  1. In Interface, pull up your tablet or HUD and go to Create.
  2. Select the entity you’d like to script by either clicking on it in Interface or finding it in the ‘Entity List’.
  3. In the Create app, go to the ‘Properties’ tab and scroll down to the ‘Behavior’ section.
  4. For ‘Server Script’, enter the URL to your server entity script.

Note

An entity can have multiple server entity scripts attached to it, but all of these must be through a single file URL.

Example of a Server Entity Script

The following script modifies the intensity of a light entity, so that it flickers tea lights.

(function() {
    var MINIMUM_LIGHT_INTENSITY = 100.0;
    var MAXIMUM_LIGHT_INTENSITY = 125.0;

    // Return a random number between `low` (inclusive) and `high` (exclusive)
    function randFloat(low, high) {
        return low + Math.random() * (high - low);
    }

    var self = this;
    this.preload = function(entityID) {
        self.intervalID = Script.setInterval(function() {
            Entities.editEntity(entityID, {
                intensity: randFloat(MINIMUM_LIGHT_INTENSITY, MAXIMUM_LIGHT_INTENSITY)
            });
        }, 100);
    };
    this.unload = function() {
        Script.clearInterval(self.intervalID);
    }
});

This script is a good example of a server entity script because it only needs one actor to update the intensity of the light. The same script could be attached as an entity client script, but all clients who could see the tea light would be editing the entity to vary the intensity of the light to flicker it.

Script API

The Entity Script Server does not have access to all of the listed components of the API. APIs for avatars, controllers, recording, overlays, and mouse and keyboard events are not available in the Entity Script Server.

Learn more about what APIs are available to server entity scripts here.

See Also

Content Creation

What video codecs do you support?

We support the following video codecs:

  • WebM VP8
  • H.264, WebM
  • WebM, H.264

Troubleshooting

Why can’t I connect to a domain?

If you cannot connect to your virtual workplace, follow these steps to resolve the issue:

  1. Check your internet connection, and ensure that your bandwidth is at least 10Mbps download, 2Mbps upload.

  2. You may not have permissions to enter the domain. If you know the domain owner, contact them to gain access to the domain.

  3. Ensure that your firewall settings allow you to run 8 agora.

    • For Windows: In your firewall settings, open the port 40102, and add ‘interface.exe’ to the list of allowed apps.
    • For Mac: In your firewall settings, add ‘interface.app’ (Library > Application Support > Launcher > interface.app) and allow incoming connections for that application.

No one can hear me!

If other users in the domain can’t hear you, then you are likely muted or your microphone gain is set too low. Here are some steps to troubleshoot your issue:

  1. Are you muted in 8 agora? When logged in, check the upper left corner. If you’re muted, click the microphone to un-mute yourself.

  2. Is your physical output device muted or turned off? Some headsets and microphones have a ‘Power’ and/or ‘Mute’ switch directly on the device itself. This setting is completely independent of 8 agora’s mute option, so even if you’re not muted in 8 agora, your device itself may not be turned on or the mute button may have been pressed.

    _images/headsets.png

  3. Is your mic muted or disabled on your computer? Lastly, your device might be muted or disabled by your operating system. Check your operating system’s input device settings:

    1. On Windows, go to Control Panel > Sound > Recording tab. Choose the device you are using with 8 agora and click ‘Properties’. On the ‘Levels’ tab, check the icon next to the volume meter. The microphone icon will tell you whether your headset/microphone is muted. If you’re muted, click the icon to un-mute yourself.
    2. On Mac, go to System Preferences > Sound > Input tab. Choose the device you are using with 8 agora. If the ‘Input volume’ is turned all of the way down, then your input device is disabled. Turn up the input volume to re-enable your microphone.

  4. Have you allowed 8 agora access to the microphone? Some operating systems require you to give explicit permission to apps to take advantage of specific hardware or software capabilities on your computer. Check your microphone permissions in your operating system settings:

    1. On Windows, go to Settings > Privacy > Microphone. Make sure that ‘Allow desktop apps to access your microphone’ is turned on.
    2. On Mac, go to System Preferences > Security & Privacy > Privacy, then select ‘Microphone’. Ensure that the checkbox next to 8 agora is selected.

If your input device is turned on, and you are not muted in the application, device, or operating system, then it is likely that your microphone volume needs to be adjusted or boosted. This is done in your operating system settings:

  • On Windows, go to Control Panel > Sound > Recording tab. Choose the device you are using with 8 agora and click ‘Properties’. On the ‘Levels’ tab, adjust the ‘Microphone Level’ and/or ‘Microphone Boost’.
  • On Mac, go to System Preferences > Sound > Input tab. Choose the device you are using with 8 agora and adjust the ‘Input volume’.

I can’t hear anything in 8 agora.

Here are some reasons you might not have audio:

  • Your headset or speakers are turned off.

  • Your headset or speakers may be muted or disabled by your operating system. Check your operating system’s output device settings:

    • On Windows, click the volume icon in the taskbar and select your audio device. The speaker icon will tell you whether or not your headset or speakers are disabled. Click the icon to un-mute yourself.
    • On Mac, go to System Preferences > Sound > Output tab. Choose the device you are using with 8 agora. At the bottom of the dialog, uncheck ‘Mute’ to un-mute yourself.

  • Your headset or speakers have a volume control of their own. Check that the volume is turned up on the device.

  • In 8 agora, you have a different audio device selected than the one you want to use. Open the Audio app and make sure the right headset, speakers, and/or microphone are selected.

  • Volume is turned down or off in 8 agora. Open the Audio app and check your volume settings.