Chapter 3: Visual Objects and Mechanics

In the previous chapter we talked about the conceptual design of the fishing game we are developing for Hyzonia. In this part we discuss the game play and we develop a working prototype of the game.

The main purpose of a Hyzonia advergame is to make the users engage with the advertised contents. Advergames should be easy to play; they should not have a very complicated game flow. In general they should not require a particular platform to run. Most of the time your audience is a wide range of internet users, not hardcore gamers.

The content of this article doesn’t describe any particular feature in Hyzonia Game Services platform. Here we build almost all the logics and UX of the game. This will be a JavaScript game and we heavily use jQuery. JavaScript using jQuery is a very fast and developer friendly platform. If you are a web designer you don't need to acquire a new skill to develop a JavaScript based game. On the other hand it will help us to make the games easily customizable (we will dig into customization in a later chapter).

The objects that we are developing here could be reused in many other JavaScript games.

We chose a classical game development approach for making this game; we are going to have a game timer that ticks several times a second and all the magic happens during each tick.

In our implementation the GameTimer class has an array of MovingObjects. In each tick the timer calls move() method of each MovingObject. The move method updates the position of the object and draws it on the screen.

GameTimer

GameTimer is a singleton object.
The most important methods of GameTimer are:

• start()
• stop()
• pause()
• addMovingObject(movingObject)
• funcs: an array of callback functions. These functions will be called at each tick.
• frequency: in miliseconds
• tick(): private

Current implementations of JavaScript in browsers don't support threading and parallel programming. It means that all the time that it takes for exestuation of the callback functions that run at each tick must be less than the frequency of the timer; otherwise the user will experience freezing and delays.

ViewPort

A game may have many view ports. Each view port has its own set of MovingObjects. The game can have one active view port at a time. All visual objects must belong to the active ViewPort to be rendered on the screen. This game has only one view port.

The ViewPort object has these members:

• size: this width and height of the view port
• jq: a reference to the jQuery object of the parent HTML element of the view port (all visual objects in the ViewPort must be child elements of it)
• addMovingObject(movingObject)
• And some attributes related only to this game like sea level.

MovingObject

