Play Yabal

How to create a space for Yabal

Requirements

  • Unreal Engine 4.27

  • An Empty Unreal Project

  • The YabalXR Plugin

  • No other Plugins[6]

Getting Started

The first thing you need to do is prepare your environment to develop for Yabal. Follow the steps closely!

Git-Repo Setup

  1. Open up the empty Unreal Engine Project

  2. In the top left corner go to Edit->Plugins

  3. In the now open Plugins window click on "New Plugin"

  4. Enter "DLC_10004" as the plugins name. NOTE: Replace "DLC_10004" with your PluginID

  5. Fill out the remaining Information however you see fit or leave empty

  6. When you are done click on "Create Plugin"

  7. Now find the directory of your Unreal Engine project

  8. Go into the "Plugins" Directory and check out your assigned Git repository here

    1. It should look like "<ProjectRoot>\Plugins\<RepoName>"

  9. Next open the folder of your newly created plugin an move over its content into the Git-Repo you just checked out

  10. remove the now empty plugin directory

  11. Commit the changes and push

Basic Project Setup

NOTE: ALL CONTENT EXCEPT LEVEL FILES AND LANDSCAPE DATA NEEDS TO BE CREATED AND PLACED INSIDE OF THE PLUGINS CONTENT DIRECTORY!

  1. Head back into Unreal Engine

  2. Go into ProjectSettings->Engine->Rendering and set the VirtualTexture Settings as follows:

  3. Create new Folders so that you get the following folder Hierarchy inside the main Projects Content Directory!: "Content/Yabal/<YourAssignedLocationName>"

  4. Enter the Folder "Content/Yabal/<YourAssignedLocationName>" and create a new Level and name it <YourAssignedLocationName>_ROOT

  5. Find your Plugins Content Directory

  6. Create a new Actor inherting from "BP_Effects" and name it "BP_Effect_<YourAssignedLocationName>"

  7. Create a new Actor inherting from "BP_LevelSetup_Base" and name it "BP_LevelSetup_<YourAssignedLocationName>"

  8. Open the "BP_LevelSetup" Blueprint

    1. Overwrite the "Begin Level Setup" Function

    2. This Function NEEDS to call "Setup Done" with "Success" = "true" you will be able to initialize your Location here

    3. In this actor you will need to assign your levels as you build your space more info on that will be provided later in this doc

  9. Create a new PrimaryAssetLabel in the plugins root directory

    1. For that right click the content browser while in the root directory and find "Miscealeanous->DataAsset" and select "PrimaryAssetLabel" as the base class

    2. Name the Asset "DLC_<YourAssignedPluginID>_Label"

    3. Open the Asset and set the following settings:

      1. ChunkID = <YourAssignedPluginID>

      2. ApplyRecursively = true

      3. LabelAssetsinMyDirectory = true

      4. IsRuntimeLabel = true

  10. Now open the "_ROOT" level you created in step 3.

  11. Via the "Place Actors" menu drag and drop a "LevelSettings" Actor into your root level

  12. Assign the BP_LevelSetup Actor and the BP_Effects Actor you created into the corresponding fields

  13. Save everything and Commit + Push

Outside view (optional)

You can have an actual building in the world, where people can see your location and enter. This can also only be a portal, or anything you can think of. Also a sign where people can interact with, to travel to your location.

You must provide 3D Assets fitting to our style guide. If you need actual light sources for your outside view, talk to our team, if and how this can be done.

Inside view

You implement your inside as your own level fully autonomous following some basic naming conventions and using our YabalXR Plugin[7]. For an easy start we also provide a template project[8].

For your brand you will be assigned an internal location name derived from your brand. We will reference this as <location> wherever you replace it with your assigned name.

Folder structure of Content Browser

In Unreal all your files have to be in these folders:

  • <PluginRoot>/Brand_<location>/… *your assets & blueprints*

  • Yabal/<location>/… *your map files*

Level structure & naming

Do not place any stationary or static light outside of a light scenario! Moveable light’s are okay, but not encouraged. All Levels but ROOT and BASE are optional, but you should have at least 1 light scenario.

Creating a Level Configuration

