Table of contents
Alloverse is an open platform for collaborative workspaces in 3D. It’s Gibson style Cyberspace, but for your day-to-day work and play, with your friends and colleagues. It’s a VR and AR platform for creating spaces, and for running real applications within those spaces, together with other people. In nerd terms, it’s a VR/AR/3D “window manager” and collaborative workspace.
For more information, please see the Alloverse website.
Your “place” is where you decorate, run apps, invite people, and hang out. It’s like a collaborative X11 server: It runs a world simulation server, a voip gateway, and all the backing data for 3d UIs for the running apps. The reference Elixir implementation is in alloplace. A “visor” is the GUI application you use to visit places and interact with your apps. allovisor implements such a visor for VR in Unity. An “appliance” is a process running on your computer, or on a computer on the Internet. Like opening a web page (or launching a remote X11 process), this app can then show its interface and be interacted with inside your place. The network and “UI protocol” is abstracted into the allonet library, written in C and used by all the above projects.
An Alloverse app is a server-side app that you run on your own server, similarly to how you would host a web app on your own server. The difference is, when a user goes to your app on the web, it loads into that user’s web browser on their computer; but when a user goes to your alloapp in an Alloverse Place, the app loads into the Place for all users in that Place to use, and your code gets collaboration and VR super-powers for free.
This tutorial will take you through creating an Alloverse app using the Lua programming language, since that is the language we’ve developed the most support for so far.
You can build apps on Mac, Linux or Windows; but for the latter, you’ll need a Unix shell, e g mingw, msys2 or WSL.
In contrast to a web framework like Rails or Django, Alloverse doesn’t install any software onto your system. Instead, a project is completely self-contained within its project folder, and contains everything it needs to run.
To write Alloverse apps, you’ll need the following:
- The Alloverse app.
- Terminal app (preinstalled on Mac and Linux, separate install on Windows).
- A plain text editor for code (We recommend Visual Studio Code).
- Git (Comes with Xcode on Mac. If you just type
gitinto a terminal, it’ll ask to install it for you even without Xcode).
- Only on Windows: Cygwin or MingW (this be a bit of a setup; we recommend doing this on a Mac or Linux).
First, create a project folder. Allo Assist requires Git to fetch all its dependencies, so we’ll init a Git repo in the folder. Then we can initialize the alloapp environment into it, and make sure it works:
(This is also a good time to
git commit -a, so the next commit only contains your own changes.)
The curl’d script will have created this project structure for you:
luacontains the Lua source code for your app
lua/main.luacontains your app! It barely does anything yet. But you can add more code to this file to keep going, and add more files into lua to modularize your code.
imagescontains images you want to use as textures on buttons, etc.
allocontains the Alloverse app framework. You should not edit anything in here, as an upgrade of the framework will overwrite your changes.
allo/assistis a script that helps you with tasks such as starting a server, installing dependencies, etc…
allo/libscontains compiled C dependencies as dynamic libraries and executables. These are
.gitignored to save space. If you check out your code on another computer, you can
./allo/assist fetchto install them again, so you don’t need to (and shouldn’t) commit them.
allo/boot.luasets up the runtime environment for your app. This code is generated, so it’s not recommended to modify this file.
That’s it! You should now be able to start your project and see it appear in an Alloplace. If you don’t have one already, you can use our sandbox alloplace://sandbox.places.alloverse.com, or be ambitious and boot one on your own (
docker run -e ALLOPLACE_NAME="my place" -p 21337:21337/udp -it alloverse/alloplace2). I’m gonna do the former:
If it all checks out, you should be able to jump into that place on your VR headset and press the button it has created.
Download the Visor app for your VR or desktop platform of choice, and then click “Connect”, “Sandbox” (or click the alloplace link of the place you’ve rented or started yourself).
Our app running in Nevyn’s place. I’ve clicked our simple app’s orange button button three times, and the laws of causality held up, printing “Hello” thrice to our terminal.
At this point, you could go off, do your own thing, read the documentation as you go. Or you could keep reading, and be guided through the development of a simple but functional todo list app, which will help establish the fundamentals and make it much easier for you to build real, complex apps.
This is also a good point at which to remind you: if you get stuck, or have questions or feedback, please hop on Discord and give it to us straight.
Let’s open up
lua/main.lua and have a look at the code, to understand what’s going on. If you’re not much for theory and you’d rather learn by doing, you can skip this section and dig directly into making an app.
Above, we’re using a Client to connect this app to a Place.
arg is the URL of the place to connect to, which Assist sets up for you in boot.lua. App then manages the Client connection for you, and manages the lifetime of your app.
Assets are files (images, glb models, videos, sounds, etc…) that you want to use in your app. They need to be published so that user’s headsets can download them before you can use them. We make
assets global so you can use it throughout your app.
Your application is represented by a hierarchy of views. If you’re a web developer, you can think of it as nested elements in a DOM. If you come from Unity, it’s similar to the GameObject hierarchy, with transforms being relative to parent GameObjects. If you’re an oldschool Macintosh Toolbox developer, I’m sorry.
app.mainView is the main UI for your app. You should set it up with your main user interface before connecting to the Place.
Bounds is the position and size of your object:
- The first three numbers are the x, y and z position (see coordinate space reference), and in this case they mean this view is centered horizontally; its base is 1.2 meters up from the floor; and -2 means 2 meters into the Place, depth-wise.
- The second group of three numbers is the width, depth and height. Here, we’re 1 meter wide, half a meter wide, and one centimeter deep.
We also make the main view
grabbable, so the user can move it around the Place. Alternatively, you can add a GrabHandle, which acts like the title bar of a desktop UI’s window.
The standard template has created a standard Button component for you, at 2 decimeters wide and high. Its position of 5 centimeter down and forward is relative to the
onActivated callback lets us run code when the button is pressed. This’ll print “hello” to your local terminal when you run the app on your machine (even if you’re running the visor somewhere else on the Internet!)
Finally, the template has configured the app’s main view to use this dummy UI. Then, it connects to the Place we’ve been asked to run in, and then hand over the runtime of the app to the UI framework so it keeps running until the user quits it.
Now that we got the gist of how to compose an app like this, we can replace it with something useful.
Let’s make a todo list app! I’m a master artist, so I’ve painted this piece of art to represent our goal:
So we’ve got:
- A list of items to check off,
- A button to add an item
- A dialog that pops up where you can name your item.
Sounds great. Let’s get started.
Note: This is where we start coding for real.
Select everything from (and including)
local mainView = ... down to
app.mainView = mainView and delete it, and we’ll write some new, fun code.
Instead of having a bunch of loose views strewn around the code, I enjoy creating a class for each main container of UI. Some equivalent of a “window”, or “view controller”, or “component” if you will. Let’s create a
TodosView, which will display the list of items, and allow you to quit the app, and add new items. Copy the code block below, and paste it between
We create a constructor, where we set up initial state and controls. Here we want a quit Button, and an add Button. We immediately add them as subviews to the TodosView, so they show up in the view hierarchy. For the first button, we use one of our image assets as a texture, and for the other, we set the text on the label instead.
AlloUI doesn’t have a comprehensive layout system instead, so we’ll call our own
layout at opportune moments. Let’s stub it out so we have something to start with. We’ll also create an instance of it, and use it as our app’s main view:
Fire off a quick
./allo/assist run in your terminal, and you’ll be presented with this beauty in VR:
We’ve created a VR interface, how cool is that!
Next up, let’s create that popup used for inputting new items.
Phew, that’s a handful. Let’s step through it.
popupis our new popup window. It’s another surface, one meter by a half.
- To it, we add a TextField! This is your standard issue text input view. Tapping it will focus it, which will display a virtual keyboard to the user (or if you have a hardware keyboard, you can just use that).
- We want to close the popup both when the return key is pressed, and when you manually tap the “Add” button, so let’s create a callback we can use for both called
onReturnis used to react to return/enter key, and we can also use it to make sure a newline character isn’t added to the text.
showNewTodoPopuphas been called with a
hand. That’s the hand of the user that tapped the “Add todo button”. It belongs to an avatar, so we can actually ask the avatar if it would pretty please focus this text field, so the user can begin typing in it directly? If you’d be so kind.
addButtonuses the same
cancelButtonjust closes the popup, no questions asked.
app:openPopupNearHandwill display our new fancy popup 60 centimeters away from the user’s hand, which is a convenient distance at which to do your job.
Warning: incoming rant
The cool thing about this popup is that if you have multiple people in the room, they can all get their own input popup, so they can add their own items without interfering with each other. This is an important and unusual aspect of UI design and development: all your UI is real time collaborative, so you have to consider how your application behaves when multiple people use it at the same time.
For example, if you had added the input field directly to the main view, only one user would’ve been able to add items at a time, and they’d likely have interfered with each other’s work. By using a personal popup, users can work naturally collaboratively and in tandem.
Relax: rant over.
Here’s what this new fancy popup should look like once you tap the “Add todo” button:
Before we continue, we’ll need another asset. Download checkmark.png and put it in
images/. Update the top of
main.lua to publish this asset:
Cool. Cool cool cool. Let’s make it actually possible to add todo items, yeah?
This should start to look familiar.
todoViewis the parent view of all the controls related to the todo list item. We store them in
self.todoViewsso we can layout them properly later.
checkButtonis used to check off a completed item. We place it along the left edge, tell it to use our new fancy checkmark texture, and configure it to call an as-of-yet nonexistent
labelis the text label describing our item. Text is black (that’s a list of Red, Green, Blue and Alpha, with components from 0.0 to 1.0), horizontally aligned to the left, with the text from the user.
- We call
layoutso our new item is positioned correctly
- And then we add it as a subview, yay!
removeTodo just finds the given item in the list, and removes it from both the list and the UI, running a relayouting pass to adjust the other items’ positions.
That’s awesome! We can now add and remove todo list items! Just one bummer: they all end up stacked on top of each other. We’ll need to lay them out before this is usable. Let’s replace our dummy
layout with something better.
Here’s a pattern I’ve brought with me all the way back from building black-and-white Mac apps in the 80s: using a
pen variable which represents a rectangle (or rather, a 3D box!) where we want to “stamp out” our UI, moving the pen as we walk through our items.
- We want to adjust the height of our UI to exactly fit our items. Each item is 13 cm tall, and then there’s 25 cm of padding for the “Add todos” button.
- The add button’s size is a perfect template for our pen. Let’s start the pen at the bottom of the window and lay out controls bottom-to-top, and also move it out from the surface so that our elements sit ON TOP of the surface, instead of embedded in it.
- Let’s add 7 cm of initial padding
- There. Stamp the pen’s current state into the add button’s bounds.
- Add another 15 cm of padding.
- Stamp the pen onto each todo item view, adding 13 cm of padding for each item.
- Figure out the perfect new location for the quit button, and…
- Set the height of the whole app to the one we calculated at the start, and update the bounds so it’s reflected on the users’ headsets.
You know what? I think this is pretty stellar. This’ll do nicely. If you dotted every i, your app should look something like this:
So, you built your fancy VR app. Now you want to show it off, and deploy it so all the Alloverse users in the world can run it in their places, right?
Our plan is to provide a Dockerfile which sets everything up just right for you, and an
./allo/assist invocation which deploys it onto Amazon ECS for you. Just a oneliner and it’s deployed. Boom.
We haven’t gotten that for yet, though. Watch this space!
If you made it this far, go eat a cinnamon roll, you deserve it. It’s on me. Really, just ping me on Discord and it’s yours. We’d at least love to hear from you, and see your creations.
Once you make your own apps, even if you’re not down with cinnamon rolls, do let us know, so we can feature your app in our app browser, blog and tweet about it, etc etc.