Keyframe Animations in G.js Levels

G.js provides a keyframe animation system that wraps GD’s native keyframe triggers, letting you define a sequence of position, rotation, and scale states and play them back on any group. This is distinct from GD’s built-in animation IDs (which play pre-made monster animations) — the keyframe system gives you full control over each step of the animation timeline.

How the Keyframe System Works

Keyframe animations work in two steps:

Define keyframes — each keyframe is a snapshot of position (x, y), rotation, and scale (scale_x, scale_y) at a given point in time.
Animate a target — the animate() call ties a group of keyframes to a target object group, playing them in sequence.

Both steps produce GJsObject values, meaning you must call .add() on each keyframe and on the animate trigger to include them in your level.

`keyframe_system()`

const anim = keyframe_system();

keyframe_system() takes no arguments and returns an object with two methods: keyframe() and animate(). Call it once and reuse the returned object for all keyframes belonging to the same animation sequence.

`anim.keyframe()`

anim.keyframe(x, y, rotation, scale_x, scale_y, duration?, easing?)

Creates a single keyframe that defines one state in the animation. Returns a GJsObject — you must call .add() on it.

Parameter	Type	Default	Description
`x`	`number`	—	Target X position
`y`	`number`	—	Target Y position
`rotation`	`number`	—	Target rotation in degrees
`scale_x`	`number`	—	Target X scale
`scale_y`	`number`	—	Target Y scale
`duration`	`number`	`0`	Time in seconds to reach this state from the previous keyframe
`easing`	`number`	`NONE`	Easing curve constant (see table below)

`anim.animate()`

anim.animate(target, keyframes, duration?, easing?)

Animates a target group through a sequence of keyframes. Returns a GJsObject — you must call .add() on it.

Parameter	Type	Default	Description
`target`	group	—	The group to animate
`keyframes`	any	—	The keyframe sequence to play back
`duration`	`number`	`0`	Overall animation duration override
`easing`	`number`	`NONE`	Global easing override

Easing Constants

G.js exposes all of GD’s built-in easing curves as named constants. Import them from the global scope or from @g-js-api/g.js/safe.

Constant	Description
`NONE`	No easing (linear)
`EASE_IN`	Ease in
`EASE_OUT`	Ease out
`EASE_IN_OUT`	Ease in and out
`ELASTIC_IN`	Elastic ease in
`ELASTIC_OUT`	Elastic ease out
`ELASTIC_IN_OUT`	Elastic ease in and out
`BOUNCE_IN`	Bounce ease in
`BOUNCE_OUT`	Bounce ease out
`BOUNCE_IN_OUT`	Bounce ease in and out
`BACK_IN`	Back ease in (slight overshoot)
`BACK_OUT`	Back ease out
`BACK_IN_OUT`	Back ease in and out
`SINE_IN`	Sine ease in
`SINE_OUT`	Sine ease out
`SINE_IN_OUT`	Sine ease in and out
`EXPONENTIAL_IN`	Exponential ease in
`EXPONENTIAL_OUT`	Exponential ease out
`EXPONENTIAL_IN_OUT`	Exponential ease in and out

Creating a Bounce Animation

The following example animates a platform group so it bounces upward and back down with an elastic ease:

Set up the level and group

import '@g-js-api/g.js';

await $.exportConfig({ type: 'savefile', options: { info: true } });

const platform = unknown_g();

Create the keyframe system

const anim = keyframe_system();

Define keyframes

Each keyframe describes where the group should be at that point in the sequence. Call .add() on every keyframe.

// Starting position (at rest)
anim.keyframe(0, 0, 0, 1, 1, 0, NONE).add();

// Jump up with elastic ease
anim.keyframe(0, 60, 0, 1, 0.8, 0.4, ELASTIC_OUT).add();

// Squash on landing
anim.keyframe(0, 0, 0, 1.3, 0.7, 0.4, BOUNCE_OUT).add();

// Settle back to normal scale
anim.keyframe(0, 0, 0, 1, 1, 0.2, EASE_OUT).add();

Attach and trigger the animation

// Animate the platform group — must call .add()
anim.animate(platform, anim, 1.0, NONE).add();

// Fire the animation when the player touches the screen
on(touch(), trigger_function(() => {
  anim.animate(platform, anim).add();
}));

