# Event Listeners

### Introduction

These functions **operate in response to specific situations** that may happen in a ZEP Space such as players typing specified words or attacking a specific object.

<table><thead><tr><th width="234">Name</th><th>Description</th></tr></thead><tbody><tr><td>onSay</td><td>Function that operates when a player types chat</td></tr><tr><td>onPlayerTouched</td><td>Function that operates when avatars collide with each other</td></tr><tr><td>onObjectTouched</td><td>Function that operates when an avatar collides with an object</td></tr><tr><td>onAppObjectTouched</td><td>Function that operates when an avatar collides with an object with a key value</td></tr><tr><td>onUnitAttacked</td><td>Function that operates when an avatar attacks another avatar with the Z key</td></tr><tr><td>onObjectAttacked</td><td>Function that operates when an avatar attacks an object with the Z key</td></tr><tr><td>onSidebarTouched</td><td>Function that operates when a player touches the Sidebar app</td></tr><tr><td>onTriggerObject</td><td>Function that operates when an avatar interacts with an object with the F key</td></tr><tr><td>onAppObjectAttacked</td><td>Function that operates when an avatar attacks an object with a key value with the Z key</td></tr></tbody></table>

## 📚 API Description and Example

<mark style="background-color:yellow;">**Event Listeners at a Glance**</mark>

```jsx
// Calls event for every chat that players enter into the chat window
// Text that begins with ! is not displayed in the chat window,
// but can be used in the onSay function.App.onSay.Add(function(player, text) {
});

// Calls event when a player collides with another player
App.onPlayerTouched.Add(function(sender, target, x, y){
});

// Calls event when the player collides with an object
App.onObjectTouched.Add(function(sender, x, y, tileID) {  
});

// Calls event when the player collides with an object with a key value
App.onAppObjectTouched.Add(function(key, sender, x, y){});

// Calls event when the player attacks another player (Z key)
App.onUnitAttacked.Add(function(sender, x, y, target) {
});

// Calls event when the player attacks an object (Z key)
App.onObjectAttacked.Add(function(sender, x, y){
});

// Calls event when an avatar attacks an object with a key value with the Z key
App.onAppObjectAttacked.Add(function (sender, x, y, layer, key) {
});
```

### onSay

{% hint style="info" %}
App.onSay.Add(function(player, text){});
{% endhint %}

This function operates when a player enters chat.

**Parameters**

<table><thead><tr><th width="130.33333333333331">Name</th><th width="109">Type</th><th>Description</th></tr></thead><tbody><tr><td>player</td><td>Player</td><td>The player’s parameter refers to the player who enters chat.<br>The player’s parameter names can be changed arbitrarily.</td></tr><tr><td>text</td><td>String</td><td>Text refers to the entered chat content.<br>The text’s parameter names can be changed arbitrarily.</td></tr></tbody></table>

**Example**

Hangul quiz - Makes a function to guess the answer via chat:

```jsx
_answer = "ZEP" // Correct
// Executes when a player enters chat
App.onSay.add(function(player, text) {
    if(_answer == text){
        App.showCenterLabel(player.name + ' Correct!\nThe answer is ' + _answer);
    }
});
```

### onPlayerTouched

{% hint style="info" %}
App.onPlayerTouched.Add(function(sender, target, x, y){});
{% endhint %}

This function operates when an avatar collides with another avatar.

**Parameters**

<table><thead><tr><th width="126">Name</th><th width="113.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>sender</td><td>Player</td><td>The player who collides</td></tr><tr><td>target</td><td>String</td><td>The player who is the object of the collision</td></tr><tr><td>x, y</td><td>Number</td><td>The X and Y coordinate of the location where the collision occurs</td></tr><tr><td></td><td></td><td>The parameter name of sender, target, X, and Y can be changed arbitrarily</td></tr></tbody></table>

**Example**

Display a message when two avatars collide.

```jsx
// Calls event when two players collide
App.onPlayerTouched.Add(function (sender, target, x, y) {
	App.showCenterLabel(
		`${sender.name} and ${target.name} have collided at the coordinates: (${x}, ${y}).`
	);
});
```

### onObjectTouched

{% hint style="info" %}
App.onObjectTouched.Add(function(sender, x, y){});
{% endhint %}

This function operates when an avatar collides with an object.

**Parameters**

<table><thead><tr><th width="116.33333333333331">Name</th><th width="107">Type</th><th>Description</th></tr></thead><tbody><tr><td>sender</td><td>Player</td><td>The player who collides with the object</td></tr><tr><td>x, y</td><td>Number</td><td>The X and Y coordinate of the location where the collision occurs</td></tr><tr><td>tileID</td><td>Number</td><td>The tile ID of the object</td></tr><tr><td>obj</td><td>Object</td><td>Object</td></tr></tbody></table>

