*_input — Reacting to player input#
Kate supports multiple input sources, such as the Kate gamepad and pointer input. Each of these input sources has a distinct API exposed, and this section describes all of the different input APIs.
State updates#
Input states are updated from the Kate Kernel by sending messages to
the cartridge process. They are then synchronised using the
Timer API, which ticks at 30 FPS. This means
that the best way to read button states is to schedule your updates using
the Timer API as well, otherwise APIs like is_just_released() will
have no defined meaning.
For example, if you’re using requestAnimationFrame to update your game, then querying the button state might end up reporting that a button was “just pressed” or “just released” multiple frames in a row:
function update() {
if (KateAPI.input.is_just_pressed("menu")) {
show_menu_screen();
} else if (KateAPI.input.is_just_pressed("o")) {
next_dialogue();
}
requestAnimationFrame(update);
}
// Don't do this, input states will not have been properly updated when
// your function is called!
requestAnimationFrame(update);
Instead, use the Timer API to schedule your updates:
KateAPI.timer.on_tick.listen(time => {
if (KateAPI.input.is_just_pressed("menu")) {
show_menu_screen();
} else if (KateAPI.input.is_just_pressed("o")) {
next_dialogue();
}
});
Alternatively, instead of pulling input states in your update function, you can have them pushed to your cartridge code by listening to input state change events. This method requires no synchronisation with the Kate timer since all changes are propagated as discrete events, but requires you to write your code in an event-driven manner.
For example:
KateAPI.input.on_key_pressed.listen(({ key }) => {
if (key === "menu") {
show_menu_screen();
} else if (key === "o") {
next_dialogue();
}
});
Kate buttons (input)#
The Kate buttons API (input) allows a cartridge to react to buttons pressed
in the standard Kate gamepad. This gamepad is made out of:
A four-directions D-pad (
);Four face buttons:
(Ok), 
(Cancel), 
(Sparkle), and 
(Menu);Two shoulder buttons:
and 
; andTwo special buttons:
(Capture button) and 
(Berry button).
Although your cartridge reacts to these Kate buttons, a player may be interacting with it through other means. E.g.: players running a Kate emulator on a PC might be interacting with your cartridge through a keyboard. Whereas players running a Kate emulator on a phone might be interacting with your cartridge through virtual buttons using their touch screen. In all cases the Kate emulator translates these distinct input sources into Kate button presses, so you don’t need to be aware of them.
Pause state#
When the player brings up the context menu, Kate considers the game paused and will not forward any input to the cartridge during this period. That lasts until the cartridge goes back to running in the foreground.
This state is readable from the input API and can be used by the cartridge to avoid updating other game entities while the player is not actively interacting with it.
- property KateAPI.input.is_paused: boolean#
Returns whether the cartridge is in a “paused” state, where the Kate Kernel will not be forwarding input to it because it’s not the application currently in the foreground.
Example
function update(lag) { if (!KateAPI.input.is_paused) { player.update(lag); for (const enemy of enemies) { enemy.update(lag); } } }
Button identifiers#
- class KateAPI.input.InputKey#
Each button in the Kate gamepad is identified by a unique string. These are
referred to as InputKey below:
Button |
Identifier |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Warning
ltrigger and rtrigger will be renamed to l and r in the
next version and the current identifiers will be deprecated.
and are special in that Kate distinguishes between
a short and long press. This also means that state changes for these buttons
is delayed until the player releases the button, so Kate can decide whether
to report that as a “short” or “long” press.
Other buttons do not have a concept of “long press”, but may be considered repeat presses if the player presses the button and doesn’t release it for a long period of time.
- class KateAPI.input.KeyPressedEvent#
Represents a key being pressed.
- property is_repeat: boolean#
True if the key was pressed in a previous frame, but remains pressed in this one.
- property is_long_press: boolean#
True if the key is special (
berryorcapture) and the player has held it for longer than the long-press threshold.
Events#
The input API provides two events for discrete changes to the button states. These are forwarded directly from the Kate Kernel and propagated to any listener in the cartridge.
- property KateAPI.input.on_key_pressed: EventStream[KeyPressedEvent]#
Emitted whenever the player presses a button, with some delay for special keys. Repeat presses may trigger this event multiple times for the same key, and in that case
is_repeatwill be set to true.
Pointer input (pointer_input)#
The Pointer API (pointer_input) allows a cartridge to react to pointer
events that happen when the cartridge is the foreground application (i.e.:
when the player is actively interacting with it).
A pointer event can come from many different input devices, the most common one being a mouse. But touch input and pen/stylus devices also generate pointer events. The design takes after the DOM pointer events. That is, pointing devices are anything that can target some coordinate on the screen, and the pointer API provides ways to react to this pointer moving or touching/parting from the screen.
Note
Currently the pointer API does not support pen pressure, tilt, and other more complex properties, but they’re planned for a future revision.
The Kate pointer API only supports one active pointer. That is, there is only one coordinate in the screen that the pointing device can be pointing at at any given time.
Pointer location#
Pointing devices allow the player to target specific coordinates of the screen, which they do so by moving a “pointer” around. For example, a player using a mouse can move the mouse around to change where the pointer in the screen points at. A player using a trackpad can do the same by sliding their finger around the pad. All of these movements generate discrete pointer movement events and update the current location of the pointer.
For example, a cartridge that wishes to change how a button on the screen looks when the player moves the pointer on top of it could do so as follows:
const button = {
color: "#ccc",
left: 100,
top: 100,
right: 200,
bottom: 200
};
KateAPI.timer.on_tick.listen(time => {
const pointer = KateAPI.pointer.location;
if (
pointer.x >= button.left && pointer.x <= button.right &&
pointer.y >= button.top && pointer.y <= button.bottom
) {
button.color = "#039";
} else {
button.color = "#ccc";
}
const canvas = document.querySelector("#canvas");
const ctx = canvas.getContext("2d");
ctx.clearRect(0, 0, 300, 300);
ctx.fillStyle = button.color;
ctx.fillRect(button.left, button.top, button.right - button.left, button.bottom - button.top);
});
Types#
Events#
Discrete events are emitted whenever a pointer changes. While the events are still throttled at 30 FPS, your cartridge can build its own synchronisation when handling them.
- property KateAPI.pointer_input.on_moved: EventStream[PointerLocation]#
Emitted whenever the position of the pointer on the screen changes.
Querying state#
The state is updated at 30 FPS, so you’ll need to use the KateAPI.timer
API to synchronise your updates with the input state updates to be able to
get something sensible out of the data.
- property KateAPI.pointer_input.x: number#
The horizontal position of the pointer in the cartridge screen, in pixels.
- property KateAPI.pointer_input.y: number#
The vertical position of the pointer in the cartridge screen, in pixels.
- property KateAPI.pointer_input.location: PointerLocation#
The horizontal and vertical position of the pointer in the cartridge screen, in pixels.