About this book

Mobile games have been the recent craze and with so many ways to monetize the popularity of these games, it is no wonder that game developers are excited to get into the market. However, the mobile platforms that are available and their popularity constantly change meaning that developers have to be able to react quickly to the market. ShiVa3D gives developers the power to quickly develop the game once, but deploy to almost every popular mobile platform, which enables them to have greater distribution and a greater opportunity to sell games.

"Learning ShiVa3D Game Development" is a simple, hands-on guide to the key features of the ShiVa3D game engine that will enable you to get up and running with your mobile game ideas. Learning ShiVa3D Game Development will make it possible to easily develop your game once, but publish it to most of the popular mobile platforms.

This book specifically targets the key features of ShiVa3D that will enable you to create games quickly. It will take you through designing game components in the editor and provide detailed explanations for every line of scripting used.

You’ll look at how the modular nature of the editor allows you to do everything from scripting, to complex physics interactions, to special effects with only a few adjustments to pre-configured settings. We will see how to deal with input from the keyboard, mouse, or touchscreen as well as how to add sound effects and music to a game. You will get to actually play your game as you learn to deploy a game to an Android phone. If you are looking for a way to make your game ideas a reality, then this is the book for you.

By the end of this book, you would have learnt everything you need to know to create your own mobile game that can then be deployed just about anywhere.

Publication date:
November 2012


Chapter 1. Getting Started

This chapter will get us through the basics of creating a game. We are going to move fast, as this is just something to get your feet wet. If there are concepts you don't quite understand, take a little more time going over the topic, but also know that most of what we do in this chapter will be covered in more detail. So sit back and enjoy the ride!

By the end of this chapter, we will have created a complete game—it won't do much, but like the chapter says, we are just getting started. We'll learn how to install ShiVa3D and begin a project. Once we get a project going, we will import a model, light the model, and test our game. Not bad for the first chapter!


System requirements

Before we take a look at how to download and install ShiVa3D, it might be a good idea to see if your system will handle it. The minimum requirements for the ShiVa3D editor are as follows:

  • Microsoft Windows XP and above, Mac OS with Parallels

  • Intel Pentium IV 2 GHz or AMD Athlon XP 2600+

  • 512 MB of RAM

  • 3D accelerated graphics card with 64 MB RAM and 1440 x 900 resolution

  • Network interface

In addition to the minimum requirements, the following suggestions will give you the best gaming experience:

  • Intel Core Duo 1.8 GHz or AMD Athlon 64 X2 3600+

  • 1024 MB of RAM

  • Modern 3D accelerated graphics card with 256 MB RAM and 1680 x 1050 resolution

  • Sound card


Downloading ShiVa3D

Head over to http://www.stonetrip.com and get a copy of ShiVa3D Web Edition. Currently, there is a download link on the home page. Once you get to the Download page, enter your email address and click on the Download button. If everything goes right, you will be prompted for a save location—save it in a place that will be easy to find later.

That's it for the download, but you may want to take a second to look around Stonetrip's website. There are links to the documentation, forum, wiki, and news updates. It will be well worth your time to become familiar with the site now since you will be using it frequently.


Installing ShiVa3D

Assuming your computer meets the minimum requirements, installation should be pretty easy. Simply find the installation file that you downloaded and run it. I recommend sticking with the default settings. If you do have issues getting it installed, it is most likely due to a technical problem, so head on over to the forums, and we will be more than glad to lend a helping hand.


The ShiVa editor

Several different applications were installed, if you accepted the default installation choices. The only one we are going to worry about for most of this book is the ShiVa Web Edition editor, so go ahead and open it now. By default, ShiVa opens with a project named Samples loaded. You can tell by looking at the lower right-hand quadrant of the screen in the Data Explorer—the root folder is named Samples, as shown in the following screenshot:

This is actually a nice place to start, because there are all sorts of samples that we can play with. We'll come back to those once we have had a chance to make our own game. We will cover the editor in more detail later, but for now it is important to notice that the default layout has four sections: Attributes Editor, Game Editor, Scene Viewer, and Data Explorer. Each of these sections represents a module within the editor. The Data Explorer window, for example, gives us access to all of the resources that can be used in our project such as materials, models, fonts, and so on.


Creating a project

A project is the way by which we can group games that share the same resources. Of course, for the purpose of this book, we will only be creating a single game, but you could go on to create your own games in this project if you wanted. To create a new project, click on Main | Projects in the upper left-hand corner of the screen. The project window will open, as shown in the following screenshot:

