Tutorial:RGB Cube

This article or section is a Stub. You can help the Resonite Wiki by expanding it.

This is meant as a quick jump into the Entity Component System (Slots/Components) and Protoflux. Over the course of this tutorial you will create a RGB cube from scratch and play around a bit with a few tools.

Note: Clicking in this tutorial refers to hitting the primary action key. (i.e. left mouse button on desktop mode)

Basic Visuals

«In the beginning, there was nothing.
And Frooxius said, ‘Let there be light.’
And there was light.»^{[Citation needed]}

But what help is light if there is nothing to see?

So, equip a Dev Tool, open the context menu, and select Create New..., then double-click Empty Object.

File:Dev Tool Create New.png

File:Create New Empty Object.png

You created an empty Slot - still a bit boring, right?
This is because Slots are just containers for Components and other Slots. They don't do anything on their own. (except having a name, being in a 3D hierarchy and a few other properties)

File:Empty Slot in Inspector.png

Click Attach Component and select the component Assets/Procedural Meshes/BoxMesh. (double clicks!)

File:Slot with BoxMesh.png

You added a component to the slot. They are the actual things you see, hear, touch etc.

But why don't you see the box you just created?
The reason is that while some components do things, some other components just represent data - like a BoxMesh which is just 24 vertices, connected by 12 triangles. There is no instruction telling Resonite to render this mesh.

You can fix this by adding the component Rendering/MeshRenderer. And don't cheat by clicking Setup Renderer!

The MeshRenderer component will tell the engine to actually render a mesh.
Emphasis is on a mesh! You need to specify which one with the Mesh property.
To fill it, first grab the header of the BoxMesh component.

File:Grabbed BoxMesh pointed at Mesh property.png

You are now holding a reference to the mesh which is visualized with a preview of the mesh data. Then point at the Mesh property or the MeshRenderer and let go. (alternative: click while pointing at the property)

File:Rendered Box without material.png

Success, there is something to look at!

But what is this checkerboard pattern?
The answer is simple: Resonite now knows the shape of the object but not what its surface is like. (Is it green like grass? Is it shiny? Does it glow in the dark?)

For a start just add the component Assets/Metarials/PBS_Metallic. Similar to the mesh this component just represents some data.

File:PBS Metallic in default config.png

To put it into the MeshRenderer, just click the Add button under Materials (list): and fill the new entry with a reference to the material. (grab&drop/click!)

File:MeshRenderer with BoxMesh and PBS Metallic.png

This looks very close to the default cube. You could almost touch it - but you can't!

Basic Interaction

Your creation still lacks in the interactive part of the experience.

To be able to physically interact the Physics category of components is a must-have. In this case you must choose one of the Colliders, and which of them matches a box the most if not the BoxCollider?

File:Box with BoxCollider shows laser interaction.png

Your laser now hits the box - that's it. Now that you could interact with it you need to specify how: Attach the component Transform/Interaction/Grabbable. This tells Resonite that anyone can grab this object when their laser or grab sphere touch it and they use their grab action.

You want to change the size of your box while holding it? Enable the Scalable property of the Grabbable and pick it up with two hands! (Desktop: right mouse button to “grab” + Shift + move mouse wheel)

File:Box being grabbed with two hands.png

Editing

A box like this is not very useful. You can't even hit people with it.
You can blame the shape: It's just too fat!

Go to the BoxMesh component and edit the Size property to be [0.1; 0.1; 1].

File:Box that has been slimmed down.png

Changing the size of a box by numbers is a bit lame. This is where you can use the power of Dev Tools: Use secondary action while pointing at the box to select it, open the context menu and select Gizmo Options/MeshRenderer.

File:Box with MeshRenderer gizmos.png

This is one example of the many types of Gizmos that can be interacted with via primary action.
Note that they usually have priority over other colliders, allowing you to interact with Gizmos behind your object!

Have you noticed that the selection visuals don't align with the dimensions of your box visuals?
Take a look at the BoxCollider!

File:BoxCollider with default values.png

It also has a Size. Visualize it by clicking the button Visualize Collider within the BoxCollider component!

File:Box with unmatching BoxCollider visuals.png

Now copy the values from the MeshRenderer to the BoxCollider!

File:Box with matching BoxCollider visuals.png

Ta-da! It matches the visuals again.

