Introduction Welcome Getting Started My First Program     Troubleshooting and Distributing Transforming Data Interactive Programs     Programming Exercises     Making Games
Documentation Declarations     Procedures     Variables Statements     Flow Control Expressions Libraries     Print     IO     Random     Game Engine
Tutorials Complete Tutorials     Introduction to Programming     Quick Start     Programming Exercises     Programming Games

LIBRARY: GAME ENGINE


All About the Game Engine Library in Vizzcode





About the Game Engine Library

The Game Engine library is complete toolkit for you to create games with inside Vizzcode.
It has all sorts of features to help your imagination become real by programming real games you can play and distribute. Anything from rendering, audio, object systems, collision detection and so on. This library was specifically made to teach you the fundamentals of game programming. These fundamentals are essential to know, no matter what game engine you might use in the future.

This page focuses on breaking down what is actually inside the library, in a technical sense. If you want to learn how to make games, you can check out the Making Games page or the Complete Tutorials.




How to Use It

Firstly, you have to import the library:

#import
"GameEngine"

By doing so, the program becomes a window application (in contrast to the default console application mode). This means the command prompt doesn't show up anymore when you launch your program, but it also means you have different ways to make your software interactable.

Game Loop

Like explained in more detail in the Making Games page and the Complete Tutorials, because players continually interact with the game, you must created a basic loop for the game.
The Game Loop is responsible for generating a frame the user will see on the screen and to update the game according to the input. The Game Loop using the Game Engine library looks like this:
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
    }
}

Creating a Game Loop with visual programming in Vizzcode

The basic idea is that while the game is running, certain things will happen. What will happen depends on the game, could be shooting a bullet, could be testing if the enemies are dead and so one.
Be sure to see the Making Games page and the Complete Tutorials for examples and tutorials.

The following sections explain in detail each procedure you can use to interface with the Game Engine library.




API Part 1: Basic Features and Input

game_is_running

This is the declaration of the game_is_running procedure:
game_is_running
:: () -> is_running :
bool
{

This procedure should be called in the beginning of every iteration of the Game Loop.
It updates the entities as specified in the previous frame, generate and display the frame and reads input for the next frame.
It returns whether or not the game should continue to run. The game stops running if the user closes the window, for example.

Here is how to use it:
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
    }
}

Creating a Game Loop with visual programming in Vizzcode



set_window_options