In this window, we can see the Samples project along with its path. The green light next to the name indicates that Samples is the project currently loaded into the editor. If there were other projects listed, the other projects would have red lights besides their names. The steps for creating a new project are as follows:

  1. Click on the Add button to create a new project.

  2. Navigate to the location we want for our project and then right-click in the explorer area and select New | Folder.

  3. Name the folder as IntroToShiva, highlight the folder and click on Select.

  4. The project window will now show our new project has the green light and the Samples project has a red light. Click on the Close button to finish. Notice that the root folder in the Data Context window now says IntroToShiva.

Creating a game

Games are exactly what you would think they are and it's time we created ours. The steps for creating our own games are as follows:

  1. Go to the Game Editor window in the lower left-hand corner and click on Game | Create.

  2. A window will pop up asking for the game name. During the course of this book, we will be creating a game in which the player must fly a spaceship through a tunnel or cave and avoid obstacles; so let's call the game CaveRunner.

  3. Click on the OK button and the bottom half of our editor should look like the following screenshot:

Notice that there is now some information displayed in the Game Editor window and the Data Explorer window shows the CaveRunner game in the Games folder. A game is simply the empty husk of what we are really trying to build. Next, we will begin building out our game by adding a scene.


Making a scene

We can think of a scene as a level in a game—it is the stage upon which we place our objects, so that the player can interact with them. We can create a scene by performing the following steps:

  1. Click on Edit | Scene | Create in the Game Editor window.

  2. Name the scene as Level1 and click on the OK button.

  3. The new scene is created and opened for immediate use, as shown in the following screenshot:

We can tell Level1 is open, because the Game Editor window switched to the Scenes tab and now Level1 has a green check mark next to it; we can also see a grid in the Scene Viewer window. Additionally, the scene information is displayed in the upper left-hand corner of the Scene Viewer window and the Scene tag says Level1.

So we were able to get a scene created, but it is sadly empty—it's not much of a level in even the worst of games. If we want this game to be worth playing, we better add something interesting. Let's start by importing a ship.


Importing models

A model is a 3D object that represents a physical object such as a car or, in our case, a spaceship. ShiVa has basic modeling capabilities such as adding shape primitives and we may actually use some of them later, but as our ship is the focal point of our entire game—it's our main character—we should make it interesting. There are many places to find pre-made models and even some good software we can use to make our own (see Appendix B, Additional Resources), but for this book, we are going to stick to the pre-made option—making our own models could be an entire series of books on its own.

For this model, I went to www.turbosquid.com and found a free model called FV X1 Fighter by a user named pinarci. The model was created in Blender (free 3D modeling software), but since ShiVa can't import .blend files, I opened it in Blender and exported it to the Collada (.dae) format. You can find the Collada version of the model in the downloadable content. To import a model, click on Import | Model in the Data Explorer window.

The Import a Model dialog window will open and, for the most part, we will accept the defaults, but we do need to make sure that the Convert from Z to Y up axis option is checked. Blender uses the z axis as the vertical axis, but ShiVa uses the y axis. If we don't check this option, the model will be displayed sideways. Just click on the button to browse for our model and click on the Import button.

ShiVa will begin importing the model including the materials and show the progress. If you see that the model is imported properly, you can then click on the OK button. To view the model, simply double-click FV_X1_Fighter in the Data Explorer window. If you don't see it, make sure the Model folder is selected in the Data Explorer tree-view.

Hold on; that doesn't quite look right. The model is solid black and we can't make out any details. Don't worry, it happens every time and there is a perfectly rational explanation. Since ShiVa controls the lighting in the game, we need to tell ShiVa that the ship materials should react to game lighting. A material is a way to define what an object's surfaces look like, it can be complex with many layers or simply a color. Let's switch over to the Material Editor window and get this fixed. The Material Editor window is part of another of the standard editor views, so click on Design in the upper right-hand corner of the editor window.

The Design window gets a bit crowded because the view includes six modules, but we are only going to focus on the Scene Viewer and the Material Editor windows for now. To open the ship's material, just click on the centre of the Material Editor window and select the material from the dialog that pops up.

Let's start with the main theme material, that is, FV_X1_Fighter_FV_X1_main_theme-material. Once the material loads, you should see all kinds of information in the Material Editor window. Select the Lighting tab and click on the Receive Dynamic Lighting checkbox—the Per Vertex checkbox should be checked by default. Immediately, we can see that the material has been updated and now it is possible to see the ship details and see the shading from the light. These settings are shown in the following screenshot:

The backs of the engines still look black and featureless, so let's switch to the other material by clicking on Material | Open in the Material Editor window and selecting the particle drive material, that is, FV_X1_Fighter_Blue_partical_drive_g-material. Repeat the lighting changes from before and then scroll further down the lighting section to the Colors subsection. Let's make the engines a bit more exciting than just the plain blue they were previously.

