Matrix Engine

Features

• One global speed variable manages game speed: global.speed_modifier.
• A persistent alarm manager object manages all alarms and timers.
• Helper functions keep alarms and timers accurate as game speed changes.
• Time-dilation functions make it easy to switch instantly or smoothly from one speed to another.
• Image-speed helpers keep animated objects visually synchronised with the current game speed.

Licence

You may use the Matrix Engine in personal or commercial projects.

Credit is not required, but is appreciated.

How to Use

Place obj_alarm_manager into a room at the start of your game, before any Matrix Engine alarms or timers are created.

The object is persistent and only needs to be created once.

Main Functions

The asset contains four related groups of functions: alarm management, timer management, time dilation and image-speed management.

Alarm Management

Timer Management

Time Dilation

Image Speed

Object animation speeds must also be updated so that animations look correct at the current game speed.

Alarm Function Arguments

Arguments marked Optional do not need to be supplied.

Timer Function Arguments

Time Dilation and Image Speed Arguments

Usage Examples

The following examples show common game scenarios for every Matrix Engine function. Function and timer names are only examples and may be replaced with names that suit your project.

Alarm Management Examples

alarm_set_ext("scan", MATRIX_SEC * 5, id, 3, scan_area);

alarm_set_ext(
    "meteor_strike",
    MATRIX_SEC * 2,
    id,
    0,
    launch_meteor,
    [target_x, target_y]
);

var _frames_remaining = alarm_get_ext("shotgun_reload", id);
var _seconds_remaining = ceil(_frames_remaining / MATRIX_SEC);

if (alarm_get_ext("energy_shield", id) <= MATRIX_SEC)
{
    shield_flash_warning = true;
}

alarm_set_state("hack_complete", alarm_state.paused, id);

alarm_set_state("floor_trap", alarm_state.active, id);

if (alarm_get_state("craft_item", id) == alarm_state.paused)
{
    draw_text(x, y - 32, "Crafting Paused");
}

if (alarm_get_state("door_close", id) == alarm_state.active)
{
    alarm_set_state("door_close", alarm_state.paused, id);
}

if (!alarm_exists("spawn_reinforcements", id))
{
    alarm_set_ext("spawn_reinforcements", MATRIX_SEC * 8, id, 0, spawn_squad);
}

rage_buff_active = alarm_exists("rage_buff", id);

alarm_destroy("self_destruct", id);

if (quest_cancelled)
{
    alarm_destroy("quest_reminder");
}

if (alarm_check_game_paused())
{
    draw_text(32, 32, "Paused");
}

Timer Management Examples

timer_create("survival_time");

timer_create("sprint_duration", id);

var _survival_seconds = floor(timer_get_elapsed("survival_time") / MATRIX_SEC);

var _charge_frames = timer_get_elapsed("charge_attack", id);
charge_power = clamp(_charge_frames / (MATRIX_SEC * 3), 0, 1);

timer_set_state("dialogue_read_time", timer_state.paused);

timer_set_state("lap_time", timer_state.active, id);

lap_timer_running =
    timer_get_state("lap_time", id) == timer_state.active;

if (timer_get_state("mission_clock") == timer_state.paused)
{
    timer_set_state("mission_clock", timer_state.active);
}

if (!timer_exists("combo_time", id))
{
    timer_create("combo_time", id);
}

speedrun_active = timer_exists("speedrun_clock");

timer_destroy("lap_time", id);

if (challenge_failed)
{
    timer_destroy("no_damage_challenge");
}

if (timer_exceeded_frames("rocket_reload", MATRIX_SEC * 8, id))
{
    rocket_ready = true;
}

if (timer_exceeded_frames("survival_time", MATRIX_SEC * 300))
{
    achievement_unlock("survive_five_minutes");
}

Time Dilation Examples

dilation_set_speed(0.25);

dilation_set_speed(1, MATRIX_SEC * 2);

var _speed_percent = round(dilation_get_speed() * 100);
draw_text(32, 32, "Game Speed: " + string(_speed_percent) + "%");

if (dilation_get_speed() < 1)
{
    draw_set_alpha(0.35);
    draw_rectangle(0, 0, room_width, room_height, false);
    draw_set_alpha(1);
}

if (!dilation_is_transitioning())
{
    dilation_set_speed(0.4, MATRIX_SEC);
}

if (dilation_is_transitioning())
{
    draw_text(32, 64, "Time speed changing...");
}

var _target_percent = round(dilation_get_target_speed() * 100);
draw_text(32, 96, "Target Speed: " + string(_target_percent) + "%");

if (dilation_get_target_speed() < dilation_get_speed())
{
    audio_play_sound(snd_time_slow, 0, false);
}
else
{
    audio_play_sound(snd_time_restore, 0, false);
}

Image Speed Examples

image_speed_set(0.2);

if (is_sprinting)
{
    image_speed_set(0.35);
}
else
{
    image_speed_set(0.15);
}

image_speed_step();

if (sprite_get_number(sprite_index) > 1)
{
    image_speed_step();
}

Object Movement and Image Speed

Time-scaled movement

Any movement that should respond to time dilation must be multiplied by SPEED_MOD. This macro represents global.speed_modifier.

At normal speed, SPEED_MOD is 1. At half speed it is 0.5, and at double speed it is 2. Multiplying movement by this value keeps objects moving at the same relative rate as the rest of the game.

x += move_speed * SPEED_MOD;

x += lengthdir_x(move_speed, direction) * SPEED_MOD;
y += lengthdir_y(move_speed, direction) * SPEED_MOD;

Time-scaled image speed

Whenever an instance's animation speed should respond to time dilation, use image_speed_set(_speed) instead of assigning directly to the built-in image_speed variable.

For example, replace:

image_speed = 0.2;

with:

image_speed_set(0.2);

The value supplied to image_speed_set() is the animation speed the object should use while the game is running at normal speed.

Any object whose animation is affected by time dilation must also call image_speed_step() once every frame. The object's Step event is usually the best location:

image_speed_step();

Additional Information

• Do not set any Matrix Engine alarms or timers before obj_alarm_manager has been created.
• When assigning an alarm or timer to an object, pass the actual instance ID rather than only the object asset name. Otherwise, the alarm or timer may be applied to the wrong instance of that object type.

Additional Information for HTML Builds

In an HTML build, the game may freeze when executing a fallback check that uses:

This fallback is used in case an object type was passed instead of an instance ID. For HTML builds, comment out blocks that use this check.

After removing the fallback, ensure that every function receives a valid instance ID whenever an instance-specific alarm or timer is required.