• position: the x, y position of the object, relative to its view port.
• size: the width and the height of the object.
• v: the instant velocity of the object relative to its view port.
• jq: a reference to the object's jQuery object (visual representation of the object).
• t: time (automatically assigned by GameTimer).
• getRect(): returns a Rect object describing the surrounding rectangle of the visual object.
• contains(x, y): finds whether point x, y is inside the object (x and y are relative to the object's view port. It will be used for a simple collision detection.)
• _updatePosition(): it is virtual method, by default it adds the instant velocity to the position of the object on each tick. We override this method in child classes to control the motion of the objects.
• move(): moves the object to its current position.
• _onMoved(): it will be called after the object is rendered in the screen at its current position.

Boat, Fish and Rod inherit from MovingObject.

In this game the player has to catch fishes using a fishing rod. The length of the thread of the rod increases as long as the left mouse click in down (so the player can catch fishes in deeper positions). It begins to retract as soon as the user releases the left button. Its length changes between a minimum and maximum value. You can think of many mathematical functions to control the length of the thread. The range of the function should be between min and max of the thread. We chose a simple trigonometry function, arc tangent. The change of the return value of arc tangent function slows down as its argument grows to bigger numbers.

Arctangent function

We attach a time property to rod. Rod time changes between 0 and 5 and its length changes between 0 and a coefficient of 7π/16. arctan(0) = 0 and arctan(5) = 7π/16.

User Input Handlers

GameControlsState class contains all the data about the current state of controls: the location of the mouse, the buttons that have been pressed but not yet released, etc. Event handlers change the state of this object. Later at each tick, each callback function checks if its controls have been triggered or not.

For example _updatePosition() method of Boat looks like this:

_updatePosition : function() {
        if(GameControlsState.keyBoard.left) {
            this.position.x -= 5;
        }
        if(GameControlsState.keyBoard.right) {
            this.position.x += 5;
        }
}

It means that at each tick of GameTimer, the boat moves 5 pixel to the left if left arrow key is down. Because tick is called 30 times a second, the small delays between each tick is unnoticeable for a player. Unfortunately JavaScript doesn’t support multithreading. You have to limit the amount of computation in each tick. User feels the delays if the computation takes more than 30 milliseconds.

Depending on your game you may want to choose a different event handling pattern.

Fish

The Fish object inherits from the MovingObject therefore all we need to make it behave like a fish is to define few more properties and a custom moving function by overriding "_updatePosition" function, Fish has the following attributes:

• isTrash: if true, it means that the object is a trash (trashes have no use for the player, we will talk about the difference between Fish and Trash and the need for trash objects in a later chapter)
• movingDirection: the direction in which the fish moves, it can be from right to left "rtl" or left to right "ltr".
• mouth: the mouth is a rectangle that defines the mouth area of the fish in which the fish can be caught.
• isHooking(x,y): this function takes the hook's coordinates and finds whether the hook is inside the fish's mouth.
• hook(): once the rod hooks the fish, it calls this function. This way the act of hooking will be controlled by the rod not the fish. After this call the fish can do any necessary action like performing a fishing animation.
• switchImageToVertical(): it is a private function. To make a better fishing animation, we rotate the fish image vertical direction as it is being dragged by the rod's hook. The function creates this animation using spriteAnimation jQuery plugin.

Two kinds of sprite animations we use for a fish: swimming and fishing. Note that the fish rotates around an axis that is located at its mouth.

Fishing Rod

Another important object in our fishing game is the rod that the player will use to catch the fishes. The hook is a part of the rod object and it is responsible for catching the fishes. The hook is a property of the rod which moves down and up. While the hook is moving we continuously check if the hook intersects with any fish by calling the fish's "isHooking()" function. This way the act of fishing will be controlled by the rod.

The rod goes through three main phases: moving down and up looking for fish, catching a fish and going back to the boat (retracting) with a fish.

By overriding the "_onMoved()" function of the movingObject class inside the rod, we can check for fishing events:

• When the rod is fully retracted and has a fish: it means that we should add the fish to the players bucket and do all the related events Like (increasing score, removing the fish from the ViewPort, …). This state is particularly important for Hyzonia advergames, this is where the player makes a progress in this game. All Hyzonia games must work with a type of Hyzonia Quest. From a very abstract point of view Hyzonia expects players continuously progress in the Quests and win them. We will discuss it in details in chapter 5.
• When the hook of the rod intersects with a fish: we fires the hooking events.

Config

If you look at the code you will notice that in several places we use Config object. Config represents the static configuration of the game and is a singleton name value collection in JSON format. The attributes of this object will be customizable. This is a common feature in all Hyzonia games. We talk about customization in details in a later chapter, for now we just describe the most important attribute of Config in this game:

• LIST_OF_FISHES: An array that defines the types of fishes the game has. Each element of the array is a fish data object that has the following properties:
  
  • isTrash
  • size: the size of the fish image.
  • movmentImage: the URL of the sprite animation of the fish in swimming state.
  • imageUrl: the URL of the sprite animation of the fish in fishing (hooking) state.
  • dir: swimming direction, "rtl" or "ltr".
  • swimDepth: an array of numbers that represent the y positions in which the fish can appear in.
  
  

We place the "LIST_OF_FISHES" array in the Config file. Later this file can be exposed to Publishers to enable customization of the game (for example using LIST_OF_FISHES they can customize the picture of the fishes).


Here is the prototype of this game. You can download the source code. We kept the code simple and clear. Therefore it lacks lots of small FX and fixes, but it's easy to follow the logics.


"GameTimer" and the "MovingObject" classes are very handy and can be used in implementing many kinds of games. Such these generic classes makes development of JavaScript based games easy and neat.

Here we also used our "sprite animation" jQuery plugin to create the animations (swimming and fishing); this way the animation is separated from the other logic of the game.

In the next chapter we introduce Hyzonia Game Client Services. These services can be consumed by game clients to communicate with Hyzonia.

Read more...

Chapter 2: Game Objects Conceptual Design

Developing an Advergame for Hyzonia

In the previous chapter we introduced a kind of casual fishing game that we are going to develop using Hyzonia platform as a sample. In this chapter we will describe the game from an abstract aspect; this will help us to understand the game logic, the main actors and what objects are needed to implement the game for Hyzonia platform.

From a game developer point of view, Hyzonia is a platform that makes building advergames easier and routine. Hyzonia allows the developer to focus on developing the game itself. The developer should think about the game rules and the game play rather than spending time trying to implement features that are not related directly to his specific game (like receiving advertisements, generating reports, etc.). Those functionalities can be implemented using Hyzonia tool called Hyzonia client library and Hyzonia Game Services that we will explain them more in the next chapters.

From a very abstract standpoint a Hyzonia game is made of three layers:

1. Game Client
   
   This layer consists of game logic, user experience, visual effects, etc. A Game Client can be made in variety of platforms like Flash, Silverlight, or Java (any platform that can communicate with XML or JSON web services). In Hyzonia we admire JavaScript, in this tutorial we build the client using JavaScript by the help of Hyzonia JavaScript Client library; this library can be used for general games purposes tasks, like having a timer or moving objects in the screen to create game animation. The game client layer is responsible for the following main functionalities:
   
   
   • Game Play: Managing the game logic
   • UI: Managing the visual objects and interacting with the player.
   • Game Services Client: Facilitating the communication with the game services
2. Game Server
   
   • Game Services: Game Services were built to help the developer to create Hyzonia compatible games easily, the services are XML Web Services that were developed using ASP.NET and can be consumed by any Web compatible technology.
     To make using these services easier to a wider range of developers, the game services can be consumed using any of the following XML or JSONP.
     
     Hyzonia JavaScript Client library contains a proxy that can be used to facilitate the communication with theses services. Calling a Hyzonia Service using the client library is as simple as calling a JavaScript function.
     
     Some parts of the targeting job are managed by this component. For example when a player starts a game session, this component finds which ad materials (Items) and Quests are relevant to her.
     
   • Statistics: The statistics services provide game data that can be displayed in the game like Top Ten Players Scores, The prize of the day, the new prizes in the game….
     
   • Game Data: All the functionalities that are related to managing the players’ data, ads data, Quests and other related game information like login, registration...etc are implemented using this component. The data layer is commonly transparent for a Game Client developer.
     
   • Hyzonia Network Communication: The main rule is to communicate with Hyzonia advergames network, this layer communicates all the data related to ads, Campaigns and Quests to and from Hyzonia platform. It is a crucial part of a Hyzonia game, without it the game simply cannot make any money.
     This component is also hidden for Game Client developers.
     
   
   
3. Hyzonia Advergame Network
   
   Games that are part of Hyzonia advergames network automatically receive Campaigns, ads and Quests from the network. Campaigns are made by advertisers who use the network to publish them to their targeted players audience. The role of an advergame is to make the engagement of the players with the ad materials happen. The network chooses and publishes the Campaign in the relevant games. Once a game was created using Hyzonia platform, the game dynamically communicates with the network. This does not require the developer to develop any special logic. Everything regarding this communication, receiving orders, targeting players and reporting, is transparent for Game Client developers.
   

Conclusion:
A casual (adver)game developer has to make Game Play and UI.
He will not care about ads, campaigns, reporting, data management, etc. these things will be provided by Game Services.

Figure 2.1: Click for larger view

Conceptual design of the fishing game

In this tutorial we will focus on the UI, Hyzonia JavaScript Client Library and Hyzonia Game Services.

Here are the main objects for our fishing game:

Figure 2.1: Click for larger view

• Moving Object
  It encapsulates all the functionalities about animating a visual object in the View Port coordinate system. In our design, Moving Objects, View Port and Game Timer will work closely to move fishes, boat and fishing rod.
  
• Fish
  image, position, containing item, isTrash
  move(), isHooked,create(), attachToHook()
  
• Fishing Rod
  hook position, phase
  isHooked()
  
• Boat
  move(dir), image, position,
  
• Game Session
  Contains the data about Quest. A player will either win or lose a Game Session.
  sessionId, time left, items,
  endSession()
  
• Player
  Player data will be maintained by Game Services.
  name, id, points,
  increasePoints(),
  
• Bag
  items, size
  removeItem(item), addItem(item),
  
• Quest
  toDo,
  canWin(), win()
  (see chapter I to read more about Quest and particularly Collect Some Items Quest)
  
• Item
  Item is an playable advertismenet material. We will dedicate a whole chapter about the relationships among Items, Quests, Campaigns and Engagements.
  For now think an Item is made of: picture, name, description
  
• View Port
  width, height, background, sea level,
  showDialog(dialogId)
  
• Game Timer
  Manages the movement of the objects.
  

Later you will see that we add more UI functionalities to work with registration and login, and a few more features.

In the following post we will talk about visual objects and the mechanics of this particular game. We will make a working prototype of this game using JavaScript.

Read more...

Chapter 1: Game Design

Developing an Advergame for Hyzonia

This is the first chapter of a series of posts intended to be a tutorial guiding developers in making their first advergames for Hyzonia. In this tutorial we will focus on Hyzonia Game Services. We will show how you can consume these services and use Hyzonia functionalities at its best in your game.

At the heart of this series is a simple advergame we are building specifically for the tutorial. As an introduction, let’s talk about game design:

The game begins by selecting a Quest. In Hyzonia each Quest has a prize to win. The player has the luxury to choose what Quest he wants to play and the corresponding prize he wants. A Quest has a ‘To-do’ and the player wins if he fulfills the To-do. We will discuss further about this unique advergame feature of Hyzonia, and the other several types of quests in the later chapters of this tutorial. Here, we will focus on a particular type of Quest: 'Collect Some Items' quest. After selecting a Quest the player will be given its list of ‘To-do’ which has the items needed to collect in order to win the game (quest).

The To-do items in the player’s selected quest can be found in the fishes and other creatures in the sea. The player must catch as many as he can in the given time limit for a better chance to complete the quest. He may find fishes with items not related to his quest. He just has to drop those items. He must avoid catching trashes to not waste more time.

Once all correct items are collected, a submit button will appear in My Quest panel. Player must click the button to submit his winning game for the record.

Game ends when a player runs out of time and has not yet collected all To-do items. He can always play again though or select a new Quest to play for.


Main Features of the Game

Landing Page
Landing page is every player's entry point before the game proper. Hyzonia requires players to register before playing the games. If he is already registered, he will just have to login. Hyzonia also provides some integration services by which a publisher can integrate its users into its games so that registration and login will be hidden from a player’s point of view.

Selecting a Quest
A Quest is made of a prize, a to-do and a few other things. Player has to select a quest (prize) to play in the welcome page of the game, shown after login. He needs to select one to proceed.

To Do
'To-do' is relative to the selected Quest. It shows the items and how many of them are needed to collect to win the game.

My Quest
This panel opens on the right side of the game upon clicking it on the Top Bar. This is a checklist of the player about his progress in the quest. It has an indicator of how many items he has already collected or what else and how many still remains to be collected.

Player should watch out for the submit button that appears at the bottom of this panel after he completed the quest. He must click that button to record his winning game.

My Bag
Every item collected by the player, whether part of his quest or not goes to the 'My Bag' panel. The bag has a limit of 9 items maximum (This is a limit set for Collect Some Items quest). Player needs to watch out what he is putting in the bag. If it is not part of the quest, player can drop it to allot space for the correct items.

Stats
It contains the rankings of the top players, a prize of the day, a brand of the day, and also records of the latest winners and newest prizes available.

View Port
This is literally the game view - bordered by 550px (w) x 365px (h) rectangle. The background environment, the items and all the above mentioned features are within View Port.

Graphical Sketches

This game will be composed of the following graphics elements:

In the succeeding chapters, we will discuss about the required specs. To make it easier we will provide you with ready-to-use images to download and guide you on how to use them and how to animate them. We will show you how to make the game customizable. So all these images, the whole look and feel of the game and some of its mechanics will be made configurable in run time (by publishers).

This is a preview of what are going to achieve at the end of this tutorial:

In this tutorial we build the game client using JavaScript and JQuery library, the following chapter will be about the objects conceptual design of the game.

Read more...