Hollywood Game Framework

release version 0.1



This document is a work in progress and will be updated. Same goes for my modules too...


last update: 27.09.2011


Modules:

 Hollywood Game Framework release: 27.09.2011
Samples:
 Hollywood Blocks v. 0.2

What is it?


Hollywood Game Framework is a collection of my helper and wrapper routines for Hollywood to aid creation of double buffered games and programs.


Currently it includes following modules:

 game.hws
 primitives.hws

Game module's purpose is to handle all the boring stuff:

 - timing
 - updating
 - drawing
 - game states

Primitives module provides basic primitives for framework:

 - point
 - rectangle
 - image

Basic program structure


Basic program structure consist of three functions, that user must override:

 ; Game setup function for the user.
 Function game.load()
	; Our game must override this dummy function.
 EndFunction


 ; Game update function for the user
 Function game.update(dt)
	; Our game must override this dummy function.
 EndFunction


 ; Game draw frame function for the user
 Function game.draw()
	; Our game must override this dummy function.   
 EndFunction

At first framework runs game.load() function, this is where you setup your program. After that it goes into infinite loop, where it calls game.draw() and game.update(dt) functions.

Default update rate for running this game loop is 50 fps.

Game update rate can be set with:

 game:setUpdateRate(fps)

You probably noticed the dt - parameter on the game.update(dt) function. Game framework passes this to the update function, when calling. It's purpose is to provide simple timing facilities to program and it simply is a delta time in seconds between the last two frames.


Game states


Game framework uses simple, but quite effective way of managing game states. Default game state, state 0 consist of game.draw() and game.update(dt) functions.

Additional game states can be registed using:

 
 game.state:register("name", state)

And set using:

 game.state:set("name")

A state is simply a table with init(), draw() and update(dt) functions. Let's take a look at the pause state as an example:

 ;
 ; Pause state: pause.hws
 ;


 pause = {}


 Function pause.draw()
	SetFont(#SANS,48)
	TextOut(#CENTER, #CENTER, "PAUSED")
 EndFunction


 Function pause.update(dt)
	If IsKeyDown("SPACE") Then game.state:set(0)
 EndFunction

But you said it should have a init() function too?

Game framework calls these special functions as events. If your game state doesn't need: init, draw or update events, they are not required.

Event order, when state is set:

 init -> draw -> update

After that, it loops:

 draw -> update

Controlling drawing operations


Game framework defaults to running draw event on every frame, even if nothing is really changed on screen. However, it's possible to manually control the drawing events.

You can do this by setting:

 game:drawAuto(False)

Now framework automatically only draws every first frame of a state.

you can manually set the draw event on for the duration of a next frame by using:

 game:drawOn()

You can also cancel drawing for the next frame:

 game:drawOff()

Primitives module


Point


Point is a table holding x, y pair.


To create a new point:

 newpoint = point:new( { x = 0, y = 0 } )

Or simply:

 newpoint = point:new()

This creates a point, where x = 0 and y = 0.


You can do math with points:


To add two points:

 p3 = p1:add(p2)

To subtract two points:

 p3 = p1:sub(p2)

To multiply a point with scalar:

 p2 = p1:mul(number)

To divide a point with scalar:

 p2 = p1:div(number)

Rectangle


Rectangle is a rectangular area and is defined by two points: min and max.


To create a new rectangle:

 r = rect:new( { min = { x = 0, y = 0 }, max = { x = 100, y = 100 } } )

This creates a new rectangle, with top left corner on ( 0, 0 ) and bottom right corner on ( 100, 100 ).

There are also some helper methods for rectangle:


You can add a point to rectangle's min and max points:

 r = r:addpt(p)

Naturally, you can also subtract a point from rectangle's min and max points:

 r = r:subpt(p)

If you want to know the width of a rectangle:

 w = r:dx()

If you want to know the height of a rectangle:

 h = r:dy()

It's possible to check if rectangle overlaps with another rectangle:

 overlaps = r:overlap(r2)

Also testing if the two rectangles are equal is possible:

 equal = r:eq(r2)