Time

Introduction

Timing is crucial to OpenBOR, as it is to most game engines. Understanding how the engine measures time, and how those measurements affect a project, is therefore essential.

By default, OpenBOR timing is based on real-world time measured in milliseconds, not display frames. For example, animation delay between animation frames is controlled by the integer setting delay {int}, where a value of 1 represents one centisecond, or 10 milliseconds.

This approach simplifies project creation and provides consistent timing across platforms. However, frame durations do not divide evenly into milliseconds. At 60 frames per second, one frame lasts approximately 16.67 milliseconds. It is therefore mathematically impossible to reproduce arbitrary frame-based timing perfectly using whole-millisecond values.

OpenBOR may optionally be configured for frame-based timing when exact frame correspondence is preferred. See the relevant section below for details.

Time in OpenBOR is represented by the following primary definitions:

Game Time

The traditional beat ’em up countdown timer used to maintain the pace of a level.

When Game Time expires, players ordinarily lose a life. Game Time is enabled by default, though creators may disable, remove, or otherwise modify it.

Elapsed Time

An integer value reset at the beginning of each active level and incremented once for every processed logical tick.

OpenBOR processes 200 logical ticks per second by default. Each Elapsed Time increment therefore represents 5 milliseconds, or one-half of a centisecond.

Elapsed Time drives much of the engine’s internal timing, including animations, delays, effect durations, and other gameplay processes.

Ticks

The number of milliseconds elapsed since OpenBOR was started.

Tick values are independent of the active level and may be used for timing operations both inside and outside gameplay. Common uses include loading processes, recorded player input, and custom script timers.

Ticks are generally preferable to manually incrementing a script variable when timing must remain independent of script execution frequency.

System Time

OpenBOR’s scripting system includes an API for accessing the host system clock and obtaining real-world dates and times.

System Time access is entirely optional. It does not affect native engine timing or gameplay functionality.

OpenBOR exposes several types of time, including world time and time elapsed since startup.

Game Time

Game time is a default countdown timer that appears at top center of the screen during an active level. It starts at 99 and decrements once every two real world seconds. At 0, all active players take damage equal to their current HP, and the game is over if no lives or credits remain. Time resets automatically when players clear a designated level wait and at the start of each new level.

The Batman Savage Dawn fan game demonstrates OpenBOR's default game timer in action at top center of the screen.

Set Time

settime {int time}

#default
settime 99

Level header command that sets value applied to timer on level start and native resets.

• Accepts any integer value from 0 to 99. Out of bounds values are ignored.
• 0 = infinite time.

HUD Display

For configuring how timer displays on screen, see Heads Up Display.

• Disable Time Display
• Timer Font
• Timer Location
• Timer Icon

Other

data/sounds/timeover.wav

If available, plays once when the game timer expires.

anim lose

If available, entity plays this animation in place of normal death when game timer expires.

• Accessible to script as openborconstant("ANI_LOSE").

anim falllose

If available and entity does not have a lose animation, entity plays this animation in place of normal fall death when game timer expires.

• Accessible to script as openborconstant("ANI_FALLLOSE").

Attack types

Attack types applied to players when game time expires.

• openborconstant("ATK_TIMEOVER") - Applied to players without a lose animation.
• openborconstant("ATK_LOSE") - Applied to players with a lose animation.

Script API

Game Time

Current game time is read and write accessible.

Get

int time = openborvariant("game_time");

Get integer representing game time remaining.

Set

int new_time = 50;

setopenborvariat("game_time", new_time);

Set game time remaining.

Timetick Event

If available, data/scripts/timetick.c fires on each game time decrement. Populates the following local variables.

• time - Current game time value.

Elapsed Time

In terms of game mechanics, elapsed time is the most important and frequently employed time measurement as it represents OpenBOR's logical clock, though its implementation is relatively simple. For each level, a global elapsed-time counter begins at 0. OpenBOR’s logical clock runs at 200 ticks per second, and the counter increments by 1 for every processed logic tick.

Each logical tick represents 5 milliseconds, or one-half of a centisecond. Therefore, two elapsed-time ticks equal one centisecond, while 200 ticks equal one second.

OpenBOR’s logical clock is separate from its outer update and rendering rate. Depending on the selected FPS setting and display synchronization, the engine may run its outer update cycle more frequently than 200 times per second. Available FPS settings include VSync, limits of 200 or 500 FPS, and an unrestricted option.

Some operations, including the global update.c and updated.c script events, execute once per outer update cycle. These scripts may therefore run more frequently than the 200 Hz logical clock. Other operations, such as entity simulation and entity update scripts, execute according to logical ticks.

OpenBOR also keeps logical timing independent from individual rendered frames. This allows the engine to maintain consistent gameplay timing across different FPS settings. Under unusual performance conditions, the engine may process more than one logical tick during an outer update to keep elapsed time synchronized, though this is rarely noticeable in normal use.

In effect, this means elapsed time is always safe during game play as a timer, but manually incremented timers may be inconsistent. For keeping time outside of game-play when elapsed time is not available, consider using ticks instead.

Most internal timing works by setting an expiration value to the current elapsed time plus a predetermined duration. The engine then compares that expiration value against the elapsed-time counter. Once elapsed time reaches or passes the expiration value, the timed item may complete, expire, continue, or perform whatever other action its system requires.

Note: In case it matters, the current elapsed time variable is a 32bit unsigned integer. That's enough to run a single level continuously for roughly eight months before rolling over.

Script API

Get Elapsed Time

int elapsed_time = openborvariant("elapsed_time");

Set Elapsed Time

Be careful about setting elapsed time during game-play, as again, virtually every active game timing property depends on it.

int new_time = 100

setopenborvariant("elapsed_time", new_time);

