MW-publications-LOGO-white-on-transp.png

Matthew Warner

Horizon World Newbie Scripting Concepts for PHP & JavaScript Programmers

If you have a programming background and have just begun to code in Horizon Worlds for the Oculus virtual reality headset, I feel for you. Here’s the article I wish I’d read when I started there a few months ago.

HORIZON … WHAT?
When I received an invitation to beta test the Meta app then called Facebook Horizon, I had no prior experience programming in virtual reality. Horizon Worlds — which users simply refer to as “Horizon” and which is not to be confused with its sister app Horizon Workrooms — is a collaborative creation tool to make gaming “worlds.” It’s a competitor to Rec Room. The experience of building and styling virtual environments from simple shapes reminds me of watching my sons play Minecraft and Roblox. The whole experience is wonderful and addictive. I haven’t played with any of my other Oculus programs in the last three months.

As with website creation, its users tend either to design things, like my friend Jay Haynes, who can craft realistic-looking chess pieces and cars, or code. I’m in the latter category, being more comfortable scripting than sculpting. And like with website designers and programmers, Horizon creators frequently team up, as Jay (Sensei_Jay) and I (Vulture667) have done on projects like Chess Parlor. For a recent entry in a contest, for example, Jay made a beautiful gun and wormhole out of primitive shapes, and I programmed them to shoot and teleport things.

Scripting in Horizon can be difficult to understand at the beginning. It can be like approaching a new martial art: you learn by doing and by consulting mentors and not necessarily by following a step-by-step curriculum. I come from a PHP and JavaScript coding background, and despite the heroic efforts of the Vidyuu Tutorials YouTube channel, I was thoroughly confused by Horizon’s “script gizmo” object. Script gizmos are literal (but virtual) cubes you pull from your building tools menu. They contain a visual scripting editor similar to Blockly in which you drop colorful blobs of code into other coloful blobs of code, thereby programming your creations’ behaviors.

There’s no requirement to attach script gizmos — let’s just call them SGs — to objects. You can make flowers and rocks or whatever all day long. You can even animate those objects through their internal properties panels. But the use of SGs raises your Horizon world to the next level.

So, are you ready to get started, Mx. PHP/JavaScript programmer? Here’s a primer. Civilians should be warned the following discussion will get technical.

OOP WITH LITERAL — BUT VIRTUAL — OBJECTS
After much hemming and hawing, I admit Horizon’s coding concepts are similar to the object-oriented programming concepts of PHP classes. The distinction, however, is we’re not instantiating objects from a class like we do in this PHP snippet:

<?php

class Shape {
   // Properties
   public $quality = 'juicy';

   // Methods
   public function get_quality() {
      return $this->quality;
   }
}

// Run time
$apple = new Shape();
echo $apple->get_quality(); // juicy

?>

Instead, we create an object out of primitive shapes and attach an SG to it. You can only attach one SG to an object or to an object composed of a group of objects. However, the same SG can be separately attached to different objects, and in that sense, each object becomes an instance of a class defined by the SG.

Figure 1. The 'Shape' script gizmo has been attached to the apple object. The SG has a string quality with 'juicy' as its default.
Figure 1. The ‘Shape’ script gizmo has been attached to the apple object. The SG has a string quality with ‘juicy’ as its default.

VARIABLES
Here are some things to know:

    • SG variables are like PHP class properties. SG event parameters are like PHP class method (function) arguments.
    • Most variables in an SG, whether accepted as input arguments or used internally, are declared on your SG’s “Variables” tab. I say “most” because input parameters to an “event” don’t have to be declared here (see below discussion of events).
    • Default values can be set on the Variables tab, but those defaults can be overridden within the object’s properties panel when the SG is attached to it, as in Figure 2 below. Overriding a default value is like adding $apple->quality = ‘rotten’; to your PHP runtime code or specifying an argument value in an ordinary function call in either PHP or JavaScript.

Figure 2. The 'Shape' script gizmo has been attached to the apple object. The apple has overridden quality's default value with 'rotten.'
Figure 2. The ‘Shape’ script gizmo has been attached to the apple object. The apple has overridden quality‘s default value with ‘rotten.’

  • Variables declared on the Variables tab are locally scoped to the SG.
  • There are no global variables for a game that all your SGs can reference unless you store them within another SG and call them through events sent between objects (see example below). There are, however, “player persistent variables” (PPVs), which are like cookies attached to a player’s ID and which survive game sessions; with these, you can record a player’s high score to be referenced in future sessions.
  • There are no game-persistent variables that can cross from one world to another. So if an RPG player has collected items into an inventory and then travels to a new game world — perhaps levels 1 and 2 are programmed in separate worlds — level 2 will not know what items were gathered in level 1. If level 2 could read level 1’s PPVs, that would be great, but PPVs only apply to the world in which they were created, like client-side cookies only apply to the website that issued them.
  • Arrays are called “lists” in Horizon. There are no associative arrays, just zero-based lists. Incrementors like – – and ++ are nice conveniences in other languages that don’t exist in Horizon, so to iterate over a list, you must set an incrementor variable to be equal to the length of the list and then decrement it via a command like “set incrementor to incrementor – 1″ during each passage through the loop, breaking out with a while command, e.g.:
while incrementor is > 0
set incrementor to incrementor - 1

Figure 3. Iterating through a list to print values to the debug console.
Figure 3. Iterating through a list to print values to the debug console.

EVENTS
Whenever you see a “when event is received” code block, that’s the equivalent of the get_quality() method in the PHP example above. It’s basically a function definition that lays out what things should happen whenever it’s called. There are no return lines, however, unless the event explicitly sends data back out. For instance, this PHP method:

   public function get_quality() {
      return $this->quality;
   }

Would look like this in Horizon Worlds:

