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

New loading pane for Hyzonia games

In order to better handle graphic rich games, we added a loading feature to the games. Using this feature the user can only start playing when the game finishes loading all its necessary objects. This way the user cannot try to play a game that is not fully functional yet.

This document describes the customizable elements of the "loading" feature.

The loading pane like other parts of Hyzonia games is customizable; Publisher can customize the style of the loading page very easily using the web forms that are accessible in his advergame control panel. If you are not familiar with basic customization for Hyzonia games you can read more in Hyzonia Docs.


The loading page is composed of two HTML DIV elements nested in each other; the parent DIV is the background, customizing it can be done by editing the "loading-div" class, while the child DIV contains the loading dialog where the 'loading…' text appears. This DIV is customizable by editing the "loading-dialog" class.

Both of those classes are added to the look customization section in docs.hyzonia.com.

Note in Blow the Bubbles, Hit the Monkeys, Blow the Balloons and Shoot the UFOs (generally if the game has a separate customizable CSS for Dialog Boxes) there are two places where the loading page appears. Hence two files Game Theme and Dialog Boxes needed to be edited by the same content.

The following is the default style of the loading pane elements:

• loading-div

  Description

  Changes the style of the loading pane. This pane appears when the game starts till all the game elements are loaded. The background is a "DIV" element, you can use any CSS instruction to style it.

  Code

  .loading-div
  {
  background-color: #aaaaaa;
  }
  





• loading-dialog

  Description

  Changes the style of the loading pane dialog. This dialog contains the loading text, normally it is "Loading…". The dialog is a "DIV" element; you can use any CSS instruction to style it.

  Code

  .loading-dialog
  {
  background-color:#ffffff;
  color: #000000;
  margin:auto;
  top:50%;
  }
  

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