For your levels to actually load when in Yabal you need to setup a level Configuration. For that open you BP_LevelSetup blueprint and assign your levels to their corresponding fields. Next edit the Level Configuration (In the same Blueprint below the level references). The Indices correspond to the Level references you assigned above.

If you don`t have a LightScenario for your level set the index to "-1"

Note that currently only the "Default" Configuration is supported but can and should be edited!

Access Control and Stream

Access Controlled Area: An Area with restricted Access based on required Ticket or Player Roles

Concert Streaming Area: An Area, wich when entered starts the concert stream and upon exit stops the concert stream

Access Control: An Area assigned to the Access Controlled Area defining the Area where the actual access check takes place. This is a separate Area since depending on the way the access permission is checked (ex. Backend call) the process can take some time. Meaning the Access Control Area acts as a kind of "Buffer" around the actual Area that needs to be access protected

The Stream will automatically start if a player enters an access controlled area and stop when he leaves. If the player does not have the correct right (admin, crew or valid ticket), the player will be blocked from entering the area. If the spawn lies in an access controlled area, the player will be thrown back to the main menu with a message.

  1. Assign the Tag "access controlled area" to the area you want to protect. This can be any actor in the world from a Collider/Trigger Box to an Actual Mesh etc.

  2. Assign the Tag "concert streaming area" this can be the same as the first but can also be a different Actor. The only requirement here is that this needs to be some kind of Trigger Volume (ex. Trigger Box/Sphere)

  3. WIP: Additional Arguments can be specified via the Tags:

    • WIP: "ACA_Ignore:" specifies Roles that should be completely excluded from the access checks

    • "ACA_Margin:" lets you specify a Margin as an Integer Value which corresponds to the Margin that he "Access Control" is bigger (or smaller) than the actual "access controlled area"

    • "ACA_CheckInterval:" Numerical Value which specifies the time between ticket Re-Checks for Players who are inside the Access Control but not inside the concert/event/concert streaming area

    • "ACA_DisableTicketRecheck:" 0/1 Representing a bool to enable or disable the automatic Ticket Re-Check

  4. Thats it!

  5. On Level Load the system will automatically assign the access control to the access controlled area and size it according to its parent Actor and the specified margin.

Player Spawns

You have to place at least one spawn point for the player, choose wisely where they should spawn and give enough points and/or enough space. Give the PlaySpawns the Actor Tag “PlayerStart”.

Effects

You can trigger effects in your Level from an admin interface. Create a child Blueprint from the BP_Effects Actor provided in the YabalXR Plugin.

The following actions are provided:

  1. SetLightScenario <id:int>

  2. SetValue <id:int> <value:int>

SetLightScenarios

You will not have to overwrite this method, just provide a list of your light scenario names in the “lightScenarios” Array Variable. The Index will be the Id.

In the backend you will have dedicated push buttons for triggering the scenarios.

SetValue

In the Admin any control has an ID and some values that will be sent on change;

  • Trigger Button: will just trigger with a static value of 1

  • Momentary Button*: will trigger with 1 on press and 0 on release

  • Switch: will trigger 1 when turned on and 0 when turned off

  • Selector: will send one of the preset values when changed

Persistence

Persistence of your effects will be important for effects that stay on or rely on a previously sent value. Only players currently connected will receive your control commands, so players joining late need to know the state of your effect parameters.

The Parent BP_Effects Actor will keep track of all values for all IDs (only last state) for you. You can access it with the function “GetLastValue <id:integer>” it will return two parameters: Found: Bool -> tells you there is a value in the persistence or not Value: Integer -> the value you asked for - this will be -1 if not found.

Tipp: you can utilize this by only reacting to actual trigger ids directly and then read the parameters from this method as well.

The id 0 control is a bit special. If you set a value for id 0 it will reset all other persitet values, but will persist the new value for id 0. With this feature you can quickly reset the state or switch between effect-banks you programmed.

Admin Controls

Every control has an id and will trigger a setValue at all clients in a way. When it’s issuing the command and what values are possible is listed here: Basic rules:

  • controls are atomic and will never influence other controls and their values

  • You can’t configure the id, it will start with 0 and increment with every control you add

  • Id 0 is special! When issued it will reset persistence for all other ids and set its own value

  • You can have up to 30 controls and use any combination of types you want.

HINT: each send will cost performance, so try to keep the number of needed control presses low and prefer trigger over momentary

Dataflow of admin controls

Artist placement and manipulation

You can set the Spawn Points for your artists by putting the ArtistSpawnPoint in your level. We recommend placing it into your stage levels, if you have any. If you don’t have any, just place it in your base level.

Location of the actor will be the root of your artist. The artist will copy rotation and scale from the Spawn Actor as well.

After the automatic spawn (done by our backend) you can manipulate the artist.

You have several functions over the BP_Effects Actor (so in your child available) to get and set things on the artist.

Set Artist Scale wants a scale in percentage. So 100 is the normal scale. The transformation is done by a timeline over 2 seconds, so the artist will grow/shrink animated.

Artist grabbing items

You can make the artist grab static meshes in both hands, and you are able to grab and release over admin commands as you have an Artist manipulation method in BP_Effects Actor called “Set Artist Grab”. But in order to make this work, you have to prepare your artist:

  1. Place sockets to the skeleton in unreal “left Hand” and/or “right Hand”.

  2. Adjust position and rotation of the socket in unreal and/or the pivot of your object in your 3D modelling tool, so the object is attached to the right position and rotation you want it.

Camera Director Mode

With the camera director role a user can turn on a special mode to control cameras, with this mode you can create a stream or recording from your show using multiple cameras.

Camera Placement

To place a camera for your level and set it up for use with the camera director interface proceed as follows:

  1. Add your cameras to the base level of your location (<name>_BASE)

  2. The cameras are expected to be of the type “CineCameraActor”

  3. Position the cameras as you like or add movement of any kind to them

  4. Tag the Actors with <location_name>_Camera

  5. Tag the Actor with CAM_ID:<numerical_ID>

  6. That's it! The System should be able to pick up your cameras and show them in the Camera Directors interface!

Use of the Camera Director

Chat Commands

This is a list of chat commands available through the chat. Some commands are only useable on one server (L), others will affect all servers (G).

You need specific roles for most of the commands (grayed out means not yet available)

And there are two more specials:

  1. Chatwall Using the Hashtag #AskTheArtist in a message will show the chat message on the 3D Chat wall (if there is a chatwall visible at your location).

  2. Mentions With @<playernam> in a message, the message will be a bit more highlighted in the chat of the mentioned player(s)

User Pledge & Emote System

Users can send emotes and pledge money from outside Unreal over the Yabal-Livestream Web-Client. These emotions and donations should be visible in the world for all. There is a default implementation to visualize this, but this can be overwritten in your location.

Default implementation

Emojies are now available over chat command:

/event mood <id>;<name>

Ids:

0 - Clap

1 - Crown

2 - Heart

3 - In Love

4 - Kiss

5 - Love

6 - Note

7 - Peace

8 - Rock

9 - Stars

10 - Sunglasses

11 - Surprise

12 - Say hi

Only Admins can trigger that command in Game! This command will usually be sent from the WebApp Users.

TODO: Document how to add them a location and how to overwrite them with own effects

Addendum

Bone Names

These are the default Bone Names. If using filtered stream to save bandwidth you MUST have the bones with the X in your rig, as only these bones will be streamed.

  1. Available late 2021 ↑

  2. https://www.mixamo.com/ ↑

  3. https://www.polywink.com/15-facial-animation-for-iphone-x.html ↑

  4. https://developer.apple.com/documentation/arkit/arfaceanchor/blendshapelocation ↑

  5. https://www.xsens.com/products/mvn-animate ↑

  6. Unless the GranolaXR team agrees to integrate the plugin to Yabal in general ↑

  7. https://gitlab.berlinoffice.granolastudios.com/GranolaStudios/yabalxr ↑

  8. https://gitlab.berlinoffice.granolastudios.com/GranolaStudios/granolaxr-template ↑

  9. Hand streaming is not yet available ↑

PreviousPlay with OG NFTNextHow to import avatars in Yabal

Last updated