OpenReality Tutorial

1. What OpenReality Is

OpenReality is built around a runtime-driven project model. Instead of writing interface code first, you create a structured project made of scenes, entities, variables, and commands. The runtime engine reads that structure and turns it into a working app experience.

At a high level, OpenReality combines four capabilities:

1. Visual project editing
2. Runtime interaction and preview
3. Remote device testing
4. Xcode project export

This makes it suitable for fast prototyping, interaction design, and early-stage app production.

2. Who It Is For

OpenReality is designed for:

• Designers building interactive app prototypes
• Creators exploring spatial and multi-platform experiences
• Developers who want to move quickly from concept to working app structure
• Teams validating interface flows before full engineering implementation

If you want to iterate on Apple platform experiences without starting from a blank codebase, OpenReality is a strong fit.

3. What You Need Before Starting

Before using OpenReality, prepare the following:

• A Mac with Xcode installed
• The OpenReality.xcodeproj project opened successfully in Xcode
• An iPhone, iPad, or Apple Vision Pro if you want remote testing
• Local network access shared by your Mac and test devices

For a first-time walkthrough, macOS alone is enough.

4. Launching OpenReality

Open OpenReality.xcodeproj in Xcode, choose the OpenReality scheme, and run the app.

Behavior depends on platform:

• On macOS, OpenReality launches as the full editor
• On iOS, it mainly acts as a runtime target for remote sessions
• On visionOS, it supports both windowed and immersive runtime modes

For the best first experience, start on macOS.

5. Your First Look at the App

When OpenReality launches on macOS, you begin on the home screen. This is the entry point for:

• Creating a new project
• Opening an existing project
• Accessing documentation or tutorial links

For this tutorial, create a new project.

6. Creating Your First Project

Select Create Project and fill in the project setup form.

You will define:

• Project name
• Organization name
• Supported platforms
• App icon

OpenReality generates a bundle identifier from your project and organization names.

Recommended first project settings

• Keep macOS enabled so you can edit and run locally
• Enable iOS or visionOS if you plan to test on devices later
• Choose a simple project name such as HelloOpenReality

When the project is created, OpenReality opens the editor.

7. Understanding the Editor Layout

The editor is divided into four main areas.

Hierarchy

The left panel manages project structure. Use it to:

• Create scenes
• Rename, duplicate, or delete scenes
• Set the entry scene
• Navigate the current project structure

Scene

The center area shows the content of the currently active scene.

Component

The right panel is used to attach components or behavior capabilities to the selected entity.

Properties

The bottom panel shows editable properties for the currently selected object, including scenes, entities, modules, variables, and commands.

Toolbar

The top toolbar includes the core actions you will use most often:

• Save
• Run
• Add
• Project settings
• Export to Xcode

Understanding these areas is the foundation of working effectively in OpenReality.

8. The Five Core Concepts

Before building anything, learn the five concepts that define every OpenReality project.

Project

A project is the full application container. It includes app information, scenes, variables, and commands.

Scene

A scene is a top-level screen or space. A project can have multiple scenes, but only one entry scene.

Entity

An entity is a structured node inside a scene. It can hold modules, modifiers, components, and 3D content.

Variable

A variable stores runtime data such as text, numbers, booleans, colors, images, video, or audio.

Command

A command defines behavior. Commands can switch scenes, update variables, run logic, access device capabilities, and control 3D content.

Once these five concepts are clear, the rest of the workflow becomes much easier.

9. Creating Your First Scene

A new project usually starts empty, so the first thing you need is a scene.

Create a scene and name it Home.

Then set Home as the entry scene.

The entry scene is the first scene shown when the project runs. If the wrong entry scene is set, your app may open to the wrong content or appear blank.

10. Creating Your First Entity

Scenes do not display content by themselves. Content is placed inside entities.

Create a new entity inside the Home scene.

An entity is the basic editable node that holds structure and behavior. It is the container that your scene content will live inside.

Once the entity exists, you can begin adding modules to it.

11. Building Your First Static Interface

For your first interface, build a simple welcome screen.

Inside the Home scene:

1. Create one entity
2. Add a VStack module
3. Add a Text module with the content Hello OpenReality
4. Add a Button module with the label Start

This gives you a minimal static interface with text and a button.

At this stage, the button does not do anything yet. The goal here is simply to learn the basic scene-to-entity-to-module workflow.

12. What Modules Are

Modules are the visible building blocks of content inside an entity.

Examples include:

• Text
• Button
• Image
• VStack
• HStack
• ZStack
• ScrollView
• Map
• VideoPlayer
• NavigationStack

Each module exposes parameters such as text content, size, style, layout, options, or bindings.

