TheAutopilot (talk | contribs) No edit summary |
→Programming: fix a couple links, since yes displays are a thing but they have no visual, unlike Value displays, etc |
||
Line 200: | Line 200: | ||
[[File:Source with Display.png|thumb|center]] | [[File:Source with Display.png|thumb|center]] | ||
You have now created a [[ProtoFlux:Display|Display]] node which is displaying the value connected to its input directly. Their main use is to test your code since they are only visible when the code is visible. (Also very useful when exploring unknown nodes/code!) | You have now created a [[ProtoFlux:Value Display|Value Display]] node which is displaying the value connected to its input directly. Their main use is to test your code since they are only visible when the code is visible. (Also very useful when exploring unknown nodes/code!) | ||
Change the <code>AlbedoColor</code> with the inspector and observe that the Display node changes output! (Hint: You can click the colored rectangles next to the raw color value to open a color picker!) | Change the <code>AlbedoColor</code> with the inspector and observe that the Display node changes output! (Hint: You can click the colored rectangles next to the raw color value to open a color picker!) | ||
Line 231: | Line 231: | ||
; An orange rectangular input which identifies as <code>Value<colorX></code><br/> | ; An orange rectangular input which identifies as <code>Value<colorX></code><br/> | ||
: This is the value that will be written into the variable targeted by the node. | : This is the value that will be written into the variable targeted by the node. | ||
: Create a [[ProtoFlux: | : Create a [[ProtoFlux:Input|Input]] node the same way you created the Call Input and change it to a proper color! (Default is transparent black: Set <code>Alpha</code> to 1.0 to remove transparency!) | ||
; Two triangle-shaped outputs identified as <code>OnWritten<Continuation></code> and <code>OnFail<Continuation></code><br/> | ; Two triangle-shaped outputs identified as <code>OnWritten<Continuation></code> and <code>OnFail<Continuation></code><br/> | ||
: Once the Write node has done its thing, it chooses one of those outputs to continue with the next node. (usually OnWritten, unless something is wrong like “no variable to write to”) | : Once the Write node has done its thing, it chooses one of those outputs to continue with the next node. (usually OnWritten, unless something is wrong like “no variable to write to”) |
Revision as of 06:17, 11 April 2024
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.
It is assumed that you already know how to navigate your Dash Menu or how to open a Context Menu.
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
.
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)
Click Attach Component
and select the component Assets/Procedural Meshes/BoxMesh
. (double clicks!)
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.
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)
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.
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!)
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?
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)
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]
.
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
.
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!
It also has a Size
. Visualize it by clicking the button Visualize Collider
within the BoxCollider component!
Now copy the values from the MeshRenderer to the BoxCollider!
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
andCtrl+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 theSize
of the BoxMesh. Grab the property name and drop/click it here. (on the input which shows anull
value by default!)Target
should be a reference to theSize
of the BoxCollider.
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:
Why is it pink?!
This color indicates that a property is driven.
If you are afraid of 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 changes when you enable WriteBack
.
Now you can change the Size
of either BoxMesh or BoxCollider and the other will change accordingly.
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 good starting point is the category Transform/Drivers
which 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)
Programming
Only grabbing and scaling becomes boring after a while. Wouldn't it be nicer if your project could actually do something a little more complex?
We could make it spin, snap to other objects or just look creepy.
There are many things we have components for and a lot of things you can do with a combination of them
and if you want to do even more you can create your own logic in ProtoFlux, the visual programming language of Resonite.
So equip your ProtoFlux Tool and start programming!
Oh, you don't know programming? That's fine! This is a tutorial. (Even experienced developers should continue reading to familiarize with the syntax!)
So, for a start, find the AlbedoColor
property of your PBS_Metallic. Then grab the property name with the equipped ProtoFlux Tool and select the context menu Source
.
You have created a Source node which is one of the bridges that connect your code with the World around it.
It allows you to read the value of a property directly.
To demonstrate this, use and hold down primary action on the orange output that shows the tooltip *<colorX>
on your ProtoFlux tool and tap secondary action.
You have now created a Value Display node which is displaying the value connected to its input directly. Their main use is to test your code since they are only visible when the code is visible. (Also very useful when exploring unknown nodes/code!)
Change the AlbedoColor
with the inspector and observe that the Display node changes output! (Hint: You can click the colored rectangles next to the raw color value to open a color picker!)
The Source node also acts as a bridge in the other direction. To do this open the context menu of the ProtoFlux Tool and click Browse nodes
.
You have opened the node browser which you navigate through via double-clicks of your primary action.
Go to the category Actions/Write
ObjectWrite
? ValueWrite
? <T>
or <C,T>
?
This is a bit confusing for the start but you will get there. For now:
- Grab the node browser and create a duplicate of it via the context menu! Put it to the side for later!
- Navigate to the subcategory
ValueWrite<T>
, scroll down until you find the entryValueWrite<colorX>
and double-click it with the ProtoFlux Tool!
You have selected the node type ValueWrite<colorX>
.
Double-click primary with the ProtoFlux Tool while not pointing at things to create one!
On this Write
node you can see multiple inputs (left) and outputs (right) as well as something that looks close to a property:
- A white triangle-shaped input which identifies as
*<ISyncOperation>
when pointing at it - This will trigger the write node when an Impulse comes through.
- Use primary-drag + secondary-click to create a Call Input node that you can use to start execution of an impulse chain!
- An orange rectangular input which identifies as
Value<colorX>
- This is the value that will be written into the variable targeted by the node.
- Create a Input node the same way you created the Call Input and change it to a proper color! (Default is transparent black: Set
Alpha
to 1.0 to remove transparency!) - Two triangle-shaped outputs identified as
OnWritten<Continuation>
andOnFail<Continuation>
- Once the Write node has done its thing, it chooses one of those outputs to continue with the next node. (usually OnWritten, unless something is wrong like “no variable to write to”)
- Use primary-drag + secondary-click again to create an Impulse Display node for each output!
- A “property” called
Variable
- This is the variable this node will write to.
- Set this up by primary-dragging from the output of the Source node to the label or reference input below it! The reference input should now display
ValueSource`1
instead ofnull
.
If you followed all steps your code should now look like this:
Execute it by clicking the Call
button on the Call Input node! The box should now have changed color.
If that didn't happen, check:
- Is the code connected like shown? Is there an arrow between the Source and the Write node when you hover over either?
- Look at the impulse outputs: If the impulse exited via
OnFail
your source may point to a material or Source node you have destroyed already. (e.g. if you had multiple cubes and deleted the wrong one) - Click the arrow button on the source field: If nothing happens it points to an already destroyed material. Otherwise, check if the material is actually used with the MeshRenderer!
- Did you try to change the color to the same color the cube had already? Please change the input to the write node to something where you actually notice the change!
PS: Those are good troubleshooting tips in general. Feel free to look at them even if everything worked on the first try!
So, now you have a color-changing box. How can it be improved?
- You want to assign a random color?
-
- Create a Random Hue ColorX node from the category
Math/Random
! - Connect it to the Write node's
Value
input with primary-drag from its output to the input! (or the other way around!)
- Create a Random Hue ColorX node from the category
- You want to trigger a color change automatically, e.g. when you hit something with the box?
-
- Create the node On Contact Start from the category
Physics/Events
! - Connect its
OnEvent
impulse output with the*
input of the Write node! (primary-drag again...) - Grab the BoxCollider component's title and let go of it while pointing at the
Collider
property of On Contact Start! - Change the BoxCollider's
Type
toActive
to make it actively detect collisions with other colliders!
- Create the node On Contact Start from the category
- You want to play a sound on each color change?
-
- Create the node Play One Shot from the category
Audio
! - Create a connection from the Write node's
OnWritten
output to the*
input of the Play One Shot! - Create an input node for the
Clip
input of the Play One Shot! (Remember: primary-drag + secondary!) - Get/import an audio clip and put it into the audio clip input. (e.g. primary-click with your laser while grabbing)
- If you don't have any at hand, use a Microphone to record a very short sound! (<1s, don't forget to reequip the ProtoFlux tool again!)
- Go to the inspector showing your Box! On the left side (a hierarchical view) grab the item representing your box, open your context menu and select
Reference
! This spawns a Changeable Source node that outputs a reference to your box. - Connect the Changeable Source to the
Root
input of the Play One Shot! This makes sure that the sound comes from the box and not from the code.
- Create the node Play One Shot from the category
You now have a color-changing RGB!!!111 box you can hit people, things and even yourself with. Those are events that happen and then are over again. For those kind of things Impulses are a great choice. (programmer-lingo: imperative programming)
Between those events nothing happens. The box would not show the world it is “RGB”. You could trigger events in regular intervals or even every frame. The changes caused by your code would then be transmitted to the other users.
This approach has problems:
- It causes a lot of network traffic.
- While the FrooxEngine's magic is good at keeping the world in sync for all users it does not come for free.
- A few of your items may work without any problem, but what happens when a dozen users keep a dozen RGB boxes in their hand that update 60 times a second?
- FrooxEngine's magic can't teleport or go faster than light.
- There will always be some network-latency before changes reach the other users.
- Even worse: Network-latency is not a constant. So sometimes updates are bunched together and sometimes there may be a “gap” during which your “animation” appears paused.
Luckily there is another style of ProtoFlux that uses Value/Reference Drives. Programmers would call this “declarative programming” because you ‘declare’ what the result should be but not when (or in this case also: where) it should be calculated. This gives Resonite the option to run it:
- Every frame after all impulse-based ProtoFlux is finished. (There are optimizations in place to avoid calculations if nothing changed.)
- For every user locally. (Remember the segment about drives in #Simple Data Binding!)
The result can be used for smooth animations that all users agree on but also for games where every user sees a different thing.
Enough talking, back to doing: You should have your ProtoFlux Tool still equipped! It's time to spin the color wheel.
- Grab the
AlbedoColor
property of the cube's material! - Open the context menu and select
Drive
! - Create a World Time Float node from the
Time
category and a ColorX Hue fromColors
! - Connect the
Hue
input of the ColorX Hue node to the World Time Float node and its output to the input of the Value Field Drive<colorX> node.
Congratulations, you have now created fancy RGB while using a bunch of new things!
- World Time Float
- This is the number seconds since the Session has been started.
- For experts: The output value is continuously changing which means that the aforementioned optimization will not happen. Your code will always run. (That is no problem, just some random fact!)
- ColorX Hue
- This converts the input in a range from 0 to 1 to a color with that hue. The pattern is conveniently repeated outside that number range. (Hue(0.1)=Hue(-0.9)=Hue(1.1))
- This is a node without any impulse. It is only executed to calculate its output value.
- For experts: In this case the output only depends on the two input values. Not all nodes that look like that are so pure. Some depend on "external" properties like the hierarchy they are in or properties of their inputs. (e.g. Read Dynamic Variable or Get Slot Name)
- Some connectors/connections are blue, some are orange.
- TODO: introduce types (mention at color-coding and PF tool hover in inputs/outputs)
- TODO: objects vs. reference vs. value (World model vs. ProtoFlux)
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
- PF: source
- PF: write with input
- PF: PF with random
- PF: create on collision trigger
- PF: drive
- PF: T -> Hue ->
Planned:
- PF: Type introduction
- PF: Write+Drive combination (RGB-overdrive on hit, suggested problem: Are drives non-interactive?)
- PF: Packing (create dedicated Slot)
- Refactoring: create parent Slot, drag&drop grabbable component, PF slot
- Proper naming
- end of tutorial: We failed - it's not a cube!
Suggestion for self-studies:
- PF: "if not hit active user"
- PF: "time multiplier"