Visual Scripting - Introduction

[Ane 1213]

Game objects

In the Ylands Editor you will encounter two basic types of objects that you can place into the scene and will help you create your own level / scenario / game. Those are Entities and Game logics. Both are very important, and by having a closer look at them, we will show you how they can be useful to you.

Entities

These are objects you normally see in the game when you play. It can be a tree, a building block, an animal or an NPC character. When you place them into the scene inside the Editor and then play this custom level, all those objects will behave the same way as you are used to in any other Ylands game. You will be able to cut down trees, kill animals that will run around as usual, and so on. In general, entities are objects that create the environment of your level.

Game logics

These are special objects that are visible only in the Editor and help you control your game. For example, the Trigger zone is an object that marks certain area, and when some player enters it or leaves it, it can perform various actions. Game logics are invisible when the level is being played, but they still react to players or events, and perform what they are designed to do.

Object selection and properties

Both Entities and Game logics can be, when placed into the scene, edited and adjusted. The object properties panel can be opened by simply double-clicking any object or by selecting it and clicking on the Object properties button in the Object selection panel. Depending on the object you are editing, you will be shown parameters that you can change. For example, when editing a tree, you will be able to modify its color or hitpoints, or choose to make it indestructible. Or, if the object you are editing is a door, you can select if it's locked or wide open.

Some Game logics, like Trigger zones, can't change their color or can't be made indestructible, since the player will never see them while playing or be able to focus them. But you can change their size or shape and modify what type of objects are going to trigger them.

 

                           Object selection panel                                                                                                   Object properties panel

                                                                        

 

Visual scripting

The best thing about Game logics and Entities is that they are able to interact with each other. You can place a door near a Trigger zone and make the door to be unlocked when the player walks through the Trigger zone. Or you can replace the Trigger zone with a lever and unlock the door when the player pulls the lever's handle. Or the door can be unlocked only when the player enters the Trigger zone with some specific item in their inventory. The possibilities are endless.

The thing that glues Entities and Game logics together is the Visual scripting.

 

---

Visual scripting basics

Visual scripting is a simple but powerful tool for creating custom games. Scripting is object oriented,  and its underlying code is based on Java Script, which will be possible to edit directly in the future. Because of this, we will try to adhere to similar conventions.

The visual scripting code can be attached to any object in the game, which means that you can add a custom script to both Entities and Game logics to make them behave the way you want. To start scripting, double-click on some object while holding SHIFT, or select it first and then click on Edit script in the Object selection panel.

Scripts are assembled from "script tiles" (or just tiles), which can serve various purposes. Scripting itself is performed by looking for script tiles that contain the desired function from the menu on the left, and then dragging those pieces of code to the area on the right, where those pieces can be assembled into functioning code. Let's have a closer look on what types of tiles you may encounter.

Script tiles

The visual scripting code is composed from script tiles. There are three basic types of tiles: events, instructions and literals. Tiles can be snapped together to create a sequence, but sequences are valid only when they start with an event tile, otherwise it won't be executed. Also, lonely tiles that are not part of any valid sequences are not executed either. 

For example - doors, when opened by players, will execute On Open event. So, if the door entity has a script and in this script there are instructions attached to On Open event, the code (tiles) under it will execute every time a player opens this door. If the code sequence doesn't include the On Open event tile, the game wouldn't know when this sequence is supposed to be executed, and it never would.

• Tile - One piece of visual scripting code
  • Event - Special tiles, serving as anchor for instruction blocks. Each Entity and Game logic object has a specific set of events. Just like with Object properties, there was no sense for the Trigger zone to have the option to change its color, there is no sense for it to have for example On Open event available. These will be available only for door-like objects. On the other hand, Trigger zone will have events On Trigger Enter and On Trigger Exit, which would make no sense on doors.
  • Instruction - Command tiles performing various functions. They can be attached to other tiles. Most of the tiles are instructions and their functions will be explained separately.
  • Literal - Tiles that can be placed inside instruction tiles as an input. They can contain texts, boolean values (true / false), references to specific entities in the scene etc.

• Sequence - An assembly of tiles.

                   

           

 

 

Working with tiles

• New tiles are dragged from the left panel to the working area on the right.
• To quickly search for a desired tile, the search bar can be used.
• Tiles can be snapped / unsnapped together via mouse dragging.
• Literals are inserted in instruction tiles and usually serve as input value for that instruction.
• Event tiles can be placed freely in the canvas and serve as starting point of a sequence.
• Already existing tiles can be duplicated by holding CTR while dragging.
• To pull a single tile from a sequence, hold SHIFT while dragging.
• For easy navigation through complex script, use key F to cycle through top-level stacks.

 

 Example - block manipulation

---

Examples

Scripted game logic

In a simple scene, we have a wall with a torch and a trigger zone. We want the torch to react to the player's presence, so we will set up a trigger zone that upon entering will lit the torch, and after leaving it, the torch will be extinguished.