From a user perspective, modules are the content pieces you place into scenes. From a system perspective, they are structured runtime definitions that the engine knows how to render.

13. Using the Properties Panel

The Properties panel changes based on what you select.

For example:

• Selecting a scene shows scene-level settings
• Selecting an entity shows entity-level state and structure
• Selecting a Text module shows content, font, alignment, and display options
• Selecting a variable shows its type and value
• Selecting a command shows its steps and execution settings

The workflow is simple:

1. Select the object you want to edit
2. Adjust its details in the Properties panel

This is how most editing in OpenReality works.

14. Adding a Variable

Now it is time to make the project dynamic.

Create a new variable:

• Name: message
• Type: String
• Default value: Welcome to OpenReality

Next, select your text module and bind its content to the message variable.

Now the text is no longer hardcoded. It is driven by runtime data.

This is the point where your project begins to act like a real application instead of a static layout.

15. What Variables Are Used For

Variables let your app respond to state changes.

Common uses include:

• Changing displayed text
• Tracking progress
• Showing or hiding content
• Storing user input
• Passing data between scenes
• Holding image, video, or audio content
• Feeding commands and runtime logic

Variables are shared runtime state. They are one of the most important parts of OpenReality once your project moves beyond static screens.

16. Adding a Second Scene

Create a second scene and name it Detail.

This will be the destination scene when your button is pressed.

Inside the Detail scene, create one entity and add:

• A Text module with the content Detail
• A second Text module bound to the message variable

Now your project has two scenes:

• Home
• Detail

The next step is connecting them with a command.

17. Creating Your First Command

Create a command named GoToDetail.

Add two steps to the command:

1. Set the message variable to You arrived from Home
2. Open the Detail scene

This command now defines a complete behavior sequence:

• First update runtime state
• Then change the active scene

Commands can contain one step or many steps. This is what makes them powerful.

18. Binding the Button to the Command

Select the button in the Home scene and bind it to the GoToDetail command.

When the button is pressed during runtime, the command will execute.

At this point, your first interactive prototype is complete.

19. Running the Project Locally

Use the Run button in the toolbar to start the project locally on macOS.

When it runs, verify the following:

• The Home scene opens first
• The welcome text appears correctly
• The button responds when clicked
• Pressing the button switches to the Detail scene
• The detail scene shows the updated message variable

If all of this works, you have successfully built a complete scene-based interaction flow in OpenReality.

20. What Just Happened

It is worth pausing to understand what you built.

Your project now includes:

• A project container
• Two scenes
• Multiple entities
• UI modules
• One runtime variable
• One command with two steps
• A working scene transition

This is the core OpenReality loop in action.

You are no longer editing static content. You are building a runtime-driven app structure.

21. Understanding Commands More Deeply

Commands are not limited to scene switching and variable updates.

OpenReality commands can also support:

• Conditional logic
• Comparison steps
• Loops and repeated execution
• Math operations
• Text concatenation
• Clipboard actions
• URL opening
• Sharing
• Audio recording
• Photo capture
• Location and sensor access
• Speech recognition
• AI actions
• 3D transformation and animation control

This means commands are the behavioral layer of OpenReality.

As your projects grow, commands become the main tool for defining what the app actually does.

22. The Best Way to Learn Commands

The best way to learn commands is incrementally.

Start with:

• Open Scene
• Set Variable

Then move to:

• Run Command
• If
• Equal / Greater Than / Less Than
• Add / Subtract / Multiply / Divide
• Repeat or loop-based commands

Once you understand those, you can explore device and media actions.

Do not try to use advanced runtime actions before your basic scene and variable logic is already stable.

23. Saving Your Work

Use the Save button regularly.

OpenReality stores your project as structured data. Saving ensures that your scenes, entities, variables, commands, and app settings are written to the project storage.

Good practice:

• Save after creating scenes
• Save after binding variables
• Save after building commands
• Save before exporting
• Save before testing on another device

Frequent saves make iteration safer and more predictable.

24. Remote Testing on iPhone or Apple Vision Pro

Once local runtime works, you can test remotely.

Basic remote workflow

1. Open OpenReality on the target device
2. Make sure the device is discoverable
3. Keep the Mac and device on the same local network
4. In the toolbar run area, select the correct platform
5. Choose the discovered device
6. Complete pairing if required
7. Press Run

The full project is sent to the device, where the runtime engine executes it independently.

This is ideal for checking:

• Real device input behavior
• Mobile layouts
• Sensor-related interactions
• Spatial and immersive experiences on visionOS

25. First-Time Pairing

If this is your first remote session, pairing may be required.

