DizzyAGE - How To?

HOW TO?
about utils...

How to track the playtime?

Some games may need to track the total time the player needs to finish the game, for a final report, for score or any other purpose. One idea about how to do this, is to increment a counter on each call of the game update handler. Given this callback is called once per frame and DizzyAGE games usually have 36 frames per second (G_FPS), you can come up with a timing formula.

However, this might not be very exact, since sometimes there are not exactly 36 frames per second. Not to mention, if the player has a very old PC, that hardly can sustain this frame rate.

So, a better solution is to use the time tracking function, provided by the GS9 language: gs_time.
It will return the internal computer timer, in milliseconds (1 second is 1000 milliseconds).

The basic idea is to use the difference of milliseconds, elapsed since the last frame, and grow a global timer variable that stores the time. Here are a few useful functions, that could be placed in util.gs or in a similar file.

/////////////////////////////////////////////////////////////////////////////////
// Gameplay time counter
/////////////////////////////////////////////////////////////////////////////////
int g_timer_lasttick;

// call on begin game callback (BeginNewGame) to reset timer
func TimerReset()
{
	g_timer_lasttick = 0;
	GameSet(G_TIMER,0);
}

// call on load callback (LoadUserData)
func TimerOnLoad()
{
	g_timer_lasttick = 0;
}

// update, call on the game update handler
func TimerUpdate()
{
	if(g_timer_lasttick==0) g_timer_lasttick = gs_time();
	timer_currenttick = gs_time();
	delta = timer_currenttick - g_timer_lasttick;
	timer = GameGet(G_TIMER);
	if(delta>0) timer += delta;
	GameSet(G_TIMER,timer);
	g_timer_lasttick = timer_currenttick;
}

// call with reference paramters to get the play time
func TimerGetTime( hours, minutes, seconds )
{
	timer = GameGet(G_TIMER)/1000; // seconds
	*hours = timer / 3600;
	*minutes = (timer / 60) % 60;
	*seconds = timer % 60;
}

// debug display of the elapsed time
func TimerPrint()
{
	h=0; m=0; s=0;
	TimerGetTime(&h,&m,&s);
	println(h,":",m,":",s);
}

Feel free to improve or adjust it to match your game's particular needs.

How to localize your game?

To localize a game means to have different aspects customized for players in specific locations. There are many ways you can customize your DizzyAGE game. And there are more levels of localization.

Of course, one way would be to duplicate the game, give it to someone to translate it and have a version for each supported language. But then, what if you have to fix a bug, or change some part of it. You'll have to do it for each version. And that can easily generate problems.

A better way is to separate those resources that are changed in the localized version, and load only the appropriate ones, when the game starts, or even during gameplay.

Let's now have a look at the common aspects of games localization.

1. The language

This is the most common aspect of localization. One way to localize the game's language is to keep separate files for each supported language, containing all the game's text messages. The messages can be global variables (or defines) in the script, like TXT1, TXT2, TXT3, etc. Instead of writing Message(x,y,"house"), write Message(x,y,TXT1) and have a global string variable, TXT1, with the value "house", placed in a separate file.

This way, you can easy copy and translate only the file containing the game's texts. When the game starts, you can load the file coresponding to the desired language.

As a technical observation, you can use gs_compilefile(filepath) to compile script files at run time. However, you must consider that, when a function using a global variable (or a define) is compiled, it must have that global variable declared, even if it has a default value. Otherwise, it will consider it to be an undefined local variable.

In other implementations, you can use gs_dofile(filepath) to compile a script file as it would be the body of a function.

Have a look at the TextWorks tool. It can help you extract text strings from your script files and replace them with define tags. Always make a backup, before working with such a tool.

2. Fonts

DizzyAGE v2.2 supports custom fonts (for details check the manual).

Consider that some languages require different fonts to show their specific characters, like for example the russian languge. These special characters have different ASCII codes, and to be used, they must be included in the game's font.

One, way to localize fonts is to load them all and select which one to use, depending on the desired language.

If there are too many different fonts, you can have different versions of the same font, with the same ID, and only load the font you need, when the game starts. You'll have to place the font tile (.tga) and the font format (.fnt) files in folders separated from the common resources, so you can choose which one to load.

Remember that DizzyAGE v2.2 also supports groups for the loaded resources, so you can unload only the old font resources, before loading the new ones.

3. Tiles

Sometimes, you can have tiles containg text or visual signs that you want to localize. As for font resources, you should place these tiles in separate folders and only load the ones for the current selected language.

For an implementation example, have a look at the Local Demo, that shows how to select between three different languages.

How to rename the game executable?

You can simply rename the dizzy.exe to mygame.exe for example and it will load mygame.pak, mygame.ini and will log messages in mygame.log. However, you should adjust the setup internal resource script, to accomodate this change (the setup assumes the game is dizzy.exe). Use a resources editor for that.

How to rename the readme file?

The setup.exe opens the readme file from the "about" page. It supports custom readme file. In dizzy.inf set the "game_readme" to the file you want (ex: game_readme="mygame.pdf"). If this option is not mentioned, it will look for "readme" files with .txt, .html, .doc, and .pdf extentions.

How to use an external installer?

The setup.exe can be integrated with an external installer, like Inno Setup. It will detect executable files starting with "install" or "unins" and will auto adjust it's install and uninstall options to launch these files. For an example check "Dizzy and The Other Side" and it's installer from the cd cover page.