This is the declaration of the set_window_options procedure:
set_window_options
:: (title :=
"Game"
, full_screen :=
false
, size_x :=
1280
, size_y :=
720
) {

The declaration of the procedure set_window_options

This procedure should be called before the first iteration of the Game Loop (before calling game_is_running for the first time).
It can set several windows configurations.
The title parameter changes the name of the window.
The full_screen parameter specifies whether or not the game should be launched in fullscreen mode. (If not, it launchers as overlapped window.
The size_x and size_y values are used to set the window size. They are ignored if the window launches in fullscreen.
#import
"GameEngine"


main
:: () {
    
set_window_options
(
"My Awesome Game!"
,
true
);
    
while
game_is_running
() {
    }
}

Setting the window options in Vizzcode's Game Engine



hide_cursor

This is the declaration of the hide_cursor procedure:
hide_cursor
:: () {

This procedure is used to hide the default operating system cursor.
The cursor's position can still queried with the get_mouse_position and set_mouse_position, as well as cursor collision with object_is_under_cursor.
It's common for games to hide the default operating system cursor and draw a bitmap (draw_bitmap) of their own on the cursor's position.
#import
"GameEngine"


main
:: () {
    
hide_cursor
();
    
while
game_is_running
() {
    }
}

Hiding the cursor in Vizzcode's Game Engine



get_delta_seconds

This is the declaration of the get_delta_seconds procedure:
get_delta_seconds
:: () -> delta_seconds :
float
{

This procedure returns how much time passed (in seconds) in the last run of the Game Loop.
It is meant to be called from inside the Game Loop. In the first iteration of the loop it returns the value 0.01666 because running the monitor at 60Hz is the most common configuration for users.

The value of the delta_seconds should be used to make frame-rate independent movement. For example: If you move an object 1 unit to the right every frame the motion will vary depending on how the user is running the game (higher frame rate would mean faster objects). To avoid this, you can multiply the unit by the delta_seconds resulting in how many units that object moves in one second.
Another very import use for delta_seconds is timers. By adding that value to a variable every frame you get a timer.
Note that the delta_seconds values is capped at 0.05s. This means that even if for some reason a frame takes longer than that, this will be the value returned. This is done to avoid very large values messing up with the physics update.

Here is an example of its use:
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
        delta_seconds :=
get_delta_seconds
();
    }
}

Using the get_delta_seconds procedure in Vizzcode's Game Engine



get_current_time

This is the declaration of the get_current_time procedure:
get_current_time
:: () -> game_time_in_seconds :
float
{

This procedure returns how much time passed from the very beginning of the game.
If you add the delta_seconds (see get_delta_seconds) every frame, you should find matching values.
It is meant to be called from inside the Game Loop.
This value is particularly useful for creating timers.
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
        time_that_passed :=
current_time
();
    }
}


random_int_in_range

This is the declaration of the random_int_in_range procedure:
random_int_in_range
:: (min_inclusive :=
0
, max_inclusive :=
10
) -> random_value :
int
{

This procedure is exactly the same as in the Random library.
This procedure generates and returns a random integer number between the specified range.
The range is inclusive, which means the minimum and maximum numbers can show up in random result.
#import
"GameEngine"


main
:: () {
    random :=
random_int_in_range
(
0
,
10
);
}

An example of random_int_in_range



random_float_in_range

This is the declaration of the random_float_in_range procedure:
random_float_in_range
:: (min_inclusive :=
0.0
, max_inclusive :=
1.0
) -> random_value :
float
{

This procedure is exactly the same as in the Random library.
This procedure generates and returns a random float number between the specified range.
The range is inclusive, which means the minimum and maximum numbers can show up in random result.
It works just like the random_int_in_range procedure.
#import
"GameEngine"


main
:: () {
    random :=
random_float_in_range
(
-10.0
,
10.0
);
}

An example of random_float_in_range



button_is_down

This is the declaration of the button_is_down procedure:
button_is_down
:: (button :=
"space"
) -> is_down :
bool
{

This one of three procedures to query keyboard (and mouse button) input. The others are button_pressed and button_released.
The parameter is a string value containing one of the following values:
  • up: The UP arrow key
  • down: The DOWN arrow key
  • left: The LEFT arrow key
  • right: The RIGHT arrow key
  • w: The W key
  • a: The A key
  • s: The S key
  • d: The D key
  • f: The F key
  • r: The R key
  • e: The E key
  • q: The Q key
  • z: The Z key
  • c: The C key
  • x: The X key
  • v: The V key
  • 1: The 1 key
  • 2: The 2 key
  • 3: The 3 key
  • 4: The 4 key
  • 5: The 5 key
  • 6: The 6 key
  • 7: The 7 key
  • 8: The 8 key
  • 9: The 9 key
  • 0: The 0 key
  • space: The SPACE BAR key
  • shift: The SHIFT key
  • ctrl: The CTRL key
  • enter: The ENTER/RETURN key
  • tab: The TAB key
  • escape: The ESCAPE/ESC key
  • lmb: The LEFT MOUSE BUTTON
  • rmb: The RIGHT MOUSE BUTTON
The procedure returns true if the user is pressing the button in this frame.
For example, if the user holds the key for 10 consecutive frames, the procedure will return true for these 10 frames and false for the rest of the frames (because the button is not down).
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
        
if
button_is_down
(
"enter"
) {
            
draw_rectangle
();
        }
    }
}

Reading user input in the game



button_pressed

This is the declaration of the button_pressed procedure:
button_pressed
:: (button :=
"space"
) -> pressed :
bool
{

This one of three procedures to query keyboard (and mouse button) input. The others are button_is_down and button_released.
The parameter is a string value containing one of the following values:
  • up: The UP arrow key
  • down: The DOWN arrow key
  • left: The LEFT arrow key
  • right: The RIGHT arrow key
  • w: The W key
  • a: The A key
  • s: The S key
  • d: The D key
  • f: The F key
  • r: The R key
  • e: The E key
  • q: The Q key
  • z: The Z key
  • c: The C key
  • x: The X key
  • v: The V key
  • 1: The 1 key
  • 2: The 2 key
  • 3: The 3 key
  • 4: The 4 key
  • 5: The 5 key
  • 6: The 6 key
  • 7: The 7 key
  • 8: The 8 key
  • 9: The 9 key
  • 0: The 0 key
  • space: The SPACE BAR key
  • shift: The SHIFT key
  • ctrl: The CTRL key
  • enter: The ENTER/RETURN key
  • tab: The TAB key
  • escape: The ESCAPE/ESC key
  • lmb: The LEFT MOUSE BUTTON
  • rmb: The RIGHT MOUSE BUTTON
The procedure returns true in the frame the user started the button press.
For example, if the user holds the key for 10 consecutive frames, the procedure will return true for the first frame of this 10-frame sequence (the frame the user begun pressing the button) and false for the rest of the frames.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    ...
    
while
game_is_running
() {
        
if
button_pressed
(
"enter"
) {
            
spawn_particles
(...);
        }
    }
}



button_released

This is the declaration of the button_released procedure:
button_released
:: (button :=
"space"
) -> released :
bool
{

This one of three procedures to query keyboard (and mouse button) input. The others are button_is_down and button_pressed.
The parameter is a string value containing one of the following values:
  • up: The UP arrow key
  • down: The DOWN arrow key
  • left: The LEFT arrow key
  • right: The RIGHT arrow key
  • w: The W key
  • a: The A key
  • s: The S key
  • d: The D key
  • f: The F key
  • r: The R key
  • e: The E key
  • q: The Q key
  • z: The Z key
  • c: The C key
  • x: The X key
  • v: The V key
  • 1: The 1 key
  • 2: The 2 key
  • 3: The 3 key
  • 4: The 4 key
  • 5: The 5 key
  • 6: The 6 key
  • 7: The 7 key
  • 8: The 8 key
  • 9: The 9 key
  • 0: The 0 key
  • space: The SPACE BAR key
  • shift: The SHIFT key
  • ctrl: The CTRL key
  • enter: The ENTER/RETURN key
  • tab: The TAB key
  • escape: The ESCAPE/ESC key
  • lmb: The LEFT MOUSE BUTTON
  • rmb: The RIGHT MOUSE BUTTON
The procedure returns true in the frame the user releases the button.
For example, if the user holds the key for 10 consecutive frames, then releases the button in the 11th frame, the procedure will return true only in the 11th frame (the frame the user let go of the button after pressing it for some time) and false for the rest of the frames.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    ...
    
while
game_is_running
() {
        
if
button_released
(
"enter"
) {
            
spawn_particles
(...);
        }
    }
}



get_mouse_position

This is the declaration of the get_mouse_position procedure:
get_mouse_position
:: () -> position_x :
float
, position_y :
float
{

The procedure returns the x and y float position of the mouse cursor this frame.
It is in standard (world-space) units, not pixel-space.
To retrieve both return values (as usual) you must use a compound declaration. You can learn more about multiple return values here. You can set the mouse cursor with the set_mouse_position procedure.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
        mouse_x, mouse_y :=
get_mouse_position
();
        
draw_rectangle
(mouse_x, mouse_y);
    }
}

Getting the mouse position



set_mouse_position

This is the declaration of the set_mouse_position procedure:
set_mouse_position
:: (x :=
0.0
, y :=
0.0
) {

The procedure moves the mouse cursor to the specified position.
It is in standard (world-space) units, not pixel-space.
If you set the mouse cursor every frame, you will essentially "lock" the mouse cursor in place.
It's very common to use this in game to lock the mouse in the center of the screen (0, 0) and only consider the delta movement of the mouse. This will make sure the mouse is never "stuck" on one of the borders of the screen, because it is reset every frame to the center.

You can get the mouse cursor with the get_mouse_position procedure.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
        
set_mouse_position
();
    }
}