Depending on the target platform, OpenReality may display a pairing code or QR-based confirmation flow. This confirms that the Mac is connecting to the intended device.

If a device does not appear, check:

• Both devices are on the same network
• OpenReality is running on the target device
• The device is set to discoverable mode
• You selected the correct target platform in the editor

26. Working with visionOS

visionOS projects may run in either a windowed context or an immersive context.

If your project includes 3D scenes, be aware of:

• Whether the current scene is a UI scene or a 3D scene
• Whether the experience should stay windowed or move into immersive space
• Whether scene transitions change the runtime environment

For visionOS content, always validate important interactions on the actual target environment whenever possible.

27. Getting Started with 3D Content

OpenReality supports 3D scene content as well as traditional UI scenes.

For your first 3D experiment:

1. Create a new 3D scene
2. Add an entity
3. Configure a 3D model source
4. Start with a primitive shape such as:
   • Box
   • Sphere
   • Cylinder
5. Adjust material settings:
   • Base color
   • Metallic
   • Roughness
   • Opacity

Once the object appears correctly, you can begin using commands to move, rotate, scale, hide, or animate it.

The best approach is to keep your first 3D scene extremely simple.

28. When to Use UI Scenes vs 3D Scenes

Use UI scenes when you want to build:

• Menus
• Flows
• Forms
• Information views
• Navigation-based app structures

Use 3D scenes when you want to build:

• Object presentations
• Spatial experiences
• Animated environments
• Immersive or model-driven interactions

Most first projects should begin with UI scenes. Add 3D scenes once your structure and logic are already clear.

29. Exporting to Xcode

When your prototype is ready to move forward, choose Export to Xcode.

The export process creates a standalone Xcode project that includes:

• A generated app entry point
• Embedded project runtime code
• A snapshot of your current OpenReality project
• Resources such as app icon and app settings
• Platform configuration for supported targets

This gives you a real engineering starting point for continued development.

30. When to Export

Export when:

• Your prototype structure is stable
• The main scenes and flows are already defined
• You need deeper native customization
• You are ready to continue in a traditional Xcode workflow
• You want to turn the prototype into a real app project

Do not export too early. OpenReality is most valuable during the fast iteration stage.

31. Recommended Learning Path

To build confidence quickly, follow this order:

1. Create a single static scene
2. Build a two-scene flow
3. Add a variable and bind it to content
4. Use a command to modify that variable
5. Add basic logic conditions
6. Try a simple 3D scene
7. Test remotely on iPhone or visionOS
8. Export to Xcode

This order keeps complexity under control and makes debugging much easier.

32. Common Beginner Mistakes

Nothing appears when the project runs

Check whether the correct entry scene is set.

A button does not do anything

Check whether it is actually bound to a command.

The text never changes

Check whether the text module is bound to a variable, instead of using fixed content.

The wrong scene opens

Check scene names and command targets.

A remote device is not visible

Check local network access, discoverability, and target platform selection.

Export fails or creates an unusable project

Check your project name, bundle identifier, destination folder, and save state.

33. Best Practices

To stay efficient as projects grow, follow these habits:

• Use clear scene names
• Keep entity structure organized
• Name variables by purpose, not by type
• Keep commands small and readable
• Test often in local runtime
• Only move to remote testing after local logic works
• Save before major changes
• Export only after the prototype stabilizes

OpenReality becomes much easier to manage when the project model stays clean.

34. What to Build Next

After completing this tutorial, try one of these next exercises:

• A simple settings screen with toggle variables
• A step-based onboarding flow across three scenes
• A gallery with image variables
• A small data-driven dashboard using numbers and commands
• A basic 3D object scene with transform commands
• A visionOS-first experience with a UI scene and a 3D scene

Each one builds naturally on what you have already learned.

35. Final Notes

OpenReality is most powerful when you stop thinking of it as a static editor and start thinking of it as a visual app runtime system.

You are not only placing interface pieces on a canvas. You are defining:

• structure
• state
• behavior
• execution flow
• multi-platform presentation

That is what makes OpenReality useful for serious prototype creation and early product development.

36. Quick Start Summary

If you want the shortest possible first path, do this:

1. Create a project
2. Add a Home scene
3. Set Home as entry
4. Add one entity
5. Add a Text and a Button
6. Create a string variable
7. Bind the text to that variable
8. Create a second scene
9. Create a command to update the variable and open the second scene
10. Bind the button to the command
11. Run the project
12. Export when ready

That is the first complete OpenReality workflow.

37. Next Step

Continue to:

• build more scenes
• add more variables
• create richer commands
• test on devices
• explore 3D content
• export to Xcode when your structure is ready

OpenReality is designed to make that progression fast, visual, and practical.