# 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="<https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FhoLozoUTYfXXJqAiHpjL%2F%EC%98%88%EC%A0%9C_onObjectTouched.zip?alt=media&token=1924a7ba-6b6f-4316-87c9-0911db0b0812>" %}

```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="<https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FcmtKmCJfIuz9HFmCwcJ7%2F%EC%98%88%EC%A0%9C_onAppObjectTouched.zip?alt=media&token=27d50d24-7e1c-477d-aa33-ac3dbecf7d98>" %}

```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="<https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FC4WKZtTpaNEwWuOeIb1t%2F%EC%98%88%EC%A0%9C_onObjectAttacked.zip?alt=media&token=0a5b4ddf-54a1-4166-85f2-3328199eaf5b>" %}

```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>](https://docs.zep.us/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/sidebar-app)

### 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="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FpCZPTQAxllFVfRWjc6XK%2Fimage.png?alt=media&#x26;token=11f18c9c-a56b-42dd-b750-f4ab6147ba39" 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](https://docs.zep.us/zep-script/zep-script-guide/appendix/object-npcproperty)

**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.

![](https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2F2Vi4r03bXszCdcCJswKs%2Fimage.png?alt=media\&token=d3062db3-2447-42c2-a72b-152fc61b9f6c)

⭐ 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="../../zep-script-guide/explore-zep-script/zep-script-example-code/sidebar-app" %}
[sidebar-app](https://docs.zep.us/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/sidebar-app)
{% endcontent-ref %}