Adjust the Diffuse and Emissive settings to be something similar to the settings shown in the previous screenshot. The Diffuse color is what you see on the object and the Emissive color is the color of the light that radiates from the object. We added the emissive color, because the engines look more dramatic with a glow. Last, but not least, click on Materials | Save All to save the changes to both the materials we have open.


Editing the scene

Okay, so we imported our model and made a few tweaks, now it's time to get it into the scene so we can see it in the game. The steps to edit a scene are as follows:

  1. Return to the General view by clicking on General in the upper right-hand corner.

  2. The Game Editor window should still show that the game is loaded. If not, click on Game | Open and select our game.

  3. Switch to the Scene tab and double-click Level1, so that the scene opens in the Scene Viewer window.

  4. Now to load our ship into the scene, all we have to do is drag-and-drop it from the Data Explorer window to the Scene Viewer window.

We can see that the model has appeared in the scene, but it is black again! Don't worry, we just need to add lights to our scene which we will do shortly. Let's switch the Attribute Editor window to the Scene Explorer window to see how the scene updates—click the concentric squares in the upper left-hand corner and select Scene Explorer from the list, as shown in the following screenshot:

Now we can see that the scene has a default camera, which we are looking through to see the scene, and the ship. The default camera is indicated by the DefaultCamera option, as shown in the following screenshot:

Eventually, we will have many more assets in the scene such as the cave and obstacles, but in this chapter we are only going to use the ship.

To make our new object more useful, we need to right-click on the ship in the Scene Viewer window or the model name in the Scene Explorer window and select Edit Selection Tag. This will enable us to set a name that we can use to refer to our ship in our code. Let's call it Ship and click on the OK button.

You have been patiently waiting for the lights I promised, so let's add them now. Click on the Models folder in the Data Explorer window and drag-and-drop a DefaultDynamicLightSet model into the scene. This model lights the entire scene no matter where they are located, but their rotation will determine the direction of the object shadows. This is shown in the following screenshot:

Now we can see the ship details again. Notice that the Scene Explorer window now shows the lights in addition to the ship and the camera.

We are making progress, but we still don't have a functioning scene. If you want to see what happens when we run our game, click on the Play button at the top of the screen. The game controls are similar to a DVD or CD player—you can stop, pause, play, restart, or play one frame at a time. When we click on the Play button, we get a black screen in the Scene Viewer window, because we have not told the game how to load the scene we have been working on—not very exciting. Click on the Stop button and let's make things more interesting by adding some scripting.


Adding intelligence

The scripting in ShiVa is called Artificial Intelligence (AI), which calls up images of robots realizing humanity is a sickness that must be eradicated, but fear not, it is much more benign than that. AIs are simply behaviors that can be added via scripting to objects, scenes, and so on. In fact, AI is needed to load the first scene of our game. Speaking of which, let's set that up now. Click on Edit | User Main AI | Create in the Game Editor window to create the game's main AI. The usual dialog opens asking us for the name of the new AI. Let's call this MainAI, so we know exactly what it does.

Our newly created MainAI now shows up in the User Main AIs information box. The AI also opens for us to edit, but in our current view we can't see the AIModel Editor window. Click on the Code view in the upper right-hand corner of the main window to open the scripting view. The Code view is shown in the following screenshot:

This view shows us everything we need to do some serious scripting. We will go over the specifics in the next chapter, but for now let's do some basic scripting to get our game going.


First, we need to declare a variable to point to our ship since it is such an important piece of our game. Click the + next to the Add Variable... option in the AIModel Editor window.

This will open the Variable window, which is shown in the following screenshot:

In ShiVa, we usually start variable names with a letter that signifies what the variable does. In this case, we are creating a handle, or a reference, to our ship object, so let's call it hShip. Select object for the variable type and enter a nice description of what the variable does. Click on the OK button to create the variable. The hShip variable shows up under Variables now and we can write the code for setting up our scene.


Scroll down in the AIModule Editor window until you see the Handlers option. A handler is code that is executed when a certain event occurs. They work a bit differently from the variables in that there are many pre-defined handlers—for the most part, you pick one that is already defined by ShiVa, but we will be creating custom handlers in Chapter 4, Physics and the Environment. In this case, we are going to create an onInit handler. This handler will execute only when the scene is initialized, so it is a great place to set up any resources the scene will need. Click on the + sign next to the Add Handler... option and select onInit. The handler is created and the code is automatically opened for editing, as shown in the following screenshot:

We can see that there is a template for scripting code. Feel free to enter the Author and Description fields although they aren't required, but we must keep any other edits strictly between the function definition and the end statement. ShiVa uses the Lua language syntax, which is similar to Python. The code for setting up our scene is pretty simple and is as follows:

-- Set the current scene to Level1 and 
-- compare to nil to make sure the scene loaded
if( application.setCurrentUserScene ( "Level1" ) ~= nil ) then
    -- Get a handle to the ship by using the ships 'name'
    this.hShip ( application.getCurrentUserSceneTaggedObject ( "Ship" ) )
    -- Send an error message to the log 
    -- if the scene can not be set
    log.error ( "Unable to load initial scene" )

The first line loads our scene by name and also checks that it was successful by comparing the result to nil (ShiVa's version of null). If the result was nil, it means that the scene was unable to load, so the code jumps to the else statement and logs the error. Otherwise, if the scene is not nil, then we assign a value to our hShip variable by asking the application to find the object that is tagged Ship.


We are able to find the object by name because we previously set the ship's tag.

This code is enough to get our game running, so let's save it by selecting Script | Save All in the Script Editor window and then compile the code by selecting Build | Compile, or simply press F7 on your keyboard. As long as there are no errors, you should see a success message in the Build window at the bottom of the screen. If there are errors, the Build window will show error messages with line numbers and a short description of the problem. These messages can be a bit cryptic at times, so make use of your favorite internet search engine or stop by the developer forums—chances are that someone has had the same error. Before we run the game again, let's add one more thing so we get more than a static screen.

Click on the + sign next to the Add Handler... option again, but this time select the onEnterFrame event. This event occurs each time a frame is being processed so it is a good place to put things such as animations that will update each frame. In this case, we are going to animate the camera, so that it rotates around the ship. Again, the code is not very complex and is as follows:

-- Test if the ship exists first
if(this.hShip ( ) ~= nil) then
    -- Get a handle to the camera
    local hCamera = application.getCurrentUserActiveCamera ( )
    -- Get the location(translation) of the ship
    local x,y,z = object.getTranslation ( this.hShip ( ), object.kGlobalSpace )
    -- Tell the camera to rotate around
    -- the ship location - x, y, z
    object.rotateAround ( hCamera, x, y, z, 0, 1, 0, object.kGlobalSpace )
    -- Tell the camera to look at the ship
    object.lookAt ( hCamera, x, y, z, object.kGlobalSpace, 1 )

The first thing to notice is that, similar to the onInit code, this code is wrapped in an if statement. The if statement is checking that the ship exists, because without it this code will not work.


Check your objects!

It is always a good idea to check your objects this way, because they may not be available for whatever reason and you don't want your game to crash!

Next, we get a handle to the only camera in the game so that we can manipulate it. We also get the location of the ship—ShiVa calls this the translation—and we tell ShiVa we want that in reference to the global space. Then we tell the camera to rotate around the x, y, and z axes (the ship location) at a rate of 0, 1, and 0 (rotations around the x, y, and z axes) degrees respectively. This sets the camera rotating around the y axis of the ship's location at 1 degree per frame. Lastly, we need to point the camera at the ship, otherwise the ship would go in and out of the view as the camera rotates. Using the lookAt function, we turn the camera towards the x, y, and z axes (again, the ship's location) in the global space. The last argument in the lookAt function is the rate at which the function will look toward the location—a setting of 1 will cause the action to occur in one frame, while values between 0 and 1 will cause the action to be averaged over several frames, creating a smooth transition.

That's it! Save the code by clicking on Script | Save All in the Script Editor window and then compile the code by selecting Build | Compile All.

Switch back to the General view and click on the Play button. If everything was entered correctly, you should see the camera slowly rotating around the ship. Congratulations! I told you it wouldn't be much, but we are just getting started, there's more to come.



Whew! I told you we were going to move fast. I hope you gained a small vision of the fundamentals of ShiVa3D. We covered installation, creating a project, game, and scene and then imported a model into that scene. We then tackled scripting to load the scene into the game and threw in camera rotation as a bonus. We will spend the rest of the book expounding on the basics we have just learned, so we can really get a grasp on how to use ShiVa3D to create great games, but you can also refer directly to the ShiVa3D developer site at http://www.stonetrip.com/developer/, if you find something you want to spend a bit more time on. I think it's time to slow things down a bit, don't you?

About the Author

  • Wade Tracy

    Wade Tracy is the founder of Subspace Games which was created with the intent of inviting the internet audience to learn game development and design alongside him. He has experience developing mobile applications for Blackberry devices and currently develops enterprise applications using the .Net framework. More than anything he enjoys spending time with his family.

    Browse publications by this author
Learning ShiVa3D Game Development
Unlock this book and the full library for FREE
Start free trial