After placing the trigger zone into the level and opening the script editor (double-click on the trigger zone while holding shift), specific tiles for both actions (Light and Extinguish) can be found in the Entities -> Actions category. For those actions to be executed, they have to be attached to corresponding events On Trigger Enter and On Trigger Leave, which can be found in the Events category. To select a target for an instruction, use the eyedropper in the entity literal, which will then allow you to pick an entity from the scene.

 

 Example - trigger zone

Scripted entity

Scripts on entities work in the same manner as on game logics. After opening the script editor, a list of appropriate events can be used to execute various instructions. In this scene, we want a lever to open and close doors. So we will edit the lever script and add the Open instruction to On Switch On event, and Close instruction to On Switch Off event. Both events can be found again in the Events category and both instructions in the Entities -> Actions.

 

 Example - entity events

Further examples

To have a look at the Visual scripting in place, check the official games developed by the Ylands team, available at the Ylands Workshop:

• Sky Arena

• Racing Track

• Adventure

 

[Miguel Preguisa 443]

A whole new section of the forum, I like it  I didn't know about either of the usages of holding Shift, so that will make the scripting a little bit easier. I hope more official tutorials will follow! 

[Ane 1213]

8 minutes ago, Miguel Preguisa said:

I hope more official tutorials will follow! 

That's the plan!

[RedEagle_P1. 905]

Hmm, I am gonna have to video that sometime

 

[drseito 11]

Given the importance of variables, can we get a quick primer on how to use them?  For example, it is not clear how the variable scope (local vs global) works in a context of visual scripting.  Can we only use global storage, or do we also have local variables?

[Indomitus 388]

6 hours ago, Seito-7f815597a5e33528 said:

Given the importance of variables, can we get a quick primer on how to use them?  For example, it is not clear how the variable scope (local vs global) works in a context of visual scripting.  Can we only use global storage, or do we also have local variables?

I've been able to identify 3 different scopes so far:

1. Global - accessible from anywhere in the scenario, but only if defined in a Global Storage or Entity Storage

2. Object Local - if it's defined within an object, it can be used anywhere inside it, but not accessed from any other object.  (this obviously doesn't include Global Storage or Entity Storage)

3. Procedural level - the values passed into a sequence of code, for example, can only be used inside that sequence.  The only way to use it somewhere else is to pass it as a value to another command, or to assign it to a variable at a higher level.  Also, the tiles for these apparently will not pass back and forth between different code sequences.  They seem to be locked to the specific sequence, even if the name is the same.  For example, in a Trigger Zone, you get a Trigger Object in both the "On Trigger Enter" and "On Trigger Exit" events but you can't grab a Trigger Object tile from one and use it in the other.  I had a code error because of that a few days ago, and it took me a long time to find the problem.  I had copied a large block with one of them in it.

[drseito 11]

Thanks.  Looking forward to some official tutorials soon...

Edited September 8, 2018 by Seito-7f815597a5e33528

[V-Alfred 367]

awesome! Happy MeGic guys!

*MeGic is gaMe loGic, we need catchy name for that *

[RedEagle_P1. 905]

For those who like this stuff in video: 

 

 

[RedEagle_P1. 905]

@Ane

Dont forget to add the video into the topic intro above

Edited October 8, 2018 by RedEagle_P1.

[Sarah-9f0c7b8d5e239d91 5]

Hi I love this game and want to learn how to script. I have done the above tutorial but when i go to see the further examples by the ylands team.. it  says creation blocked..and indeed the games are locked Is this by accident or design?

[Bob Salvador 82]

it's design because it was old saves before 1.0

[Sarah-9f0c7b8d5e239d91 5]

Ah yes of course thanks...I must be patient...It doesn't look like we can open an unprotected game example in the editor anyway.

Edited December 15, 2019 by Sarah-9f0c7b8d5e239d91

[Igor Q. 519]

3 hours ago, Sarah-9f0c7b8d5e239d91 said:

Ah yes of course thanks...I must be patient...It doesn't look like we can open an unprotected game example in the editor anyway.

Certain games or file compositions will be available if they are unprotected.

If you are looking to learn the editor (and don't want to suffer learning alone) I suggest you join a community such as P1, World of Dreams, 3HT designs, Kysen's channel or try to get into contact with some of the good scripters out there such as me or @Indomitus

[Sarah-9f0c7b8d5e239d91 5]

Thanks will do that.

[RedEagle_P1. 905]

You can join us here: https://discord.gg/GSVbPNj

[Sarah-9f0c7b8d5e239d91 5]

Yes I'm signed up to the P1 academy now ^^ thx

[Mrs_faroe 0]

Hey :) Is it still possible to chose from premade games in editor to learn more about visual scripting? :)

[Adam Snellgrove 1451]

On 4/11/2020 at 9:51 PM, Mrs_faroe said:

Hey Is it still possible to chose from premade games in editor to learn more about visual scripting?

Yep, there are quite a few templates in the Editor ?