Full Bounce Animation Script

import '@g-js-api/g.js';

await $.exportConfig({ type: 'savefile', options: { info: true } });

const platform = unknown_g();
const anim = keyframe_system();

// Define the four keyframes of the bounce cycle
anim.keyframe(0,  0,  0, 1.0, 1.0, 0.0, NONE).add();         // rest
anim.keyframe(0, 60,  0, 1.0, 0.8, 0.4, ELASTIC_OUT).add();  // rise
anim.keyframe(0,  0,  0, 1.3, 0.7, 0.4, BOUNCE_OUT).add();   // land/squash
anim.keyframe(0,  0,  0, 1.0, 1.0, 0.2, EASE_OUT).add();     // settle

// Play the animation on our platform group
anim.animate(platform, anim).add();

// Place a platform block and tag it with the group
object({
  [obj_props.OBJ_ID]: 1,
  [obj_props.X]: 150,
  [obj_props.Y]: 75,
  [obj_props.GROUPS]: platform
}).add();

GD Animation IDs (`$group.animate()`)

This is a different feature from the keyframe system above. $group.animate(anim_id?) triggers one of GD’s built-in monster/enemy animation sequences on an object group — it does not use the keyframe_system() API.

GD ships with pre-defined animation sequences for certain enemy objects. You can trigger these using the .animate() method on a group reference, passing one of the IDs from the animations constant object.

Available Animation IDs

The animations object contains IDs grouped by creature type: animations.big_beast

Key	Description
`bite`	Bite attack
`attack01`	Attack sequence 1
`attack01_end`	End of attack sequence 1
`idle01`	Idle loop 1

animations.bat

Key	Description
`idle01`	Idle loop 1
`idle02`	Idle loop 2
`idle03`	Idle loop 3
`attack01`	Attack sequence 1
`attack02`	Attack sequence 2
`attack02_end`	End of attack sequence 2
`sleep`	Sleep start
`sleep_loop`	Sleep loop
`sleep_end`	Wake from sleep
`attack02_loop`	Attack loop 2

animations.spikeball

Key	Description
`idle01`	Idle loop 1
`idle02`	Idle loop 2
`toAttack01`	Transition to attack 1
`attack01`	Attack sequence 1
`attack02`	Attack sequence 2
`toAttack03`	Transition to attack 3
`attack03`	Attack sequence 3
`idle03`	Idle loop 3
`fromAttack03`	Return from attack 3

Example — Trigger a Bat Attack

import '@g-js-api/g.js';

await $.exportConfig({ type: 'savefile', options: { info: true } });

const bat_group = group(5); // assumes bat object is already in group 5

on(touch(), trigger_function(() => {
  bat_group.animate(animations.bat.attack01);
}));

Particles & Shaders

Create particle systems and apply GD 2.2 post-processing shaders.

Camera & Visual

Camera offsets, rotation, zoom, and free-mode controls.

Keyframes API Reference

Full API reference for the keyframe system.

Events

Respond to touch, collision, death, and other GD events.

Get Started

Core Concepts

Guides

Keyframe Animations in G.js Levels

How the Keyframe System Works

`keyframe_system()`

`anim.keyframe()`

`anim.animate()`

Easing Constants

Creating a Bounce Animation

Full Bounce Animation Script

GD Animation IDs (`$group.animate()`)

Available Animation IDs

Example — Trigger a Bat Attack

Particles & Shaders

Camera & Visual

Keyframes API Reference

Events

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Documentation Index

​How the Keyframe System Works

​keyframe_system()

​anim.keyframe()

​anim.animate()

​Easing Constants

​Creating a Bounce Animation

​Full Bounce Animation Script

​GD Animation IDs ($group.animate())

​Available Animation IDs

​Example — Trigger a Bat Attack

Particles & Shaders

Camera & Visual

Keyframes API Reference

Events

Build docs developers (and LLMs) love

How the Keyframe System Works

`keyframe_system()`

`anim.keyframe()`

`anim.animate()`

Easing Constants

Creating a Bounce Animation

Full Bounce Animation Script

GD Animation IDs (`$group.animate()`)

Available Animation IDs

Example — Trigger a Bat Attack