API Part 2: Immediate Drawing

clear_screen

This is the declaration of the clear_screen procedure:
clear_screen
:: (colorred :=
1.0
, color_green :=
1.0
, color_blue :=
1.0
) {

Setting the entire screen to a solid color in the game

This procedure immediately paints the entire screen area with a solid color.
It uses RGB colors from 0 to 1.
Like the other immediate draw routines, this procedure is drawn in the moment it is called inside the frame, before drawing the objects.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
        
clear_screen
(
.2
,
1
,
.75
);
    }
}


draw_rectangle

This is the declaration of the draw_rectangle procedure:
draw_rectangle
:: (position_x :=
0.0
, position_y :=
0.0
, size_x :=
5.0
, size_y :=
5.0
, color_red :=
1.0
, color_green :=
1.0
, color_blue :=
1.0
, color_alpha :=
1.0
) {

How to draw a rectangle on the screen in Vizzcode

This procedure immediately draws a rectangle on the screen with a solid color.
It uses standard (world) coordinates. The colors are RGB colors from 0 to 1.
The alpha component of the color controls the rectangle's opacity - where 0.0 is fully transparent and 1.0 is fully opaque.
Like the other immediate draw routines, this procedure is drawn in the moment it is called inside the frame, before drawing the objects.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
        
draw_rectangle
(position_x=
10
, position_y=
-5.5
, size_x=
2
, size_y=
8
, color_red=
0.5
, color_green=
1
, color_blue=
0.25
, color_alpha=
0.5
);
    }
}


draw_bitmap

This is the declaration of the draw_bitmap procedure:
draw_bitmap
:: (file_name :=
"file.png"
, position_x :=
0.0
, position_y :=
0.0
, size :=
5.0
) {

How to draw an image to the screen in Vizzcode

This procedure immediately draws an specified image on the screen.
The image must be on the .png format.
The procedure looks for the image in the specified path relative to the executable (or wherever the application's working directory is). If no valid PNG image is found, this procedure draws nothing.
The procedures uses standard (world) coordinates.
This procedure is great for drawing background elements without having to create objects.
They are also very useful if you want to use the Game Engine as a rendering tool and disconsider its object system entirely.
Like the other immediate draw routines, this procedure is drawn in the moment it is called inside the frame, before drawing the objects.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
        
draw_image
(
"assets/background.png"
);
    }
}


draw_text

This is the declaration of the draw_text procedure:
draw_text
:: (text :=
"Hello!"
, position_x :=
0.0
, position_y :=
0.0
, size :=
5.0
) {

How to draw a text to the screen in Vizzcode

This procedure immediately draws a text string on a specified location on the screen.
It uses standard (world) coordinates.
This procedure is great for prototyping menus and User Interfaces before implementing the final art (that could be a png image, for example).
Like the other immediate draw routines, this procedure is drawn in the moment it is called inside the frame, before drawing the objects.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    
while
game_is_running
() {
        
draw_text
(
"Nice Text!"
);
    }
}


draw_int

This is the declaration of the draw_int procedure:
draw_int
:: (value_to_draw :
int
, position_x :=
0.0
, position_y :=
0.0
, size :=
5.0
) {

How to draw a number to the user's screen in Vizzcode

This procedure immediately draws any int value on a specified location on the screen.
It uses standard (world) coordinates.
Like the other immediate draw routines, this procedure is drawn in the moment it is called inside the frame, before drawing the objects.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    score :=
0
;
    
while
game_is_running
() {
        
draw_int
(score);
    }
}


draw_float