**Example**

Label display

⭐ A collision with an object without the `overlap: true` attribute cannot call this function.

{% file src="/files/GJgEAqSrUmrHYEjAZ7Rk" %}

```jsx
let testObject = App.loadSpritesheet("object.png");

App.onStart.Add(function () {
	Map.putObject(5, 5, testObject, { overlap: true });
});

// Calls event when the player collides with an object
App.onObjectTouched.Add(function (sender, x, y, tileID) {
	Map.putObject(x, y, null);
	App.showCenterLabel(
		`${sender.name} has collided with an object at the coordinates: (${x}, ${y}).`
	);
});
```

```jsx
let testObject = App.loadSpritesheet("object.png");
// available ObjectEffectType
const ObjectEffectType = {
    NONE = 0,
    SHOW_NOTE = 1,
    SHOW_IMAGE = 2,
    PASSWORD_DOOR = 3,
    LINK_WEBSITE = 4,
    EMBED_WEBSITE = 5,
    API_CALL = 6,
    REPLACE_IMAGE = 7,
    NFT_GIVEAWAY = 8,
    NFT_DOOR = 9,
    POST_MESSAGE = 10,
    SHOW_CHAT_BALLOON = 11,
    FT_DOOR = 12,
    POST_MESSAGE_TO_APP = 13,
    DONATION_DOOR = 14,
    IMPASSABLE = 15,
    STAMP = 16,
    TOKEN_DONATION_DOOR = 17,
    CHANGE_OBJECT = 18,
    ANIMATION = 19,
    NFT_DOOR_MOVE = 20,
    INTERACTION_WITH_ZEPSCRIPTS = 21,
    MULTIPLE_CHOICE = 22,
}

App.onStart.Add(function () {
	Map.putObject(5, 5, testObject, { overlap: true });
});

// Calls event when the player collides with an object
App.onObjectTouched.Add(function (sender, x, y, tileID, obj) {
	Map.putObject(x, y, null);
	App.showCenterLabel(
		`${sender.name} has collided with an object at the coordinates: (${x}, ${y}).(Type: ${obj.type})`
	);
});
```

### onAppObjectTouched

{% hint style="info" %}
App.onAppObjectTouched.Add(function(key, sender, x, y){});
{% endhint %}

️This function operates when an avatar collides with an object with a key value.

**Parameters**

<table><thead><tr><th width="133.33333333333331">Name</th><th width="127">Type</th><th>Description</th></tr></thead><tbody><tr><td>key</td><td>String</td><td>The key value of the object</td></tr><tr><td>sender</td><td>Player</td><td>The player who collides with the object</td></tr><tr><td>x, y</td><td>Number</td><td>The X and Y coordinate of the location where the collision occurs</td></tr></tbody></table>

**Example**

Label display

⭐ A collision with an object without the `overlap: true` attribute cannot call this function.

{% file src="/files/t5vgF4ozWdFyest5whqK" %}

```jsx
let blueman_dance = App.loadSpritesheet(
	"blueman.png",
	48,
	64,
	[20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37],
	8
);

// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
	App.sayToAll("Collision test with an object that has a key value");
	Map.putObjectWithKey(8, 5, blueman_dance, { overlap: true, key: "blueman" });
});

App.onAppObjectTouched.Add(function (player, key, x, y) {
	App.sayToAll(
		`${sender.name} has collided with an object whose value is ${key} at the coordinates: (${x}, ${y}).`
	);
});
```

### onUnitAttacked

{% hint style="info" %}
App.onUnitAttacked.Add(function(sender, x, y, target){});
{% endhint %}

This function operates when an avatar attacks another avatar with Z.

**Parameters**

<table><thead><tr><th width="122.33333333333331">Name</th><th width="114">Type</th><th>Description</th></tr></thead><tbody><tr><td>sender</td><td>Player</td><td>The player who attacks</td></tr><tr><td>x, y</td><td>Number</td><td>The X and Y coordinate of the location of the player who attacks</td></tr><tr><td>target</td><td>Player</td><td>The player who is under attack</td></tr><tr><td></td><td></td><td>The parameter name of sender, target, x, and y can be changed arbitrarily</td></tr></tbody></table>

**Example**

Display a message when a player attacks another player.

```jsx
// Calls event when the player attacks another player (Z key)
App.onUnitAttacked.Add(function (sender, x, y, target) {
	App.showCenterLabel(`${sender.name} has attacked ${target.name}.`);
	App.sayToAll(`(${x}, ${y})`);
});
```

### onObjectAttacked

