Welcome to Vylocity!

Vylocity is a game creation service that helps game developers easily create web-based games from anywhere and on any device. Vylocity projects are created and managed using the Vylocity IDE (integrated development environment) which consists of multiple tools such as the code editor, the icon editor, the map editor, the interface editor, the macro editor, and the sound editor. Vylocity uses a custom JavaScript-like programming language known as VyScript, which is the most important part of the creation process, so these tutorials will mostly cover how to use it.

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 link.

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 File 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 box.

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 Project and then Build or we can hold the Ctrl key and press the K key.

The builder will go through all of our project's code and check it for errors. If no errors are found, it will turn our VyScript scripts into JavaScript and put everything together with the Vylocity engine so that our game can be played. Because we have not entered any code (hopefully) yet, building should not result in any errors. The builder will also go through any of changed resource files and properly package them along with all project files so that the engine can work with all of the resources while the game is running.

Now in order to run the game we can once again go up to Project and then Run or we can hold the Ctrl key and press the R key.

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 Project and Build or by holding the Ctrl key and pressing the K key.

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 interpret 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 /* and */ 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 multi-line comment */ 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 File menu and select Save, or you can hold the Ctrl key and press the S key.

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 File and select New File.

Type icons (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 Edit 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, dirt, solid, not_solid. 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 File 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 option.

Go ahead and create four folders called code, icons, maps, 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 folder.

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/