Understanding Events and Event Handlers in KAPLAY

Events in KAPLAY provide a way to handle specific moments in your game execution by executing code when those moments occur. This guide covers the basics of events, event handlers, and their types, helping you implement dynamic game mechanics with ease.

 

What Are Events?

Events are actions or occurrences within the game, such as:

·       A player pressing a key

·       Clicking the mouse

·       An enemy being hurt

By responding to these events, you can make your game interactive and engaging.

 

Event Handlers

Event Handlers are methods that "listen" for events and execute code when the event occurs. These methods are typically named in the format on{EventName}.

 

Example

onKeyPress("space", () => { // Logic here });

 

Event Controller

When an event handler is created, it returns an Event Controller. This allows you to manage the event, such as canceling or pausing it.

 

Example

const pressEvent = onKeyPress((key) => { debug.log(key); }); pressEvent.cancel(); // Stops running the handler

 

Follow below step-by-step procedure to build an Application.

 

Step 1: Create a KAPLAY project event-handling-hello-world by executing below command.

 

npx create-kaplay event-handling-hello-world

 

Upon successful execution of above command, you can see a project structure looks like below.

 

 

Step 2: Update src/main.js with below code.

 

main.js

import kaplay from "kaplay";

const k = kaplay();

k.setGravity(1000);

k.loadSprite("bean", "sprites/bean.png");

const player = k.add([k.pos(120, 80), k.sprite("bean"), k.body(), k.area()]);

const ground = k.add([
  k.rect(k.width(), 100),
  k.pos(0, 700),
  k.area(),
  k.outline(3),
  k.color(109, 99, 19), // Brown-like color for the ground
  k.body({ isStatic: true }),
]);

// Function to create and fire a bullet
function fireBullet() {
  const bullet = k.add([
    k.pos(player.pos.x + player.width / 2 - 5, player.pos.y), // Position at player's top center
    k.circle(10), // Bullet size
    k.color(255, 0, 0), // Red bullet color
    k.area(),
  ]);

  // Move bullet upwards in the update loop
  bullet.onUpdate(() => {
    bullet.move(0, -400); // Move up with a speed of 600 units per second

    // Destroy the bullet if it goes off-screen
    if (bullet.pos.y < -10) {
      bullet.destroy();
    }
  });
}

// Event listener for space key press
player.onKeyPress("space", () => {
  if (player.isGrounded()) {
    fireBullet();
  }
});

// Define smooth horizontal movement for the player
// Move left when the left arrow key is held down
player.onKeyDown("left", () => {
  player.move(-300, 0); // Move left with a speed of 300
});

// Move right when the right arrow key is held down
player.onKeyDown("right", () => {
  player.move(300, 0); // Move right with a speed of 300
});

// Add screen boundaries to prevent the player from moving off the screen
player.onUpdate(() => {
  if (player.pos.x < 0) {
    player.pos.x = 0; // Prevent moving off the left edge
  }
  if (player.pos.x > k.width() - player.width) {
    player.pos.x = k.width() - player.width; // Prevent moving off the right edge
  }
});

 Step 3: Execute below commands from project root folder to run the Application.

 

npm install
npm run dev

 

Launch the url ‘http://localhost:3001/’ in a browser to play with the Application.

 

You can see a demo recording here (https://www.youtube.com/watch?v=DM_KSBHkcfM).

 

 

Explanation of Code

Event handlers in KAPLAY are functions that "listen" for specific game events and execute code when those events occur. They are defined using methods like onKeyPress, onKeyDown, and onUpdate.

 

1. onKeyPress: Listens for a specific key press event and executes the associated code once when the key is pressed.

 

player.onKeyPress("space", () => {
    if (player.isGrounded()) {
        fireBullet();
    }
});

 

This handler listens for the space key press. If the player is grounded (standing on a surface), the fireBullet function is triggered, creating a bullet.

 

2. onKeyDown: Listens for a specific key being held down and executes the associated code repeatedly while the key is pressed.

player.onKeyDown("left", () => {
    player.move(-300, 0); // Move left
});

player.onKeyDown("right", () => {
    player.move(300, 0); // Move right
});

The left and right arrow keys are used to move the player horizontally. This creates smooth, continuous movement as long as the key is held.

 

3. onUpdate: Runs a callback function every frame, typically 60 times per second.

bullet.onUpdate(() => {
    bullet.move(0, -400); // Bullet moves upward
    if (bullet.pos.y < -10) {
        bullet.destroy(); // Remove bullet when it leaves the screen
    }
});

player.onUpdate(() => {
    if (player.pos.x < 0) {
        player.pos.x = 0; // Prevent moving off the left edge
    }
    if (player.pos.x > k.width() - player.width) {
        player.pos.x = k.width() - player.width; // Prevent moving off the right edge
    }
});

 

The bullet's onUpdate handler moves the bullet upwards every frame and destroys it when it goes off-screen. The player's onUpdate handler ensures the player stays within screen boundaries by restricting its x position.

 

You can download the Application from this link.

 

Previous                                                    Next                                                    Home