In this tutorial series, we will focus on cross-platform game development for the iPad and Android tablets using the ShiVa3D Suite game development framework. Although mainly for 3D games, ShiVa3D Suite can be used to develop 2D games as well. "Puzzle", the game described in this series, is an example of a relatively simple 2D game that can be quickly created with ShiVa3D.
Also Available in This Series:
The main goal of the Puzzle is very simple. When the game starts, pieces of an image are randomly positioned on the screen. To solve the puzzle, the user needs to place those pieces in their correct locations. A timer shows the elapsed time since the start of the game. The timer can be paused if the user needs time off from the game. By pressing a "Solve" button, the game can be automatically solved, a feature that comes in handy if the user needs help with solving the game.
Organization Of The Series
This tutorial series consists of three parts. Part 1 starts with the next section, named "Description Of The Game", where we give more details of the Puzzle, describing its behavior using screenshots. In the following section, "Screen Images in Android Tablet and iPad 2", we provide screen images of the final product in an Android tablet with Android OS 4.0.3 (Ice Cream Sandwich) and iPad 2 with iOS 4.3. This is followed by "Development Process Via Shiva3D Suite", where we introduce the main components of the ShiVa3D Suite, the ShiVa Editor, and the ShiVa Authoring Tool, and then give an overview of the process to develop the Puzzle in a platform independent manner with those components.
The following sections are concerned with implementation. Part 2 starts with "Game Geometry", which is focused on the underlying geometric aspects of the game and lays the background for code development. In "Developing The Puzzle In The ShiVa Editor", we introduce the main constructs of the code base that implement the game functionality, including the variables, functions, and event handlers. This section also gives step-by-step instructions on how to develop the game with the ShiVa Editor. Here, we describe creating the project and the game and importing textures, the AI model, and the sound bank from the download archive accompanying the tutorial. This concludes Part 2 of the series.
Part 3 of the series continues the discussion in "Developing The Puzzle In ShiVa Editor". We describe importing the HUD components and make the final adjustments on the game developed so far. Then, we conclude "Developing The Puzzle In ShiVa Editor" via a unit test. In the "Authoring Tool" section, we show how to use the ShiVa Authoring Tool to convert the Puzzle into two different applications, one for Android OS and one for the iPad. We wrap up the article with "Conclusions", where several concluding remarks are given.
Credits
Some of the reference material in this article has been borrowed from the official ShiVa3D product website.
The sound files used in the application have been taken from the sample set that installs with the ShiVa Editor (Stonetrip\ShiVa Editor PLE\Data\Samples\Resources\Sounds folder).
The codebase for rotating the viewport, so that the toolbar stays atop as the device is rotated by the user, is based on another ShiVa 3D tutorial
(http://www.stonetrip.com/developer/1704-rotate-the-viewport-according-to-the-device-rotation).
The codebase for multi-touch management takes ideas from another ShiVa 3D tutorial (http://www.stonetrip.com/developer/1046-multitouch-management).
The author has greatly benefited from a book on ShiVa3D, entitled Introduction to 3D Programming with ShiVa.
Finally, the videos in this tutorial have been produced using open source FreeStudio Video to Flash Converter and CamStudio tools.
Description Of The Game
In this section, we will describe the Puzzle game. The application starts with the following splash screen.
Initialized State
After the splash screen is displayed, the game enters the "Initialized" state. This state starts with puzzle pieces originating from the lower left corner of the display moving to random locations on the game area. As they move, half of the pieces turn clockwise and the other half turn counter-clockwise (a snapshot is provided below).
The short video below shows the game while it is initializing.
Once all the pieces have taken their random positions, the Start and Solve buttons become enabled in the toolbar at the top as shown in the figure below. There are a total of 54 puzzle pieces placed in 9 rows and 6 columns. As we will see later, the application code can be easily extended to accommodate any number of rows and columns. The purpose of the game is to position the pieces to construct the puzzle image correctly in the shortest timeframe possible. If a piece is positioned in the correct location, its borders are highlighted in green. As an example, see the third piece in the last row below.
The game starts when the Start button is pressed. This brings the game into the "Started" state.
Started State
In this state, the Start button turns into a Pause button and the New and Solve buttons are disabled. The timer starts counting. When the user moves a piece to another position, let's say piece A, the piece it replaced moves automatically to the original position of piece A. This is shown in the figure below. The user has moved the piece on the upper left corner to the lower right corner (movement indicated by green line). The puzzle piece it replaced moves up to upper left corner to fill in the empty location (piece indicated by red arrow). Automatic movement of the piece takes approximately 3 seconds to complete. Although not shown in the snapshots above, the automatically moving piece rotates clockwise or counter-clockwise while it travels. The clockwise or counter-clockwise decision depends on the column and row index of the piece.
The video below shows the user pressing the Start button and then moving a piece from one location to another, replacing another piece.
As mentioned previously, there are 54 puzzle pieces. These are placed in fixed positions consisting of 9 rows and 6 columns as shown in the figure below. Centers of the puzzle pieces coincide with the fixed positions.
In order to move a piece, the user presses on the piece with a finger and moves it as desired. When the target position is reached, the user releases his finger. If the distance between the nearest fixed position and center of the puzzle piece is less than a pre-specified tolerance (a parameter in the application code), then the piece automatically snaps into the fixed position. Otherwise, the piece moves back to its original position automatically.
When the piece moved by the user snaps into a position, the piece it replaced moves into the original position of the piece moved by the user. If the piece moved by the user does not snap into a new position, it goes back to its original position. In both cases, the motion is performed automatically by the application. When that motion starts, the game goes into a new state called "Replaced".
Replaced State
This is a state where a puzzle piece moves automatically, rotating clockwise or counter-clockwise during the travel, and finally reaches a target location. Motion of the puzzle piece is controlled by the application. When the motion is completed, in other words when the piece reaches its position, the game goes back into the "Started" state.
Started State - Continued
If a puzzle piece is placed in its correct position, its borders will be highlighted in green. In the sample screen image below, the pieces that have green borders are in the correct positions. Those that do not have green borders are not in the correct positions.
If a user presses the Pause button, the game will go into the "Paused" state.
Paused State
In the Paused state, the timer is suspended. The Pause button will turn into the Start button and the New and Solve buttons will be enabled, as shown below.
In Paused state, puzzle pieces cannot be moved.
In the Paused state, if user presses on the New button, this will end the game and the application will restart. The game will go into the "Initialized" state (see above). The puzzle pieces will originate from the lower left corner of the display moving to random locations on the game area.
Also in the Paused state, if the user presses on the Start button, the game will go back into the Start state.
In Paused state, if user presses on the Solve button, this will end the game by solving it automatically. Solving the game this way is useful if user has given up solving the game on their own. The pieces will move from their current locations into the correct locations to construct the puzzle image (See the figure below). The game will go into the "Solved" state.
The video below shows the game when user presses the Solve button.
Solved State
In the Solved state, the puzzle image has been constructed. In the right-most image in Figure 9 above, observe that the puzzle pieces all have green borders because they are all in correct positions.
In the Solved state, only the New button is enabled. The user can press the New button to restart the game. This will bring the game into the Initialized state. As described previously, puzzle pieces will originate from the lower left corner of the screen and start moving to random locations.
State Diagram
The following diagram shows the state transitions summarizing the discussion above.
Screenshots for Android and iPad 2
Android OS 4.0.3 (Ice Cream Sandwich) Tablet
The following images show the puzzle game on an Android OS 4.0.3 tablet during Initialized state. A new game is starting, on the left, and just after all puzzle pieces have reached their random locations, on the right.
The following images show the puzzle game on an Android OS 4.0.3 tablet, just after user pressed the Solve button, on the left, and after game is solved, on the right.
The following image shows the launch icon of the puzzle game on an Android OS 4.0.3 tablet.
iPad 2
The following images show the puzzle game on iPad 2 during the Initialized state. A new game is starting, on the left, and then just after all puzzle pieces have reached their random locations, on the right.
The following images show the puzzle game on iPad 2, just after the user pressed the Solve button, on the left, and then after the game is actually solved, on the right.
The following image shows the launch icon of the puzzle game on iPad 2.
Development Process Via Shiva3D Suite
ShiVa3D Concepts
In this section, we will discuss several concepts of game development with ShiVa3D. Most of the discussion here is borrowed from the original ShiVa3D documentation. For more information, please see http://www.stonetrip.com/developer/doc/ and the user manual that comes with ShiVa editor.
Note that ShiVa3D is mainly a 3D game development framework. Our game does not have 3D features, however, and is an example of how ShiVa3D could be used to develop 2D games as well.
Game represents a game, the main entity of the application. It encapsulates everything else in the application such as cameras, scenes etc. A Game is a standalone deployment unit.
AIModel implies 'artificial intelligence' and represents behavior. An AIModel can have functions, handlers, states, and variables. In the Puzzle, we will use a single AIModel to define functionality of the game.
Script contains the code in an AIModel, for example, code for a function or handler. The scripting language in ShiVa3D is Lua.
HUD stands for "Head Up Display" and is a term to represent various user interface widgets such as button, label, list, slider, etc. allowing the user to interact with the game.
ShiVa3D Tools
To develop the Puzzle game, we will use the free version of ShiVa3D Suite (http://www.stonetrip.com/download.html), which includes ShiVa Editor PLE (personal learning edition) and ShiVa Authoring Tool. The diagram below gives an overview of the development process we used with those tools.
Let's discuss individual steps of that process.
ShiVa Editor
The ShiVa Editor has various modules to develop and test a 2D or 3D application, typically a game, from ground up. An important feature of the ShiVa Editor is that an application developed with that tool can be deployed (after authored in ShiVa Authoring Tool) in different devices with different operating systems, e.g. a PC running Windows OS, a mobile phone with Android OS, iPhone/iPod Touch, iPad etc. Some of the basic actions you can perform with the ShiVa Editor are as follows.
Develop:
- Create a new game.
- Create AIModels and write scripts for the AIModels.
- Create a HUD and integrate it with the AIModels.
- Compile the scripts in the game.
Test: You can perform an initial test of the 2D or 3D application in the development environment before deploying it in a target device. Testing is performed via the Animate or Preview feature of the ShiVa Editor. During testing, you can change settings for the screen size to see how the application will be displayed in the actual target device. In the Puzzle, to test button events, we used mouse clicks. To test touch events, we used drag-and-drop via the mouse.
Export: After testing is complete, export the application. This will generate a file with an stk extension. The exported application will be used by the ShiVa Authoring tool, which is discussed next.
ShiVa Authoring Tool
The main purpose of the ShiVa Authoring tool is to convert an application, created via the ShiVa Editor, into a platform specific application that can be deployed in a particular device, e.g. iPad or Android tablet. Certain restrictions apply in regard to the operating system of the machine running the ShiVa Authoring tool and the target device for conversion. For example, the ShiVa Authoring tool running on a Windows machine cannot generate an iPad or iPhone application. While developing the Puzzle, we used a Windows machine for The ShiVa Editor. To create the Android Puzzle application, we also used a Windows machine to run the ShiVa Authoring Tool. On the other hand, to create the iOS Puzzle application for iPad, we used a Mac OS machine to run the ShiVa Authoring Tool.
Some of the basic actions one may perform with the ShiVa Authoring tool are the following.
Select Authoring Platform: For the purposes of this series, the platform options we are interested in are iPad and Android. Note that for iPad you need to have the ShiVa Authoring Tool running on a Mac OS machine.
Import: Import the application (a file with stk extension) which was exported via the ShiVa Editor.
Build: When authoring for Android, we will configure the ShiVa Authoring Tool to generate an Android apk file that can be directly deployed in a compatible Android device. When authoring for iPad, we will configure the ShiVa Authoring Tool to generate an Xcode project for iPad development. Then, one can build the project in Xcode and deploy the executable to a connected device (building the project in Xcode and deploying the resulting executable to a connected device is not covered in this series).
For each platform, the ShiVa Authoring Tool offers slightly different options to generate its end product. For example, when authoring for Android, you could generate an Eclipse project instead of an Android executable. As mentioned above, we chose to generate an Android executable in this series.
Similarly, for iPad, one could generate an executable for distribution instead of generating an Xcode project. As mentioned previously, we chose to generate an Xcode projects in this series. Please consult the ShiVa Authoring Tool user manual for further details.
Software Configurations
The following is a list of configurations we used while developing the Puzzle game. For additional requirements and prerequisites, see the Shiva3D documentation described in http://www.stonetrip.com/developer/doc/editor/information/hardware and http://www.stonetrip.com/developer/doc/authoringtool/installation.
Configuration For ShiVa Editor
OS of development machine: Windows 7
Configuration For ShiVa Authoring Tool
- Android:
- OS of development machine: Windows 7
- Software Versions:
- Android SDK revision 8
- Android NDK revision 7
- Cygwin, GNU make package version 3.82
- Apache Ant version 1.8.0
- Test device: Android tablet with Android OS 4.0.3 (Ice Cream Sandwich).
- iPhone and iPad
- OS of development machine: Mac OS 10.6.7
- Software Versions:
- xCode 3.2.6
- iOS SDK 4.3
- Test device: iPad 2 with iOS 4.3.1
Concluding Remarks For Part 1
In Part 1 of this tutorial, we introduced our game and described its details. We also summarized the cross-platform game development process via Shiva3D Suite. art 2 will start with "Game Geometry", which is focused on underlying geometric aspects of the game and lays the background for code development. In "Developing The Puzzle In ShiVa Editor", we will introduce main constructs of the code base that implement the game functionality, including the variables, functions, and event handlers. This section will also give step-by-step instructions on how to develop the game in the ShiVa Editor. Here, we will describe creating the project and the game, and importing textures, AI models and the sound bank from the download archive accompanying the tutorial.
Comments