Welcome to Vylocity!
But before we jump into the first official VyScript scripting tutorial, it's important to get a basic understanding of how to create and manage projects, as well as use the Vylocity IDE in general.
In order to create and manage a project on Vylocity, simply visit http://vylocity.com/ide/
. You can also get to this page from the main website's top navigation bar using the
Once at the IDE start page you will see a number of text boxes. If you have an account, the Page Path
row will have a text box where you can enter a name to identify your project and get to the IDE for that project using a web link. Usually this will just be the game's name without any symbols or spaces. If you do not have an account then this will be automatically generated and after the project has been created you will need to remember or store the link so that you can get back to it in the future. The rest of the boxes are pretty self explanatory.
All of the text boxes can be left blank and changed later, but for the purposes of these tutorials we will be naming the project First Project
. So enter FirstProject
into the first box if you have an account and First Project
into the second.
Once all the information is entered, hit the button.
After a short delay you should be taken to a new page. This page is the IDE application for your new project. This application can be used for everything you need to make and maintain your project's source. You can return to this page from any internet-connected device at any time to continue working on your project (of course if you made the project with an account you'll have to log in first).
Before we start creating some files and learning how to use some of the tools, let's make sure we know how to leave the project and return to it without using the direct link. If you are not logged into a Vylocity account, you can skip this step (but be sure to remember it for the future).
At the top of the page is a blue bar and on the left side of that bar are some menu buttons. These buttons can be used to do various things in the project just like any normal computer application.
Click on the menu button and a new drop down menu should appear. Go to the bottom of the menu and click on the Exit
option to exit the project and return to the IDE starter page. It may ask if you are sure you want to leave (this is so you don't accidentally leave without saving any changes you made), just accept and exit.
This page should be familiar, but now at the bottom of the page your project should be listed (you have to be logged into a Vylocity account to see any projects listed). Click on the First Project
listing and let's return back to the project's IDE so we can start creating some files and learn some of the basics of some of the tools.
Now that we are back in the project's IDE, let's create our project's first file. The first page you see when creating a new project is the New File
page. In order to create a new file for the project we just have to simply enter the name of the file and then select the type of file we want. Every project needs a code file, so enter main
into the text box labeled File Name
and click on the Code
Our new code file will open in the code editor for us. Each line has a number and each line can be selected and you can enter code into it just like a normal text box. However, the text we enter will take on a specific syntax in order for us to tell the builder what we want to happen (a script). The code editor will automatically highlight and change colors of certain words and phrases as we type to help us understand what is happening. We wont be creating any scripts in this specific tutorial, but basically every tutorial after this one will be focusing on scripts.
Even though we haven't actually made anything for our project, every project can be built and ran right out of the gate using all the defaults of a Vylocity project.
After we make changes to our project and want to play test or see our changes in things like the map editor and interface editor, we have to build the project. In order to build we can go up to the menu bar at the top of the page and select and then Build
or we can hold the Ctrl
key and press the K
Now in order to run the game we can once again go up to and then Run
or we can hold the Ctrl
key and press the R
A window should pop up (if one does not, be sure to allow vylocity.com to display pop ups). This is our game, but because we have not created anything yet, the screen will be black and nothing will be happening.
Close the game window (the popup window) and let's learn a bit more about the code editor and builder errors. In the main
code file enter the following code:
This is some text!
Build the project by going up to and Build
or by holding the Ctrl
key and pressing the K
After the build loading screen goes away, a red window should appear. This red window is a list of the build errors. In order for our project to build, there cannot be any errors, so we will have to fix each error and build again. Each line in the red box is a different error. In this case we should only have one error which looks something like main:2: Invalid object type (Thisissometext!)
. This text format is the file name, the line number, the error itself, and then the specific text involved. This exact error is because the builder is not expecting random text out of nowhere so it tried to interprete what we wrote the best it could and was unable to do so because the text broke a syntax rule. We can click on the error to jump to the location in the code file so we can fix it.
We wont go over specifically why this code throws an error since we aren't yet learning VyScript itself, but what we can do is comment
out the text so that the builder ignores it. At the start of the text add two forward slashes ( /
) and everything on that line after the two slashes will turn into a code comment
and be ignored by the builder when we build the project. Below is an example of how it should look.
// This is some text!
Comments are a good way for us to add custom text to our code files to make notes, remind us what certain code does, let other people know what specific code does, or maybe temporarily remove something we plan to add back later when we need it again.
While the two forward slashes will only comment
things after it on the same line, we can comment
across multiple lines using /*
where our commented text will be between these two groups of symbols. Below is some example code of a multi-line comment
(do not put the comment
into your project).
This is a
Now that our This is some text!
text has become a comment
, we should be able to build again and get rid of the error. Go ahead and do that.
We haven't had to save a file yet because building automatically saves any changed files for us, but saving without building is important. We only want to build if we need to run the game to see our changes or if see specific changes in the map editor or interface editors.
There are quite a few ways to save a file. You can right-click on the file's tab at the top of the IDE and select the Save
option, you can right-click on the file in the files list to the left of the IDE and select the Save
option, you can go up to the menu and select Save
, or you can hold the Ctrl
key and press the S
Go ahead and delete all the text in our main
code file so we can start from fresh in the next tutorial where we will start to learn VyScript and then save the file using one of the above mentioned methods.
In order for us to have an actual game, there needs to be some type of visual representation. This is done by using Vylocity icons, which are images with data attached to them to determine how the icon will be used. We use the icon editor in order to create and modify these icons, as you would in most image or photo editors. We wont go into all of the details, but we will need some icons in order to see some of our upcoming tutorial scripts in action. So we'll learn some of the most basics and create some temporary icons to give future things a visual representation.
We need to create our icon atlas file so we can add some icons to it. There are quite a few ways to make a new file, but the easiest way is to click on the +
button next to our main
file tab toward the top of the page. If you are unable to find the button you can go up to and select New File
(lowercase i) into the File Name
text box and select the box labeled Icon
Our new icons
file should open up in the icon editor. One icon atlas holds many icons. Usually you want related icons in the same icon atlas file. For example, if our game has a "lava level" then we probably want all lava related art assets in the same icon atlas so when the player enters the level they only need to download and access a single file that has all the related assets they will need. Of course you can categorize the assets depending on the project. A smaller project probably doesn't need a whole icon atlas for a specific thing and you might get away with putting all scenery-based assets in a single file. Setup things the way that best fits your project.
On the left side of the icon atlas file is a box titled Icons
. This box is where all of this file's icons will be listed. At the top the box, on the right, is a +
button we can press to add a new icon to the file. Do this and enter tile
in the Icon Name
text box and click the button (or press the enter
key) while leaving everything else the way it is.
You should now see an icon in the icon list called tile
and a box with a grid on it in the middle of the screen. The box in the middle is our icon canvas where we can paint onto the icon. Feel free to mess around and draw on the canvas. Once you are done go up to the menu at the top of the page and select Revert
to return everything to a blank canvas.
Next to the Icons
box is a Tools
box. Under the Tools
box mouse over the different tools to see what they are. Find and select the tool labeled Fill Tool
On the right side of the icon editor is a box titled Color
which has color sliders. Click or move the sliders on the one labeled G
so that you select a green color.
Once you have a green color selected (you can use whatever color you want, this icon will be our main ground icon) click on the icon canvas in the middle of the editor in order to fill the entire thing with our color using the fill tool.
Create a new icon in our current icons
icon atlas file called player
, select a new color and fill the canvas with it. This icon will be used to represent our player character in the following tutorials. Also create a new icon called monster
, select a new color and fill the canvas with it. This icon will be used to represent a monster in the following tutorials.
We'll need a few more icons, so create the following icons and give them each a new color, grass
. These icons will be used as tiles and obstacles in the coming tutorials.
We wont do anything in the other editors for this tutorial, we will talk about them more in the following tutorials. However, we do still need a couple more files for the next tutorial which we will go ahead and create here.
Create a new map file called map
and a new macro file called macros
. When creating the map file it will ask what size the map should be, just leave it at the defaults and click the button.
A map file holds the information for a map, which is what the player in our game will walk around on and interact with things.
A macro file holds the information for our macros, which are commands that are called when certain keys are pressed in our game.
Organization is very important with a project. If you do not properly organize and categorize things, the larger your project gets the harder it can be to navigate and find things. One way to organize is to put files into folders. You can create a folder by going up to the menu and selecting New Folder
or by right-clicking on the files list on the left side of the IDE and selecting the New Folder
Go ahead and create four folders called code
, and macros
You can move files around in the files list by selecting and dragging them. Drag the main
icon file onto the code
folder, the icons
icon atlas file onto the icons
folder, the map
map file onto the maps
folder, and the macros
macro file onto the macros
Build the project or use the Save All
to save everything so it is ready for the next tutorial!
If you followed everything in this tutorial, the source of your project should look something like this: https://vylocity.com/ide/Vylocity/FirstProject/