Counter and Timer Functions — G.js API Reference

Counters are G.js’s primary abstraction over GD’s item system. They wrap a numeric item ID and expose a chainable API for arithmetic, conditional branching, and display. float_counter extends the integer counter with floating-point support, and timer creates a time-based counter driven by the level clock. For a higher-level guide see Counters and Conditions.

counter

Creates a new counter backed by a GD item ID. By default a fresh item ID is allocated automatically.

import { counter } from 'geometry-dash-gjs';

const c = counter();          // starts at 0
const c2 = counter(10);       // starts at 10
const c3 = counter(0, false, true); // persistent across attempts

num

any

default:"0"

Initial value. Can be a number or boolean.

use_id

boolean

default:"false"

When true, treats num as an existing item ID rather than an initial value.

persistent

boolean

default:"false"

Keeps the counter value across attempts.

is_timer

boolean

default:"false"

Creates the counter as a timer item.

bits

number

Number of bits to use for the counter. Affects maximum storable value.

Returns Counter.

float_counter

Version of counter that supports floating-point values. Adds round(), floor(), and ceil() methods on top of the standard Counter interface.

import { float_counter } from 'geometry-dash-gjs';

const f = float_counter(3.14);
f.add(1.5);
f.round(); // rounds to nearest integer

val

number

default:"0"

Initial floating-point value.

use_id

boolean

default:"false"

When true, treats val as an existing item ID.

persistent

boolean

default:"false"

Keeps the value across attempts.

Returns FloatCounter.

timer

Creates a time-based counter that counts up (or down) in real seconds using GD’s timer system. The returned Counter also exposes start(), stop(), set_start(), and set_end() methods.

import { timer, group } from 'geometry-dash-gjs';

// Count from 0 to 30 seconds, then call group(5)
const t = timer(0, 30, group(5));
t.start();

// Countdown from 60 to 0 seconds
const countdown = timer(60, 0, group(10), true);
countdown.start();

start_seconds

number

required

Initial time value in seconds.

end_seconds

number

default:"0"

Time value at which the timer fires the target group.

target_id

$group

default:"group(0)"

Group to call when the timer reaches end_seconds.

backwards

boolean

default:"false"

Count downward instead of upward.

seconds_only

boolean

default:"false"

Only count full seconds (no sub-second precision).

stop

boolean

default:"true"

Stop the timer automatically when it reaches end_seconds.

time_mod

number

default:"1"

Multiply the timer’s speed by this value. Cannot be used when backwards is true.

ignore_timewarp

boolean

default:"false"

Ignore the level’s timewarp trigger when ticking.

no_override

boolean

default:"false"

Prevent another timer from overriding this one.

Returns Counter.

Counter Interface

Every counter returned by counter(), float_counter(), or timer() implements the following interface.

Properties

item

any

The underlying GD item ID. Pass this to item_edit, item_comp, or count when you need raw item access.

type

number

Item type constant. 1 = ITEM, 2 = TIMER.

bits

number | undefined

Bit width of the counter, or undefined if unset.

Arithmetic Methods

Each arithmetic method returns the counter itself to allow chaining. The amount argument can be a plain number or another Counter.

add(amount)

Counter

Adds amount to the counter.

subtract(amount)

Counter

Subtracts amount from the counter.

multiply(amount)

Counter

Multiplies the counter by amount.

divide(amount)

Counter

Divides the counter by amount.

set(amount)

Counter

Sets the counter to amount.

mod(b)

Counter

Sets the counter to counter % b.

abs()

Counter

Takes the absolute value of the counter.

neg()

Counter

Negates the counter.

reset()

Counter

Resets the counter to zero.

Copy / Transfer Methods

add_to(item)

Counter

Adds this counter’s value to another counter.

copy_to(item)

Counter

Copies this counter’s value to another counter.

subtract_from(b)

Counter

Subtracts this counter’s value from counter b.

clone()

Counter

Creates a new counter with the same current value.

Conditional & Conversion Methods

if_is(comparison, other, trig_func)

void

Calls trig_func when the condition counter [comparison] other is true. Use the EQUAL_TO, LARGER_THAN, or SMALLER_THAN constants for comparison.

to_const(range, cb)

void

Iterates over range and calls cb(val) for each value that matches the counter. Useful for runtime branching on counter values.

to_obj()

GJsObject

Converts the counter to a raw GJsObject for use in object dictionaries.

display(x, y)

void

Places an item-display trigger at position (x, y) that shows this counter’s value on screen.

Code Example

import { counter, EQUAL_TO, trigger_function } from 'geometry-dash-gjs';

const score = counter(0);

// Increment on each call
score.add(1);

// Conditional branch when score reaches 10
score.if_is(EQUAL_TO, 10, trigger_function(() => {
  // winner!
}));

// Chain arithmetic
score.multiply(2).subtract(3);

// Display at position (100, 200)
score.display(100, 200);

FloatCounter Additional Methods

FloatCounter extends Counter with three rounding helpers, each of which returns the FloatCounter for chaining.

round()

FloatCounter

Rounds the value to the nearest integer.

floor()

FloatCounter

Floors the value to the nearest integer below.

ceil()

FloatCounter

Ceils the value to the nearest integer above. (Exposed via the core FloatCounter interface.)

import { float_counter } from 'geometry-dash-gjs';

const f = float_counter(7.9);
f.floor(); // 7
f.ceil();  // 8
f.round(); // 8

ceil() is defined in the FloatCounter TypeScript interface (core.d.ts) but the declaration file lists it alongside floor() as a method returning FloatCounter. Treat it as equivalent to floor() for upward rounding.

Core

Functions

Constants & Properties

Counter and Timer Functions — G.js API Reference

counter

float_counter

timer

Counter Interface

Properties

Arithmetic Methods

Copy / Transfer Methods

Conditional & Conversion Methods

Code Example

FloatCounter Additional Methods

Build docs developers (and LLMs) love

Core

Functions

Constants & Properties

Documentation Index

​counter

​float_counter

​timer

​Counter Interface

​Properties

​Arithmetic Methods

​Copy / Transfer Methods

​Conditional & Conversion Methods

​Code Example

​FloatCounter Additional Methods

Build docs developers (and LLMs) love

counter

float_counter

timer

Counter Interface

Properties

Arithmetic Methods

Copy / Transfer Methods

Conditional & Conversion Methods

Code Example

FloatCounter Additional Methods