This is the declaration of the draw_float procedure:
draw_float
:: (value_to_draw :
float
, position_x :=
0.0
, position_y :=
0.0
, size :=
5.0
, number_of_decimals :=
2
) {


How to draw a floating point number to the user's screen in Vizzcode

This procedure immediately draws any float value on a specified location on the screen.
It uses standard (world) coordinates.
You can specify the number of decimal digits to display.
Like the other immediate draw routines, this procedure is drawn in the moment it is called inside the frame, before drawing the objects.
It is meant to be called from inside the Game Loop.
#import
"GameEngine"


main
:: () {
    some_float :=
random_float_in_range
(
1.0
,
2.0
);
    
while
game_is_running
() {
        
draw_float
(some_float);
    }
}




API Part 3: Sound and Basic Object System

play_sound

This is the declaration of the play_sound procedure:
play_sound
:: (file_name :=
"file.wav"
, looping_sound :=
false
, variation :=
0.0
, volume :=
1.0
) -> sound_id :
int
{

How to play a sound file in the game using Vizzcode

This procedure plays a sound file, with several options.
The sound file must be in the .wav PCM format, encoded at 44.100Hz with 1 or 2 channels.
The procedure looks for the sound file in the specified path relative to the executable (or wherever the application's working directory is). If no valid WAV sound is found, this procedure plays nothing.
You can set the looping_sound parameter to true and the sound will restart as soon as it ends. This parameters is great for music files that should keep playing while the game is running.
The variation parameters will add a random value to the volume and to the pitch of the sound. This parameter is very useful for repetitive sounds (such as shots, explosions, etc) so that they don't sound repetitive and dull. The pitch variation will slightly speed up or down the sound to achieve the desired pitch change. The volume parameter should be set from 0 (completely muted) to 1 (normal volume) or slightly over 1 to sound louder. If you set the volume to a much larger value, it may start to clip.
The procedure returns an ID for the sound (also referred to as a handle). This ID can be passed on to the set_sound_volume to change the volume of an existing sound.
This procedure can be called from anywhere in the program.
#import
"GameEngine"


main
:: () {
    
play_sound
(
"epic_music.wav"
);
    
while
game_is_running
() {
    }
}


set_sound_volume

This is the declaration of the set_sound_volume procedure:
set_sound_value
:: (sound_id :
int
, volume :=
0.0
, fading_speed :=
3.0
) {

How to change the volume of a playing sound in Vizzcode

This procedure changes the volume of a playing sound.
The sound must already be playing with the play_sound procedure. The return value of the play_sound is the value that should be passed as the sound_id parameter to modify that sound.
The volume parameter works just like the play_sound sound parameter: it should be set from 0 (completely muted) to 1 (normal volume) or slightly over 1 to sound louder. If you set the volume to a much larger value, it may start to clip.
The fading_speed parameter can be arbitrarily changed to make the volume change faster or slower. The greater the fading_speed parameter the faster the sound will move towards the newly specified volume.
This procedure can be called from anywhere in the program.
#import
"GameEngine"


main
:: () {
    music :=
play_sound
(
"epic_music.wav"
);
    
while
game_is_running
() {
        
if
button_pressed
() {
            
set_sound_volume
(music,
0
);
        }
    }
}


create_object

This is the declaration of the create_object procedure:
create_object
:: (size_x :
5.0
, size_y :=
5.0
) -> object_id :
int
{

How to create an object in the game using Vizzcode

This is the base procedure to use the Game Engine's object system.
The object system is very useful to manage the objects in the game. These objects (also referred to as actors or entities) can be specified and then simulated by the game engine. You can then query collision on these objects, specify how they look or move.

The create_object procedure is the first procedure to be called to use the object system.
You can specify the size of the object with this procedure. (If you associate an image to this object later on, you can use that image's dimensions; in that case you can ignore the create_object's size.
This procedure returns the object id (also referred to handle). Saving this id to a variable is extremely important to be able to specify additional parameters to the object as well as spawning it.

Spawning the object is very necessary part of the object system, the create_object procedure just creates a "blank canvas" for you to specify additional information on the objects and then spawn them.
This procedure should be called before the Game Loop.
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
while
game_is_running
() {
    }
}


spawn_object

This is the declaration of the spawn_object procedure:
spawn_object
:: (object_id :
int
, position_x :=
0.0
, position_y :=
0.0
) -> instance_id :
int
{

How to spawn an object in the game using Vizzcode

This procedure creates an instance of an object in the game world.
The object must have been already created with the create_object procedure. The return value of the create_object should be sent to the object_id parameter.

By calling spawn_object, an instance of the object will be created in the world at the specified position.
This procedure can be called anywhere in the program.
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
spawn_object
(game_object,
10
,
-20
);
    
while
game_is_running
() {
    }
}


destroy_instance

This is the declaration of the destroy_instance procedure:
destroy_instance
:: (instance_id :
int
) {

How to destroy an object in the game using Vizzcode

This procedure destroys an instance of an object that exists in the game world.
You can get the instance id by saving the return value of spawn_object or by calling one of the instance querying procedure (get_first_instance, get_random_instance, get_next_instance).
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    instance_id :=
spawn_object
(game_object,
10
,
-20
);
    
while
game_is_running
() {
        
if
button_pressed
() {
            
destroy_instance
(instance_id);
        }
    }
}

A working example of a game where you can destroy objects



get_instance_count

This is the declaration of the get_instance_count procedure:
get_instance_count
:: (object_id :
int
) -> instance_count :
int
{

This procedure returns the number of active instances spawned in the world of a certain object.
You need to pass an object_id that was returned in a create_object procedure.
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
spawn_object
(game_object,
10
,
-20
);
    
while
game_is_running
() {
        instance_count :=
get_instance_count
(game_object);
        
draw_int
(instance_count);
    }
}

An example of get_instance_count



get_first_instance

This is the declaration of the get_first_instance procedure:
get_first_instance
:: (object_id :
int
) -> instance_id :
int
{

This procedure returns the instance_id of the first instanced spawned of a certain object_id.
You need to pass an object_id that was returned in a create_object procedure.
This is particularly useful to use in objects that only have one spawned instance (like a player object, for instance).
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
spawn_object
(game_object,
10
,
-20
);
    
while
game_is_running
() {
        
if
button_pressed
() {
            
destroy_instance
(
get_first_instance
(game_object));
        }
    }
}

How to get the first instance of a game object



get_random_instance

This is the declaration of the get_random_instance procedure:
get_random_instance
:: (object_id :
int
) -> instance_id :
int
{

The declaration of get_random_instance

This procedure returns the instance_id of a random active instance of a certain object_id.
You need to pass an object_id that was returned in a create_object procedure.
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
spawn_object
(game_object,
10
,
-20
);
    
while
game_is_running
() {
        
if
button_pressed
() {
            
destroy_instance
(
get_random_instance
(game_object));
        }
    }
}


get_next_instance

This is the declaration of the get_next_instance procedure:
get_next_instance
:: (object_id :
int
) -> instance_id :
int
{

The declaration of get_next_instance

This procedure is used to incrementally get the id of all instances of a certain object.
For example, in a given frame, calling get_next_instance for the first time in that frame will return the first spawned instance's id.
The second time, it will return you the second spawned instance's id. The third time, the third instance's id and so on.
When all of the valid instances' ids were returned in that frame, the procedure will return zero.
When the frame is reset, the next instance counter is reset - making it return the first spawned instance's id again. You can manually reset this internal counter with reset_next_instance_counter.

This procedure is particularly useful to iterate through all the spawned instances of an object.
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
spawn_object
(game_object,
10
,
-20
);
    
while
game_is_running
() {
        instance :=
get_next_instance
(game_object);
        
while
instance !=
0
{
            ...
            instance =
get_next_instance
(game_object);
        }
    }
}


reset_next_instance_counter

This is the declaration of the reset_next_instance_counter procedure:
reset_next_instance_counter
:: (object_id :
int
) {

The declaration of reset_next_instance_counter

This procedure resets the internal counter of the get_next_instance procedure.
The get_next_instance procedure iteratively returns the ids of all the instances of an object. When all of the object's instances' ids are returned, the get_next_instance procedure returns zero (invalid index).
By calling reset_next_instance_counter the get_next_instance procedure will be reset and return the first instance's id again.
In the end of every frame the next instance counter is reset automatically.
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
spawn_object
(game_object,
10
,
-20
);
    
while
game_is_running
() {
        instance :=
get_next_instance
(game_object);
        
while
instance !=
0
{
            ...
            instance =
get_next_instance
(game_object);
        }
        
        
reset_next_instance_counter
(game_object);
        
        instance =
get_next_instance
(game_object);
        
while
instance !=
0
{
            ...
            instance =
get_next_instance
(game_object);
        }
    }
}




API Part 4: Object Parameters

set_object_bitmap

This is the declaration of the set_object_bitmap procedure:
set_object_bitmap
:: (object_id :
int
, file_name :=
"file.png"
, update_object_size :=
true
, new_size :=
5.0
) {

The declaration of set_object_bitmap

This procedure configures a certain object to use an image when that object is rendered.
The image must be on the .png format.
The procedure looks for the image in the specified path relative to the executable (or wherever the application's working directory is). If no valid PNG image is found, this procedure draws nothing.
If you set the update_object_size parameter to false, the object's size will not be changed and the new_size parameter is ignored. The image may be distorted if the object's size has a different aspect ratio.
If you set the update_object_size to true, the object's size will be overwritten by the new_size parameter. There is only one size value (in contrast to having x and y sizes, like in create_object) because the image aspect is maintained. The new_size parameter will be used as the smallest size of the image. The other size is calculated to be larger in such a way to keep the image aspect. For example: if the image is 320x160 pixels and you set the new_size to 5 units, the object size will be 10x5 units, keeping the size 5 on the smallest axis and setting the other axis to a value keeping the image aspect ratio (10 units in this case).
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
set_object_bitmap
(game_object,
"object_image.png"
,
true
,
15.0
);
    
spawn_object
(game_object);
    
while
game_is_running
() {
    }
}


set_object_color

This is the declaration of the set_object_color procedure:
set_object_color
:: (object_id :
int
, color_red :=
1.0
, color_green :=
1.0
, color_blue :=
1.0
, color_alpha :=
1.0
) {

The declaration of set_object_color

This procedure configures a color for the object to use when rendering.
If you set an object's bitmap with set_object_bitmap, the color you set with set_object_color will be multiplied by the image.
If there is no bitmap set, the color will be used as the fill color of the rectangle.
The colors are RGB colors from 0 to 1.
The alpha component of the color controls the object's opacity - where 0.0 is fully transparent and 1.0 is fully opaque.
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
set_object_color
(game_object,
1.0
,
.25
,
.75
,
0.5
);
    
spawn_object
(game_object);
    
while
game_is_running
() {
    }
}


set_object_color_as_random_color

This is the declaration of the set_object_color_as_random_color procedure:
set_object_color_as_random_color
:: (object_id :
int
, min_color_red :=
1.0
, min_color_green :=
1.0
, min_color_blue :=
1.0
, min_color_alpha :=
1.0
, max_color_red :=
1.0
, max_color_green :=
1.0
, max_color_blue :=
1.0
, max_color_alpha :=
1.0
) {

The declaration of set_object_color_as_random_color

This procedure configures a color range for the object to use when rendering.
Each instance of the object will select a random color in that range.
If you set an object's bitmap with set_object_bitmap, the color you set with set_object_color_as_random_color will be multiplied by the image.
If there is no bitmap set, the color will be used as the fill color of the rectangle.
The colors are RGB colors from 0 to 1.
The alpha component of the color controls the object's opacity - where 0.0 is fully transparent and 1.0 is fully opaque.
#import
"GameEngine"


main
:: () {
    game_object :=
create_object
();
    
set_object_color_as_random_color
(game_object,
1.0
,
0
,
1
,
0.5
);
    
spawn_object
(game_object);
    
spawn_object
(game_object,
10
);
    
spawn_object
(game_object,
20
);
    
while
game_is_running
() {
    }
}


set_object_particle_trail

This is the declaration of the set_object_particle_trail procedure:
set_object_particle_trail
:: (object_id :
int
, particle_object_id :
int
, particles_per_second :=
10.0
, outward_velocity :=
2.0
, outward_velocity_randomness :=
1.5
, size_randomness :=
2.0
, position_deviation :=
1.0
, lifetime_in_seconds :=
1.0
, lifetime_randomness :=
0.5
) {

The declaration of set_object_particle_trail

This procedure configures a certain objects to be a particle emitter.
This object will constantly spawn another object (called particle) at a certain rate.
The particles will follow certain movement rules (specified in the parameters). These rules will be added by the other movement parameters specified in the particle's object (with procedures such as set_object_constance_acceleration).

Parameters:
object_id: the ID of the emitter object
particle_object_id: the ID of the object that will be spawned as a particle
particles_per_second: the number of particles that will be emitted by the object per second
outward_velocity: this parameter controls the velocity of the particles moving away from the emitter
outward_velocity_randomness: to make particles look better and more unpredictable, it's very useful to add some randomness to the particles motion. This parameter adds a random factor to the outward velocity
size_randomness: a random factor that will be added to the particle object's size
position_deviation: a random factor that will be added to the particle's spawn location (deviating from the emitter object's position)
lifetime_in_seconds: how many seconds the particle will last before being destroyed - the particle will fade out during its lifetime
lifetime_randomness: a random factor that will be added to (or subtracted from) to particle's lifetime

#import
"GameEngine"


main
:: () {
    emitter :=
create_object
();
    particle :=
create_object
();
    
set_object_particle_trail
(emitter, particle);
    
spawn_object
(emitter);
    
while
game_is_running
() {
    }
}


set_object_movement

This is the declaration of the set_object_movement procedure:
set_object_movement
:: (object_id :
int
, movement :=
"player_all_directions"
) {

This procedure configures a certain object to be have a pre-determined movement behavior.
It is particularly useful for player movement and "follower" behavior.
If you specify a player movement with this procedure, you can configure its parameters (such as acceleration and friction) with the set_player_control procedure.
If you specify a follower movement, you must specify its parameters (the target to follow, as well as the acceleration and friction).
Here is an explanation of all the possible movement strings you can pass to this procedure:
  • player_up_down: allows the player to control this object moving up and down with the UP/DOWN arrow keys or the W/S keys
  • player_left_right: allows the player to control this object moving left and right with the LEFT/RIGHT arrow keys or the A/D keys
  • player_all_directions: allows the player to control this object moving left, right, up and down with the LEFT/RIGHT/UP/DOWN arrow keys or the W/A/S/D keys

  • player_up_down_wasd_only: allows the player to control this object moving up and down with the W/S keys
  • player_left_right_wasd_only: allows the player to control this object moving left and right with the A/D keys
  • player_all_directions_wasd_only: allows the player to control this object moving left, right, up and down with the W/A/S/D keys

  • player_up_down_arrow_only: allows the player to control this object moving up and down with the UP/DOWN arrow keys
  • player_left_right_arrow_only: allows the player to control this object moving left and right with the LEFT/RIGHT arrow keys
  • player_all_directions_arrow_only: allows the player to control this object moving left, right, up and down with the LEFT/RIGHT/UP/DOWN arrow keys

  • follow_up_down: sets the object as a follower on the y axis (following a target up and down)
  • follow_left_right: sets the object as a follower on the x axis (following a target left and right)
  • follow_all_directions: sets the object as a follower on every direction (following a target up, down, left and right)
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    
set_object_movement
(object,
"player_all_directions"
);
    
spawn_object
(object);
    
while
game_is_running
() {
    }
}

An example game where the player controls a square across the screen

#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    target :=
create_object
();
    
set_object_movement
(object,
"follow_left_right"
);
    
set_object_follow_options
(object, target);
    
spawn_object
(object,
-20
,
-20
);
    
spawn_object
(target,
20
,
20
);
    
while
game_is_running
() {
    }
}

An example game where an enemy follows a target



set_player_control

This is the declaration of the set_player_control procedure:
set_player_control
:: (object_id :
int
, acceleration :=
1500.0
, friction :=
10.0
) {

The declaration of set_player_control

This procedure configures the acceleration and friction of a player movement.
It only works if the object's movement was set to a "player" movement before calling this procedure. You can set the movement using the set_object_movement procedure.
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    
set_object_movement
(object,
"player_all_directions"
);
    
set_player_control
(object,
600
,
5
);
    
spawn_object
(object);
    
while
game_is_running
() {
    }
}


set_object_follow_options

This is the declaration of the set_object_follow_options procedure:
set_object_follow_options
:: (object_id :
int
, target_object_or_instance_id :
int
, acceleration :=
1000.0
, friction :=
10.0
) {

The declaration of set_object_follow_options

This procedure configures the target as well as the acceleration and friction of a follow movement.
It only works if the object's movement was set to a "follow" movement before calling this procedure. If fact, configuring the target with set_object_follow_options is required after setting an object's movement to "follow". You can set the movement using the set_object_movement procedure.
The target option could be an object id or an instance id. If it's an object id, the first instance of that object will be used as the target.
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    target :=
create_object
();
    
set_object_movement
(object,
"follow_left_right"
);
    
set_object_follow_options
(object, target);
    
spawn_object
(object,
-20
,
-20
);
    
spawn_object
(target,
20
,
20
);
    
while
game_is_running
() {
    }
}


set_object_constant_acceleration

This is the declaration of the set_object_constant_acceleration procedure:
set_object_constant_acceleration
:: (object_id :
int
, acceleration_x :=
0.0
, acceleration_y :=
0.0
) {

The declaration of set_object_constant_acceleration

This procedure configures the constant acceleration what will applied to the object.
This procedure is great for adding a "gravity" or "wind" movement to an object, or any acceleration-based movement.
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    
set_object_constant_velocity
(object, acceleration_y=
-20
);
    
spawn_object
(object,
-20
,
-20
);
    
while
game_is_running
() {
    }
}


set_object_constant_velocity

This is the declaration of the set_object_constant_velocity procedure:
set_object_constant_velocity
:: (object_id :
int
, velocity_x :=
0.0
, velocity_y :=
0.0
) {

The declaration of set_object_constant_velocity

This procedure configures the constant velocity what will applied to the object.
This procedure is great for creating a linear motion, like a projectile; or adding a sudden impulse, like a jump.
This value can be queried using get_object_constant_velocity.
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    
set_object_constant_velocity
(object,
-5
,
10
);
    
spawn_object
(object,
-20
,
-20
);
    
while
game_is_running
() {
    }
}


get_object_constant_velocity

This is the declaration of the get_object_constant_velocity procedure:
set_object_constant_velocity
:: (object_id :
int
) -> velocity_x :
float
, velocity_y :
float
{

The declaration of get_object_constant_velocity

This procedure returns the constant velocity of a certain object.
The value this procedure returns is the value that was set using the set_object_constant_velocity.
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    
set_object_constant_velocity
(object,
100
);
    
spawn_object
(object,
-20
,
-20
);
    
while
game_is_running
() {
        velocity_x, velocity_y :=
get_object_constant_velocity
(object);
    }
}




API Part 5: Instance Data, Collision, Scene System and Particles

get_instance_position

This is the declaration of the get_instance_position procedure:
get_instance_position
:: (instance_id :
int
) -> position_x :
float
, position_y :
float
{

This procedure returns the current position of an instance that is spawned in the world.
It uses standard (world) coordinates.
You can get the instance id by saving the return value of spawn_object or by calling one of the instance querying procedure (get_first_instance, get_random_instance, get_next_instance).
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    instance :=
spawn_object
(object,
-20
,
-20
);
    
while
game_is_running
() {
        position_x, position_y :=
get_instance_position
(instance);
    }
}

How to get an object's position in Vizzcode



set_instance_position

This is the declaration of the set_instance_position procedure:
set_instance_positoin
:: (instance_id :
int
, position_x :=
0.0
, position_y :=
0.0
) {

This procedure sets the position of an instance that is spawned in the world.
It uses standard (world) coordinates.
It is particularly useful to create custom movement for objects - not using the default movement procedures.
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    instance :=
spawn_object
(object);
    
while
game_is_running
() {
        
set_instance_position
(instance,
-10
,
10
);
    }
}

How to set an object's position in Vizzcode



set_instance_velocity

This is the declaration of the set_instance_velocity procedure:
set_instance_velocity
:: (instance_id :
int
, velocity_x :=
0.0
, velocity_y :=
0.0
) {

This procedure sets the constant velocity of an instance that is spawned in the world.
The instance's velocity set with this procedure is added to the object's velocity set with the set_object_constant_velocity procedure.
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    instance :=
spawn_object
(object);
    
set_instance_velocity
(instance, -10);
    
while
game_is_running
() {
    }
}

How to set an instance's velocity in Vizzcode



objects_collided

This is the declaration of the objects_collided procedure:
objects_collided
:: (object_1_id :
int
, object_2_id :
int
) -> collided :
bool
, instance_1_id :
int
, instance_2_id :
int
{

The node declaration of objects_collided

This procedure takes in two object ids and queries information about collisions between instances of those objects that occurred last frame.
For instance, if there are asteroids flying around the scene (instances of the asteroid object) and a player (instance of the player object), you might see if there was a collision between the player and any asteroid with the objects_collided procedure.

If there was a collision, the collided return value returns true and the instance_1_id returns the id of the instance of the object_1_id object that collided with an instance of the other object. Similarly, the instance_2_id returns the id of the instance of the object_2_id object that collided with an instance of the first object. With that information, you can selectively act on a specific instance that collided, like destroying it, querying its position, or anything else.
If there was no collision, the collided return value returns false and the other return values have invalid ids in them.

If there were multiple collisions, you can use this procedure to query all of them.
The first time you call objects_collided in the frame, it will return information about the first collision. The second time you call it, it will return information about the second collision. The third time, the third collision. And so on. Until all the collisions were queries. After returning information on all of that frame's collisions, the procedure will return no collision information (collided set to false and invalid instance_1_id and instance_2_id id values).
This is very useful to process all of the collisions between two specific objects that happened on a specific frame. You can do it by simply calling the procedure repeatedly (in a while loop, for example) and break out of the loop when the return value collided is set to false.
#import
"GameEngine"


main
:: () {
    object1 :=
create_object
();
    
spawn_object
(object1);
    object2 :=
create_object
();
    
spawn_object
(object2);
    
while
game_is_running
() {
        collided, instance_of_object_1, instance_of_object_2 :=
objects_collided
(object1, object2);
        ...
    }
}


object_is_under_cursor

This is the declaration of the object_is_under_cursor procedure:
object_is_under_cursor
:: (object_id :
int
) -> collided :
bool
, instance_id :
int
{


The node declaration of object_is_under_cursor

This procedure takes in an object_id and queries information about instances of this object that were under the mouse cursor last frame.

If there is an instance of this object under the mouse cursor (colliding with the point where it's located), the collided return value returns true and the instance_id returns the id of the instance of the object_id object that collided with the mouse cursor.
If there was no collision, the collided return value returns false and the instance_id return value returns an invalid id.

If there were multiple instances of this particular object under the mouse cursor, you can use this procedure to query all of them.
The first time you call object_is_under_cursor in the frame, it will return information about the first collision. The second time you call it, it will return information about the second collision. The third time, the third collision. And so on. Until all the collisions were queries. After returning information on all of that frame's collisions, the procedure will return no collision information (collided set to false and invalid instance_1_id and instance_2_id id values).
This is very useful to process all of the collisions between a specific object and the mouse cursor that happened on a specific frame. You can do it by simply calling the procedure repeatedly (in a while loop, for example) and break out of the loop when the return value collided is set to false.
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    
spawn_object
(object);
    
while
game_is_running
() {
        collided, instance_id :=
object_is_under_cursor
(object);
        ...
    }
}


get_current_scene

This is the declaration of the get_current_scene procedure:
get_current_scene
:: () -> scene_index :
int
{

This procedure is one of the ways you can use the scene system inside the Game Engine.
Scenes are simply world states (or a snapshot of the world) that contains data about what instances of objects are spawned in the world. You can save, set/reset, clear and get scenes - each with its respective procedure.

The get_current_scene procedure returns the scene_index of the current scene.
If no scene was set/reset, it returns the default scene id.
This procedure is very useful for testing the current states of the game, for example, if the current scene is the gameplay scene, you might want to have one behavior, if it's the menu scene, another one, and so on.

The following code spawns an instance of object in the world and save that world snapshot as scene_1. The get_current_scene returns the value of the scene_1 variable.
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    
spawn_object
(object);
    scene_1 :=
save_scene
();
    
while
game_is_running
() {
        current_scene :=
get_current_scene
();
        
if
current_scene == scene_1 {
            ...
        }
    }
}


save_scene

This is the declaration of the save_scene procedure:
save_scene
:: () -> scene_index :
int
{

This procedure is one of the ways you can use the scene system inside the Game Engine.
Scenes are simply world states (or a snapshot of the world) that contains data about what instances of objects are spawned in the world. You can save, set/reset, clear and get scenes - each with its respective procedure.

The save_scene procedure saves a scene (the world state, or, a snapshot of the world) and returns the scene_index of that scene. You can then store that scene index in a variable to reset the world to that scene (with the reset_scene procedure), compare it with the current scene (returned by get_current_scene) and so on.

The following code spawns an instance of object in the world and save that world snapshot as scene_1. The left mouse button destroys the object and the right mouse button resets the scene to the saved scene (returning the instance of the object to is place when the scene was saved).
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    
spawn_object
(object);
    scene_1 :=
save_scene
();
    
while
game_is_running
() {
        
if
button_pressed
(
"lmb"
)
            
destroy_instance
(
get_first_instance
(object));
        
if
button_pressed
(
"rmb"
)
            
reset_scene
(scene_1);
    }
}

An example program using the scene system in Vizzcode's Game Engine



clear_scene

This is the declaration of the clear_scene procedure:
clear_scene
:: () {

This procedure is one of the ways you can use the scene system inside the Game Engine.
Scenes are simply world states (or a snapshot of the world) that contain data about what instances of objects are spawned in the world. You can save, set/reset, clear and get scenes - each with its respective procedure.

The clear_scene procedure simply destroys every instance (and particle) that exists current in the world.
It's particularly useful when creating and saving multiple scenes at startup. For example, you can spawn several objects and save that scene, then clear the scene and spawn entirely different objects, to save it as another scene. The following code does exactly that.

#import
"GameEngine"


main
:: () {
    object_1 :=
create_object
();
    object_2 :=
create_object
();

    
spawn_object
(object_1);
    scene_1 :=
save_scene
();

    
clear_scene
();

    
spawn_object
(object_2);
    scene_2 :=
save_scene
();
    
while
game_is_running
() {
        ...
    }
}


reset_scene

This is the declaration of the reset_scene procedure:
reset_scene
:: (scene_to_reset :=
-1
) {

This procedure is one of the ways you can use the scene system inside the Game Engine.
Scenes are simply world states (or a snapshot of the world) that contain data about what instances of objects are spawned in the world. You can save, set/reset, clear and get scenes - each with its respective procedure.

The reset_scene procedure takes in a scene to reset the world to.
For example, if scene_1 contains one instance of an object; calling reset_scene(scene_1) will clear the scene (just like the clear_scene procedure) and restore that scene - inserting the saved instance.

The procedure can be called with its default argument -1 to reset the current_scene.
If no scenes were saved, it restores the instances in the world to the point they were right before the start of the game loop (the first call to game_is_running).
#import
"GameEngine"


main
:: () {
    object :=
create_object
();
    
set_object_constant_velocity
(object,
10
);
    
spawn_object
(object);
    
while
game_is_running
() {
        
if
button_pressed
(
"enter"
)
            
reset_scene
();
    }
}


spawn_particles

This is the declaration of the spawn_particles procedure:
spawn_particles
:: (particle_object_id :
int
, position_x :=
0.0
, position_y :=
0.0
, amount :=
20
, outward_velocity :=
5.0
, outward_velocity_randomness :=
2.0
, size_randomness :=
2.0
, lifetime_in_seconds :=
1.0
, lifetime_randomness :=
0.5
) {

How can I spawn particles in my game using Vizzcode

This procedure emits a particle burst in a specified location with specified parameters.
The particle burst is a one-time only event, like an explosion: it will only spawn particles the moment you call the procedure. But you can call spawn_particles very frequently to simulate a particle trail.
The particles will be follow certain movement rules (specified in the parameters). These rules will be added by the other movement parameters specified in the particle's object (with procedures such as set_object_constance_acceleration).

Parameters:
particle_object_id: the ID of the object that will be spawned as a particle
position_x: the X position of the center of the particle burst
position_y: the Y position of the center of the particle burst
amount: the number of particles that will be spawned
outward_velocity: this parameter controls the velocity of the particles moving away from the center
outward_velocity_randomness: to make particles look better and more unpredictable, it's very useful to add some randomness to the particles motion. This parameter adds a random factor to the outward velocity
size_randomness: a random factor that will be added to the particle object's size
lifetime_in_seconds: how many seconds the particle will last before being destroyed - the particle will fade out during its lifetime
lifetime_randomness: a random factor that will be added to (or subtracted from) to particle's lifetime

#import
"GameEngine"


main
:: () {
    particle :=
create_object
();
    
while
game_is_running
() {
        
if
button_pressed
()
            
spawn_particles
(particle);
    }
}