Using ZapBox with ZapWorks Studio


I have played with the demo golf game and works well.

  1. Would like to know do we use world codes for all our worlds we make?
  2. Can we get the code to the golf game?


Excellent questions Steve. Better developer documentation is high up on the todo list, hoping to get on to that next week.

Until then, here’s the “zpt” tracking file that we use (you can just drag it directly into the media library and load it into a TargetFinder)

zapbox_controllers_withworld.zpt (26.2 KB)

That will expose the current world map on your device as a target with the identifier “map”, and then actually has all 10 possible controllers in it too, called “A_Left”, “Z_Right”, and everything in between (Z being the print-at-home set). We’ve yet to fully work out how to expose the “paired” controllers through to the content API, so our content generally just locks onto the first controller that it sees. I’ll update the flower and button demo to do that now and share it here.

The golf code is pretty complex (the physics is all in Javascript for example) and there are some assets that we purchased with licenses that prevent us redistributing them as assets (which is effectively what we’d be doing if we shared the project).

The Xylophone experience is being built with the intention of being shared; we made all the assets in-house so we can share it, and it’s going to be a relatively minimal example of TriggerRegion, but with some interesting extension possibilities. Hoping to finish that up next week.


And here’s the updated “Flower and Button” demo:

FlowerAndButton-Beta2.zpp (1.2 MB)

I’ve switched to the target file above and updated the code to use the world map from the device for the button, and to lock the flower onto the first controller that is seen. I also made the button bigger. Bigger button = more fun!

Let us know how you get on, and hopefully we’ll soon have the Xylophone demo and doc updates ready to share too.

Just received my ZapBox, can't scan codes
iOS - Can't Scan Preview Codes

ok so I was playing with the flower in Zapworks studio. When I play the animations of the flower closing when it gets to the end Zapworks studio stopped working error.


Thanks for the bug report. It works for me here on OS X, I can’t see anything weird with the POD file that might cause this, but I’ll get our support team to look into it more next week.

ps: I’ve also changed the topic title as we’re going to link to it from a Kickstarter update.


Thanks for sharing the code @simon.

I reviewed ZapWorks Studio tutorial videos and built some basic stuff. With that understanding, I tried importing zapbox_controllers_withworld.zpt into my media library and I just see a black 2d zapbox logo appearing on my canvas. Is that expected?

However, I am able to open the FlowerandButton.zpp file and play animation and learnt a few things. Thanks for that.

Please bridge the gap in my understanding to build ZapBox compatible MR. Solid docs would get a high-five!


Yes, that’s expected if you drag it from the media library into the hierarchy. The Studio UI doesn’t really cope with target files that have multiple “targets” in them at the moment (although we do have a concept of attachment points in Studio which will take care of this in future).

For now instead of dragging it into the hierarchy (which under-the-hood ends up as a wrapper around a TargetFinder object), just keep it in the Media Library list.

The FlowerAndButton provides the best example of how we deal with this for now - make some fake “simulation” groups in the hierarchy for the stuff you want on different targets (eg one for the world map and one for a controller), make them relative to Z.Camera and positioned somewhere like [0,0,-3]. Then add a child group underneath them to act as the parent group for the actual content you want in those different places. That lets you preview the content somewhere reasonable in the Studio view, but also allows you to easily put the content where it should be at runtime by just setting the content parent group’s relativeTo property in a script.

Add a blank script node to your hierarchy, and in it construct a Z.TargetFinder with the zpt media file (you can drag it into the code view to fill in the symbol.mediaFiles.zapbox_controllers[...] path). Add handlers for the “newinstance” event on the TargetFinder, and in the handler you can determine which of the targets it is (using the identifier() function), and make the appropriate child group relativeTo the instance.

The FlowerAndButton demo does all this in the “functionality” script node at the top of the hierarchy, which is quite well commented. I hope that’s enough to get you going for now, good luck!

…and we’ll keep working on those docs to earn that high-five!


    I watched the tutorial and got the GOLF demo to load, but the "course" is floating several feet off of the floor, and my "putter" is showing just above it.  I cannot actually play with it displaying this way.  I was thinking that after I discover all of my world points and then get ready to build, I could hold the phone farther away from the world points and then press build.
   I will need to try that next time, but does anyone else have ideas on how I can get the "course" to display at floor level, so the "putter" has room to move


Hello simon,

Is there a tutorial to recreate this “Flower and Button” demo or another one?

I would like to create my own project using my ZapBox ! :slight_smile:



Hi All,

Just letting you know that the TriggerRegion documentation is now live -

This combined with the FlowerAndButton-Beta2.zpp should help paint a picture as to how ZapBox experiences are created in ZapWorks Studio.

@loick.depret1 we have a tutorial on general MR project setup in Studio here - Turning an AR project into a MR (ZapBox) experience




I’m looking at using both controllers with 2 different 3d items. In you post here you have the names of A_Left and Z_Right. I understand the a-z part and in your demo it just uses the first controller.
So do I have to lock it to my Kit (I have A,B and Z)? Or make one for each kit?
How do I set it up for all Left controller are one item and all Right are other?



Hi Steve,

The xylophone demo provides another example that might be more appropriate for your use case - that just assumes any “newinstance” that is not called “map” is a controller, and puts a mallet on it. Playing xylophone with 4 controllers is pretty fun :slight_smile:

If you want a different thing on “left” vs “right” you could just see if the string contains “Left” or “Right” using something like:

if(instance.identifier().indexOf("Left") > -1) {
// it's a left controller

We haven’t fully implemented the controller pairing process yet so this is a stop-gap solution. Eventually the plan is by default the app will only report the set of controllers it has been paired with, and will name them consistently (ie just “leftcontroller” or something).



Hey Simon,
I’m working to recreate the flower button project in order to better understand what coding is needed for zapbox projects. Can you explain the reason for the trigger plane to me?


Hi Molly,

A TriggerRegion node will only emit events for Z.Object nodes that have the same tag as its triggerTag property. In the flower button project, the plane is acting as the Z.Object node.

More information on TriggerRegions can be found here in our documentation -



Thanks for getting back so quickly. That definitely helps. I guess I’m still just struggling to understand the choice of sizing between the trigger region and the size of the flower symbol compared to the size of the trigger plane. I would think that the flower and trigger plane would need to be the same size so that when the “flower” or controller hit the button it would make the animation play. Yet when I tried that my flower was no longer tracking with my controller. Like I said, I’m still very new to this and just trying to figure out why things are just so. If you could shed some light on this I’d greatly appreciate it!


Hey Molly,

The size of the trigger plane has no impact, it’s only the center position that is used in the detection. When the center point of the plane begins to enter any part of the TriggerRegion, that’s when the ‘triggerenter’ event will be fired and so on.

The position of the plane within the flower will determine when the trigger events will begin to fire. You can put it right at the top of the flower to have it trigger as soon as the flower starts to enter the TriggerRegion or you can put it in the middle of the flower meaning the flower will have to enter further into the TriggerRegion to fire events.

It’s a tricky concept to discuss in words but hopefully this has helped.



This helps a ton. Thank you!