For the purpose of this tutorial we will assume we are not happy with the dimensions:

• Change them!
• And make sure that the collider matches the visuals!
• Change it again while matching the collider!
• Do it again!
• And again!
• Do it 100 times!

Okay... That probably is enough. Tedious, right?

So, here are a few tricks that you may have figured out on the way:

• You can copy and paste text via the clipboard of the operating system of your choice. In VR there are usually dedicated keys on your keyboard while on desktop you use the shortcuts Ctrl+C and Ctrl+V.
• You can “Grab & Drop” texts from one text field to another.
• Grabbing the colored icon to the left of a property name and dropping it directly on a property name of a compatible type allows you to copy the full value at once. (a 3-dimensional vector here)
• Even with all those tricks it is tedious work to copy all those values manually. Mistakes are a guarantee!

Simple Data Binding

Introducing: Transform/Drivers/ValueCopy

Configure it like this:

• Source should be a reference to the Size of the BoxMesh. Grab the property name and drop/click it here. (on the input which shows a null value by default!)
• Target should be a reference to the Size of the BoxCollider.

File:ValueCopy from BoxMesh.Size to BoxCollider.Size.png

Now it should do the work for you - all changes to the BoxMesh will be applied to the BoxCollider.

Take a look at the Size property of the BoxCollider:

File:Driven BoxCollider Size.png

Why is it pink?!
This color indicates that a property is driven. If you refuse to use Wiki links, here is the short version:

• It is not an independent value anymore but instead computed from others. (Size of BoxMesh in this case)
• As a side-effect it disables the FrooxEngine magic that communicates values across the network. Everyone computes their own version. (Warning: Links contain quite technical Wiki pages!)

Try to edit the Size of the BoxCollider now!

It doesn't work, right? This makes sense if you consider that this value is not independent anymore. Even assuming that you were temporarily changing it - which you didn't - it would be overwritten by ValueCopy immediately. (Note: the inner workings are slightly different and also a bit more complex.)

This behaviour changs when you enable WriteBack.

Now you can change the Size of either BoxMesh or BoxCollider and the other will change appropriately.

This example shows that there may be many useful components you haven't heard of before and even simple properties may change their behaviour completely.

You may be overwhelmed by how many there are, so take it easy and learn it in your own pace!
At this point a visit of the category Transform/Drivers is recommended. It contains many useful components that are centered around driving values.

It doesn't matter if you just try stuff on your own or if you study the Wiki:
If you are stuck, ask the community! We are happy to share our experience with you.

In fact teaching others or being taught in Resonite is a nice, social experience on its own. More often than not, not only the “student” but also the “teacher” learns something new. (Bonus: There are no exams, you just learn for life!)

If you still have energy you may continue with the next chapter to be introduced to programming in Resonite. Otherwise you can save your box when you grab it, open your Dash Menu, select one of your own directories inside the Inventory and click Save Item.

Don't forget to give your project a proper (Slot) name before saving! (Too late, isn't it? :-P)

If you want to continue and found out that you lost your first project, don't worry: You were actually tricked to create a slightly modified default cube that you can spawn with the Dev Tip via Create New.../3D Model/Box. (They have to come from somewhere!)

Programming

TODO

Notes

Done:

• BoxMesh -> nothing to see here
• MeshRenderer -> still nothing
• Drag&Drop ref into field -> Finally, but checkerboard!
• Material -> Looks OK!

(* Texture (something bright, have it in wiki) -> Nice but can't interact!)

• Component:BoxCollider -> some reaction with laser but still no interaction
• Grabbable -> interactive but a bit large
• Scalable -> but can't stretch
• resize with numbers -> boring
• resize with Dev Tool -> much better, but wait, the interaction is with original box (also: hint at the multitude of Gizmos)
• manually copy values -> Automation?!
• Component:ValueCopy -> better
• The simple way to do the same. (destroy ValueCopy and drag&drop)
• WriteBack
• hint to documentation and asking people

Planned:

• PF: source
• PF: write with input
• PF: PF with random
• PF: create on collision trigger
• PF: drive (flashy images warning)
• PF: T -> Hue ->
• PF: time multiplier
• PF: Packing (create dedicated Slot)
• Refactoring: create parent Slot, drag&drop grabbable component
• Proper naming
• end of tutorial: We failed - it's not a cube!