Ticks

Ticks is a read only measure of milliseconds starting from game boot. OpenBOR natively uses ticks for the player input recording feature and for timing during load screens. Ticks therefore do not generally affect active game-play, but are useful for user content, scripting, and keeping time outside of active game-play elements when increments are not natively incremented.

Script API

Get Ticks

int ticks = openborvariant("ticks");

System Time

System time is entirely optional and provided for creator defined script use. It is not accessed by native engine logic in any way. System is available as a Unix timestamp in either seconds or milliseconds where supported by hardware. Conversion functions allow outputting a custom formatted string or time parts as integer values for use in logic expressions.

Script API

Get Current Unix Timestamp

Returns the current system time as the number of seconds elapsed since 1970-01-01 00:00:00 UTC.

int timestamp = datetime_gettimestamp();

Get Current Unix Timestamp in Milliseconds

Returns the current system time as the number of milliseconds elapsed since 1970-01-01 00:00:00 UTC.

Note: Millisecond Unix timestamps require a 64-bit integer value.

int timestamp = datetime_gettimestampms();

Format Current Local Date and Time

Formats the current system time as a string using the host system's local time standard. The format string uses standard datetime conversion codes.

Note: Names such as weekdays and months may vary according to the host system's configured language and locale.

void date_time = datetime_format("%Y-%m-%d %H:%M:%S");

The following examples demonstrate several common formats:

/*
* ISO-style date and 24-hour time:
* 2026-07-12 14:35:08
*/
void date_time = datetime_format("%Y-%m-%d %H:%M:%S");

/*
* Month, day, and year:
* 07/12/2026
*/
void date = datetime_format("%m/%d/%Y");

/*
* Full weekday and month names:
* Sunday, July 12, 2026
*/
void written_date = datetime_format("%A, %B %d, %Y");

/*
* Abbreviated weekday and month names:
* Sun, Jul 12, 2026
*/
void short_date = datetime_format("%a, %b %d, %Y");

/*
* 12-hour time with AM or PM:
* 02:35:08 PM
*/
void time_12_hour = datetime_format("%I:%M:%S %p");

/*
* 24-hour time:
* 14:35:08
*/
void time_24_hour = datetime_format("%H:%M:%S");

/*
* Year, month, day, hour, and minute:
* 20260712_1435
*
* Useful for save names, logs, and generated filenames.
*/
void file_timestamp = datetime_format("%Y%m%d_%H%M");

/*
* Day of the year:
* Day 193 of 2026
*/
void year_progress = datetime_format("Day %j of %Y");

/*
* Weekday name:
* Sunday
*/
void weekday = datetime_format("%A");

Format a Unix Timestamp

Formats a supplied Unix timestamp expressed in milliseconds.

int timestamp = 1783890000000;

void date_time = datetime_format("%Y-%m-%d %H:%M:%S", timestamp);

Format Date and Time as UTC

Formats a supplied Unix timestamp using Coordinated Universal Time instead of the host system's local time.

int timestamp = datetime_gettimestampms();

void date_time = datetime_format("%Y-%m-%d %H:%M:%S", timestamp, DATETIME_STANDARD_UTC);

Get Current Year

Returns the current four-digit year using the host system's local time standard.

int year = datetime_getyear();

Get Current Month

Returns the current calendar month as an integer.

int month = datetime_getmonth();

Get Current Day

Returns the current day of the month as an integer.

int day = datetime_getday();

Get Current Weekday

Return the current day of the week as an integer corresponding to one of the following constants:

openborconstant("DATETIME_WEEKDAY_SUNDAY")
openborconstant("DATETIME_WEEKDAY_MONDAY")
openborconstant("DATETIME_WEEKDAY_TUESDAY")
openborconstant("DATETIME_WEEKDAY_WEDNESDAY")
openborconstant("DATETIME_WEEKDAY_THURSDAY")
openborconstant("DATETIME_WEEKDAY_FRIDAY")
openborconstant("DATETIME_WEEKDAY_SATURDAY")

int weekday = datetime_getweekday();

/* Is it Monday? */
if(weekday == openborconstant("DATETIME_WEEKDAY_MONDAY")){
    log("Just another Manic Monday.");
}

Get Current Hour

Returns the current hour using the host system's local time standard.

int hour = datetime_gethour();

Get Current Minute

Returns the current minute of the hour.

int minute = datetime_getminute();

Get Current Second

Returns the current second of the minute.

int second = datetime_getsecond();

Get Date and Time Parts from a Unix Timestamp

Each component function optionally accepts a Unix timestamp expressed in milliseconds. This allows creators to extract individual date and time values from a stored timestamp.

int timestamp = 1783890000000;

int year   = datetime_getyear(timestamp);
int month  = datetime_getmonth(timestamp);
int day    = datetime_getday(timestamp);
int hour   = datetime_gethour(timestamp);
int minute = datetime_getminute(timestamp);
int second = datetime_getsecond(timestamp);

Get Date and Time Parts as UTC

Pass `DATETIME_STANDARD_UTC` as the second argument to interpret the supplied timestamp as Coordinated Universal Time.

int timestamp = datetime_gettimestampms();

int year = datetime_getyear(timestamp, DATETIME_STANDARD_UTC);

int month = datetime_getmonth(timestamp, DATETIME_STANDARD_UTC);

int day = datetime_getday(timestamp, DATETIME_STANDARD_UTC);

int hour = datetime_gethour(timestamp, DATETIME_STANDARD_UTC);

Use Current Time with an Explicit Time Standard

Pass `NULL()` for the optional timestamp argument when selecting a time standard without supplying a custom timestamp.

int utc_hour = datetime_gethour(NULL(), DATETIME_STANDARD_UTC);