when get_quality is received with calling_object
send return_quality to calling_object with quality

Those commands would live within colorful, Blockly-like blobs, of course.

It’s worth noting here that the calling_object parameter is also a variable, but it’s a variable that’s local to this event block, whereas quality references a string variable declared on the SG’s Variables tab. In other words, calling_object is an input argument. This means that calls to the get_quality event must have a corresponding number of arguments:

send get_quality to receiving_object with self

And just like in JavaScript and PHP, the typecast of the input and receiving arguments — called parameters — must match, too.  So if the call sends in string, boolean, object, then the recipient listens for string, boolean, object, in that order.  You can send and receive up to three of them. You can’t send lists.

An event that returns some point of data isn’t a common use of event definitions, though — but I think it would be an awesome use of them. Most events act directly upon objects in the game world. For example:

when paint_yourself is received
Set self color to color_variable

ASYNCHRONOUS VS. SYNCHRONOUS, ROUND 1
Without getting into a discussion of whether Horizon scripting is async or sync — because inevitably I will confuse those definitions — I’ll just tell you how I believe it works.

An SG’s commands within a given event block are performed sequentially but so quickly that they’re practically simultaneous. Before the introduction of the else and else if commands a few weeks ago, all we had were while and if. Boolean switches were a pain. Consider this snippet:

when world is started
if booleanvalue
set booleanvalue to false
if not (booleanvalue)
set booleanvalue to true

In my naiveté, I thought that was a great way to toggle booleanvalue until I realized that if the first if statement set a boolean to false, the second if statement would fire as well. This meant that (again, before the advent of else), toggling booleanvalue required firing events back to self on a delay:

when world is started
if booleanvalue
send togglefalse to self after #1 seconds
if not (booleanvalue)
send toggletrue to self after #1 seconds
when togglefalse is received
set booleanvalue to false
when toggletrue is received
set booleanvalue to true

In other words, if booleanvalue were true when the script began, the “if not (booleanvalue)” line within the when world is started block needed the command parser to move past it so it wouldn’t fire as well; so that’s why the togglefalse event was fired on a delay slower than the parser. Wow, what a pain, huh? So thank God they came out with else so we can simply write:

when world is started
if booleanvalue
set booleanvalue to false
else
set booleanvalue to true

ASYNCHRONOUS VS. SYNCHRONOUS, ROUND 2
Why is this so important, other than simplifying our code? I’m glad you asked.

Horizon allows us to send events to self or other objects on a delay. This is critical when doing things like rotating objects:

when world is started
send rotateme to self
when rotateme is received
send rotateme to self after #1 seconds
rotate self by 90.0.0 over #1 sec

Two things are happening here you need to notice. The first is the event listener you saw earlier, when world is started, which causes an event (rotateme) to fire. There are lots of event listeners to play with concerning things like collisions and grabs and button pushes, and you’ll have fun with those.

The second thing to note is what I’m talking about here regarding the near-simultaneity of the parser. Within the rotateme event, the “send rotateme to self after #1 seconds” command and the “rotate self by 90.0.0 over #1 sec” command basically occur at the same time. The send line is like saying in JavaScript: setTimeout(function(){ rotateme(); }, 1000);. So if you ever loop your events on a delay, like we’re doing here, then make sure your motion-over-time seconds parameter and your event-on-delay seconds parameter match, or you’ll get some crazy rhythm.

SCRIPT GIZMOS CAN ATTACH TO OBJECTS, OBJECT GROUPS, AND OBJECTS WITHIN THE OBJECT GROUPS
This fact made my brain explode. Let’s say you have a gun. If you’re me, it’s just an object group consisting of two perpendicular rectangles (for the handle and barrel) and one projectile launcher at the muzzle. If you’re my partner Jay, it’s a highly realistic looking sculpture to make you weep at its beauty.

The way you build this is to lay everything out, select them all, and then group them together and name them “gun” or something. You can then impart properties to the group such as physics, gravity, and grabbability, via its properties panel.

To make it fire, you attach an SG called “Fire Gun” to the gun. It says that when the player pulls the trigger on their controller to fire a projectile from the projectile launcher. The projectile launcher, being an object within the gun object group, is referenced locally within the SG’s Variables tab but passed into the script through the gun’s “Attached Script” panel.

Figure 4. One damn ugly gun shape with attached script to make its projectile launcher fire.
Figure 4. One damn ugly gun shape with attached script to make its projectile launcher fire.

This causes the projectile launcher to fire a pretty little sphere. If you want those spheres to do something, however, you have to attach a separate SG to the projectile launcher itself.

The parent gun object can be referenced within the projectile launcher’s SG if you like. Maybe upon projectile impact, you want the player to drop the gun for some reason.

Figure 5. Script attached to the projectile launcher, which is inside the gun object. Its script references the gun object to make the player drop the gun upon projectile impact.
Figure 5. Script attached to the projectile launcher, which is inside the gun object. Its script references the gun object to make the player drop the gun upon projectile impact.

This is just one example, but it’s an important concept for you to know if you want to impart your complex objects with complex behaviors.

DEEP WEED THOUGHTS: A SCRIPT GIZMO IS AN OBJECT’S BRAIN
Since an object can only have one SG attached to it, I find that comparing the SG to a brain is a useful analogy. Perhaps this is body-over-brain bias at work, but this comparison reminds me that the SG is an optional attachment to the object and that the object is not really an instance of the SG. The SG is only a set of instructions, and if separate objects use the same SG, then fine; they won’t necessarily think the same thoughts. The SG is nothing without the object; you hear me? Nothing!

Philosophy aside, I hope this primer helps break the ice between your programming brain and Horizon Worlds. If you have anything to add, please leave me a comment or holler at me on Facebook. I overly ambitiously intend to keep this article updated with new Horizon code releases.