{% hint style="info" %}
App.onObjectAttacked.Add(function(sender, x, y){});
{% endhint %}

This function operates when an avatar attacks an object with the Z key.

**Parameters**

<table><thead><tr><th width="130.33333333333331">Name</th><th width="130">Type</th><th>Description</th></tr></thead><tbody><tr><td>sender</td><td>Player</td><td>The player who attacks</td></tr><tr><td>x, y</td><td>Number</td><td>The X and Y coordinate of the location of the object</td></tr><tr><td></td><td></td><td>The parameter name of sender, x, and y can be changed arbitrarily.</td></tr></tbody></table>

**Example**

Display a message when an avatar attacks an object.

⭐ An attack on an object without the `overlap: true` attribute cannot execute the function.

{% file src="/files/Id4ANGByvpd1rndyHyob" %}

```jsx
let testObject = App.loadSpritesheet("object.png");

App.onStart.Add(function () {
	Map.putObject(5, 5, testObject, { overlap: true });
});
// Calls event when the player attacks an object (Z key)
App.onObjectAttacked.Add(function(sender, x, y){
	App.showCenterLabel(
		`${sender.name} has attacked an object at the coordinates: (${x}, ${y}).`
	);
})
```

### onSidebarTouched

{% hint style="info" %}
App.onSidebarTouched.Add(function(player){});
{% endhint %}

This function operates when a player touches the Sidebar app.

**Parameters**

<table><thead><tr><th width="145.33333333333331">Name</th><th width="127">Type</th><th>Description</th></tr></thead><tbody><tr><td>player</td><td>Player</td><td>The player who touches the Sidebar app</td></tr></tbody></table>

**Example**

Display a message on touching the Sidebar app.

```jsx
App.onSidebarTouched.Add(function (player) {
	App.sayToAll(`${player.name} has touched the Sidebar app.`)
});
```

**Related Tutorial**

[<mark style="color:purple;">Sidebar App Example</mark>](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/sidebar-app.md)

### onTriggerObject

{% hint style="info" %}
App.onTriggerObject.Add(function(player, layerID, x, y, key){});
{% endhint %}

This function that when an avatar interacts with an object with the F key.

**Parameters**

<table><thead><tr><th width="139.33333333333331">Name</th><th width="125">Type</th><th>Description</th></tr></thead><tbody><tr><td>player</td><td>Player</td><td>The player who interacts with the object</td></tr><tr><td>layerID</td><td>Number</td><td>The ID of the layer where the object is installed<br>Object: layerID = 3<br>Top object: layerID = 5</td></tr><tr><td>x, y</td><td>Number</td><td>The X and Y coordinate of the location of the object</td></tr><tr><td>key</td><td>String</td><td>Key value of the interacted object</td></tr></tbody></table>

**Example**

Display a message on interacting with the object.

<figure><img src="/files/wisBoL9RMBoCu3hd3sF6" alt=""><figcaption></figcaption></figure>

```javascript
App.onTriggerObject.Add(function (player, layerID, x, y) {
	App.sayToAll(`playerName: ${player.name} / layer: ${layerID} / coordinates:(${x}, ${y})`);
});
```

### onAppObjectAttacked

{% hint style="info" %}

```
App.onAppObjectAttacked.Add(function (sender, x, y, layer, key) {});
```

{% endhint %}

This function operates when an avatar attacks an object with a key value with the Z key.

**Reference**: [Object npcProperty](/zep-script/zep-script-guide/appendix/object-npcproperty.md)

**Parameters**

<table><thead><tr><th width="123.33333333333331">Name</th><th width="120">Type</th><th>Description</th></tr></thead><tbody><tr><td>sender</td><td>Player</td><td>The player who attacks</td></tr><tr><td>x, y</td><td>Number</td><td>The X and Y coordinate of the location of the object</td></tr><tr><td>layer</td><td>Number</td><td>The layer where the object is installed</td></tr><tr><td>key</td><td>String</td><td>The key value of the object</td></tr></tbody></table>

**Example**

Display a message on attacking an object with a key value.

![](/files/qzTW6ItnMjv9nvGLh4Mr)

⭐ Attacking an object without the `collide: true` property does not execute the function.

```javascript
App.onAppObjectAttacked.Add(function (sender, x, y, layer, key) {
    App.showCenterLabel(
        `sender: ${sender.name} 
        coordinates: (${x}, ${y})
        layer: ${layer}
        key: ${key}`
    );
})ja
```

**Reference**

{% content-ref url="/pages/iOcGEKOq4SErIlbeRYa5" %}
[Sidebar App](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/sidebar-app.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zep.us/zep-script/zep-script-api/scriptapp/event-listeners.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.