# Methods

### Introduction

The following functions provide general features that occur within ZEP such as UI, user control, sound, etc.

Convenient features such as displaying UI on a player’s personal screen, moving players, playing sounds exclusively for a player, etc. are provided below.

### UI

<table><thead><tr><th width="214">Name</th><th>Description</th></tr></thead><tbody><tr><td>showCenterLabel</td><td>Function to display a text for 3 seconds at a specific location to a player</td></tr><tr><td>showCustomLabel</td><td>Function to display a text for 3 seconds at a specific location to a player<br>Text can be decorated by using <code>span</code> tags in the text part.</td></tr><tr><td>showWidget</td><td>Function to call a widget to a specific location to a player</td></tr><tr><td>showBuyAlert</td><td>Function to display a purchase widget to a player and execute a callback function that runs when a purchase is completed</td></tr><tr><td>hideBuyAlert</td><td>Function to hide a player's purchase widget</td></tr><tr><td>sendMessage</td><td>Function to send a private message to a player in the chat window</td></tr><tr><td>showPrompt</td><td>Function to display an input window and execute a callback function that runs according to a player's response.</td></tr><tr><td>showConfirm</td><td>Function to display an confirm window and execute a callback function that runs when a player clicks "OK".</td></tr><tr><td>showAlert</td><td>Function to display an alert window and execute a callback function that runs when a player clicks "OK".</td></tr><tr><td>showWidgetResponsive</td><td>Function to display the widget by defining the top/bottom/left/right margin in percentage to the screen size.</td></tr><tr><td>openWebLink</td><td>Function to open a web URL in a new tab or window to a player </td></tr><tr><td>showEmbed</td><td>Function to open a web URL as an embed.<br>Size and location are adjustable.</td></tr></tbody></table>

### Data Load

<table><thead><tr><th width="215">Name</th><th>Description</th></tr></thead><tbody><tr><td>isEmail</td><td>Function to compare the player’s email</td></tr><tr><td>getLocationName</td><td>Displays the name of the specific location of where the player is standing</td></tr></tbody></table>

### **User Control**

<table><thead><tr><th width="215">Name</th><th>Description</th></tr></thead><tbody><tr><td>spawnAt</td><td>Function to move the player’s avatar to a designated coordinate</td></tr><tr><td>spawnAtLocation</td><td>Function to move the player’s avatar to a designated location</td></tr><tr><td>spawnAtMap</td><td>Function to move a player to another Space or to another map</td></tr></tbody></table>

### Sound

<table><thead><tr><th width="221">Name</th><th>Description</th></tr></thead><tbody><tr><td>playSound</td><td>Function to play a sound file to a player</td></tr><tr><td>playSoundLink</td><td>Function to play the sound URL to a player</td></tr></tbody></table>

### **Common**

<table><thead><tr><th width="222">Name</th><th>Description</th></tr></thead><tbody><tr><td>sendUpdated</td><td>Function to apply the changed value whenever changes are made to any of the field values pertaining to Player</td></tr><tr><td>save</td><td>Function to apply the changed values to whenever changes are made to any Player storage values</td></tr></tbody></table>



## 📚 API Explanation and Example

### 🎨 **UI Methods**

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

<pre class="language-jsx"><code class="lang-jsx">// Displays a text for 3 seconds at a specific location to a player
player.showCenterLabel(text: string, color: uint = 0xFFFFFF, bgColor: uint = 0x000000, offset: int = 0, time: int = 3000)

// Displays a text for 3 seconds at a specific location to a player, customizable
player.showCustomLabel(text: string, color: number = 0xFFFFFF, bgColor: number = 0x000000, offset: number = 0, width = 100, opacity = 0.6, time: int = 3000);

// Calls the corresponding html file as a widget to a specific align location to a player 
player.showWidget(fileName: string, align: string, width: integer, height: integer): ScriptWidget

// Displays a purchase widget to a player and executes a callback function that runs when a purchase is completed
player.showBuyAlert(itemName: string, price: number, callback: function);

// Hides a player's purchase widget
player.hideBuyAlert();

<strong>// Sends a private message to a player in the chat window
</strong>player.sendMessage(message: string, color: number = 0xFFFFFF)

// Displays an input window and execute a callback function that runs according to a player's response
player.showPrompt(text: string, function(inputText))

// Displays an confirm window and execute a callback function that runs when a player clicks "OK"
player.showConfirm(text: string, function(result))

// Displays an alert window and execute a callback function that runs when a player clicks "OK"
player.showAlert(text: string, function())

// Displays the widget by defining the top/bottom/left/right margin in percentage to the screen size
player.showWidgetResponsive(fileName:string, marginTop:number, marginRight:number, marginBottom:number, marginLeft:number)

// Opens a web URL in a new tab or window to a player 
player.openWebLink(url:string, popup:boolean);

// Opens a web URL as an embed
player.showEmbed(url: string, align: string, width: number, height: number, hasBackdrop: boolean = true)
</code></pre>



### showCenterLabel

{% hint style="info" %}
player.showCenterLabel(text: string, color: uint = 0xFFFFFF, bgColor: uint = 0x000000, offset: int = 0, time: number = 3000)
{% endhint %}

This function displays text for 3 seconds at a designated location to the corresponding player.

**Parameters**

<table><thead><tr><th width="148.33333333333331">Name</th><th width="117">Type</th><th>Description</th></tr></thead><tbody><tr><td>text</td><td>String</td><td>Text to display on label</td></tr><tr><td>color</td><td>Unit</td><td>Color of text to be displayed (HexCode)<br>If left blank, it is set to white (0xFFFFFF).<br>➡️<a href="https://www.google.com/search?q=COLOR+PICKER&#x26;sxsrf=ALiCzsbc_6XvOn9SiJdEBkLmfLurJ4tvOA%3A1658153265956&#x26;ei=MWnVYrX3Ocv4wAOXk6-wBg&#x26;ved=0ahUKEwj105mjzoL5AhVLPHAKHZfJC2YQ4dUDCA4&#x26;uact=5&#x26;oq=COLOR+PICKER&#x26;gs_lcp=Cgdnd3Mtd2l6EAMyBAgjECcyBQgAEIAEMgUIABCABDIFCAAQgAQyBQgAEIAEMgUIABCABDIFCAAQgAQyBQgAEIAEMgUIABCABDIFCAAQgAQ6CwgAEIAEELEDEIMBOhEILhCABBCxAxCDARDHARDRAzoRCC4QgAQQsQMQgwEQxwEQrwE6CAgAEIAEELEDOhAIABCABBCHAhCxAxCDARAUOgoIABCABBCHAhAUSgQIQRgASgQIRhgAUABYhRVgvxZoAHABeACAAYwBiAHmC5IBBDAuMTKYAQCgAQHAAQE&#x26;sclient=gws-wiz"><mark style="color:purple;">Color Picker</mark></a></td></tr><tr><td>bgColor</td><td>Unit</td><td>Background color of the message to be displayed as the label<br>If left blank, it is set to black (0xFFFFFF).</td></tr><tr><td>offset</td><td>Integer</td><td>The higher the offset value, the location will be closer to the bottom.<br>If left blank, 0 is the designated value.</td></tr><tr><td>time</td><td>number</td><td>Label display time (ms), default 3000 ms (3 seconds)</td></tr></tbody></table>

**Example**

Display the label as yellow.

<div align="left"><figure><img src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FYYiX6ohocrjHSBLMPOfW%2FUntitled.png?alt=media&#x26;token=876df49b-1bac-4ce5-b509-7092ed2cdde1" alt=""><figcaption></figcaption></figure></div>

```jsx
App.onJoinPlayer.Add(function(player){
	player.showCenterLabel(`${player.name} has entered.`, 0x000000, 0xFFFF00, 500, 2000); // Displays as black text with a yellow background
});
```



### showCustomLabel

{% hint style="info" %}
player.showCustomLabel(text: string, color: number = 0xFFFFFF, bgColor: number = 0x000000, offset: number = 0, width = 100, opacity = 0.6, time: number = 3000);
{% endhint %}

This function displays a text for 3 seconds at a specific location to all players.

You can decorate the text by adding `span` tags to the text.

**Parameters**

<table><thead><tr><th width="121.33333333333331">Name</th><th width="112">Type</th><th>Description</th></tr></thead><tbody><tr><td>text</td><td>String</td><td>Text to display on label (allows <code>span</code> tags)</td></tr><tr><td>color</td><td>Unit</td><td>Color of text to be displayed (HexCode)<br>If left blank, it is set to white (0xFFFFFF).<br>➡️<a href="https://www.google.com/search?q=COLOR+PICKER&#x26;sxsrf=ALiCzsbc_6XvOn9SiJdEBkLmfLurJ4tvOA%3A1658153265956&#x26;ei=MWnVYrX3Ocv4wAOXk6-wBg&#x26;ved=0ahUKEwj105mjzoL5AhVLPHAKHZfJC2YQ4dUDCA4&#x26;uact=5&#x26;oq=COLOR+PICKER&#x26;gs_lcp=Cgdnd3Mtd2l6EAMyBAgjECcyBQgAEIAEMgUIABCABDIFCAAQgAQyBQgAEIAEMgUIABCABDIFCAAQgAQyBQgAEIAEMgUIABCABDIFCAAQgAQ6CwgAEIAEELEDEIMBOhEILhCABBCxAxCDARDHARDRAzoRCC4QgAQQsQMQgwEQxwEQrwE6CAgAEIAEELEDOhAIABCABBCHAhCxAxCDARAUOgoIABCABBCHAhAUSgQIQRgASgQIRhgAUABYhRVgvxZoAHABeACAAYwBiAHmC5IBBDAuMTKYAQCgAQHAAQE&#x26;sclient=gws-wiz"><mark style="color:purple;">Color Picker</mark></a></td></tr><tr><td>bgColor</td><td>Unit</td><td>The background color of the message to be displayed as the label<br>If left blank, it is set to black (0xFFFFFF).</td></tr><tr><td>offset</td><td>number</td><td>The higher the offset value, the location will be closer to the bottom.<br>If left blank, 0 is the designated value.</td></tr><tr><td>width</td><td>number</td><td>A value that sets the label's width to n% (default 100)</td></tr><tr><td>opacity</td><td>number</td><td>A value that sets the label background's transparency (default 0.6, range 0 to 1)</td></tr><tr><td>time</td><td>number</td><td>Label display time (ms), default 3000 ms (3 seconds)</td></tr></tbody></table>

**Example**

Decorate the label using HTML tags.

![](https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FsMhLEIVIlU0ryGSzGcSc%2Fimage.png?alt=media\&token=60b6060e-ae1c-4b31-add0-53c8d587061d)

```jsx
// Activates function when x is pressed
App.addOnKeyDown(88, function (player) {
    // Style of the white box to input x into
      let style =
          "display: inline-block; text-align: center; width:1.2em; height:1.2em; line-height: 1.2em; color: black; background-color: white; font-size: 1.2em; border-radius:3px";
      player.showCustomLabel(
          `You can run the example by pressing the <span style = "${style}">X</span> button.`,
          0xffffff, // white text
          0, // black background
          300, // offset 300
          30, // width 20%
          1, // transparency 1 -> opacity
          5000 // display time 5000 -> for 5 seconds
      );
});

```



### showWidget

{% hint style="info" %}
player.showWidget(fileName: string, align: string, width: integer, height: integer): ScriptWidget
{% endhint %}

This function calls the html file as a widget to the player’s designated align location.

**Parameters**

<table><thead><tr><th width="146">Name</th><th width="94.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>fileName</td><td>String</td><td>Name of the file being called</td></tr><tr><td>align</td><td>String</td><td>Location to display widget<br>’popup’, ‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’</td></tr><tr><td>width<br>height</td><td>Integer</td><td>Width and height size area to display the widget (px)</td></tr></tbody></table>

**Example**

Replicate the Korean consonant quiz widget.

{% file src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FomtBYFKX2cKBL4Y3v7EO%2F%EC%98%88%EC%A0%9C_showWidget(player).zip?alt=media&token=c28b46b3-2e13-4dbf-9791-cca85c2431fd" %}

<div align="left"><figure><img src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FL3SetwBDL4o8xUA0snJI%2FUntitled%201.png?alt=media&#x26;token=44136dd9-1817-460a-ba38-9bc4ffa49ad0" alt=""><figcaption></figcaption></figure></div>

```jsx
let _widget = null;
// Activates when player enters 
App.onJoinPlayer.Add(function (player) {
	_widget = player.showWidget("widget.html", "top", 200, 300); // Displays widget at the top of the screen in an 200x300 area
	_widget.sendMessage({
		timer: 15,
		answer: "ㅅㅍㅋ",
	});
});
```



### showBuyAlert <a href="#showbuyalert" id="showbuyalert"></a>

{% hint style="info" %}
player.showBuyAlert(itemName: string, price: number, callback: function)
{% endhint %}

This function displays a purchase widget to a player and executes a callback function that runs when a purchase is completed.

> The consumed ZEM will be sent to the creators and the history can be found in the [My Donation History](https://zep.us/manage/donations) page.
>
> Please refer to the [Settlement Guide](https://teamzep.notion.site/Settlement-Guide-8291d5141b9848b68184ab597d09f1ae) for more detailed information on ZEP settlement.

**Parameters**

<table><thead><tr><th width="144.33333333333331">Name</th><th width="115">Type</th><th>Description</th></tr></thead><tbody><tr><td>itemName</td><td>String</td><td>Name of the item to display in the purchase widget</td></tr><tr><td>price</td><td>Number</td><td>Price of the item (Currency: ZEM)</td></tr><tr><td>callback</td><td>Function</td><td>Callback functions to execute when a purchase is completed</td></tr><tr><td>payToSpaceOwner</td><td>Boolean</td><td><p>When false: the revenue goes to the app owner</p><p>When true: the revenue goes to the map owner</p><p>(Default value: false)</p></td></tr><tr><td>option</td><td>Object</td><td>You can set the following options.<br><strong><code>message</code></strong> : Sets the text to be displayed in the purchase widget.<br><strong><code>timer</code></strong> : You can set the time (ms) for displaying the purchase widget.</td></tr></tbody></table>

**Example**

Purchase an item and save data in player.storage.

<pre class="language-java" data-overflow="wrap"><code class="lang-java">const itemName = "ITEM";

//Activates function when Q is pressed - Purchase an item and save data in player.storage.
App.addOnKeyDown(81, function (player) {
	let pStorage = JSON.parse(player.storage);
	if (!player.tag) {
		player.tag = {};
	}
	if (pStorage == null) {
		pStorage = {};
	}
	//Displays a message if the item has already been purchased
	if (pStorage[itemName]) {
		player.showCenterLabel(`${itemName} has been already purchased.`);
	} else {
		player.showBuyAlert(itemName, 0, function (success, buyAlertResult) {
			if (success) {
				App.sayToAll(`[Info.] ${player.name} has purchased ${itemName}!`);
				pStorage[itemName] = true;
				player.tag.buyAlertResult = buyAlertResult
				player.storage = JSON.stringify(pStorage);
				player.save();
			}
		}, 
		false,// if false, the revenue goes to the app owner, if true the revenue goes to the Space owner
		{
			message: `${itemName} custom message`,//Highlights a text corresponding to itemName in the message.
			timer: 10000 // 10 seconds - purchase widget display time (ms)
		}
		);
	}
});

<strong>// Activates function when W is pressed - Refund
</strong>App.addOnKeyDown(87, function (player) {
	let pStorage = JSON.parse(player.storage);
	if( pStorage &#x26;&#x26; player.tag.buyAlertResult )
	{	
		if( player.tag.buyAlertResult.Refund() )
		{
			App.sayToAll("===== refund success!");
			pStorage[itemName] = false;
		}
		else {
			App.sayToAll("===== refund failed");
		}
		player.tag.buyAlertResult = null;
		player.storage = JSON.stringify(pStorage);
		player.save();
	}
})
</code></pre>

<div align="left"><figure><img src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2F3tawIdTL7nmvAS9w2tuD%2Fimage.png?alt=media&#x26;token=dc58fdb9-ae01-4116-97d6-69cb45eeaf69" alt=""><figcaption><p>Purchase Menu</p></figcaption></figure></div>

<div align="left"><figure><img src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FgJDmMF95PoaRD6wY3aNa%2Fspaces_iW553XSGeKCAPpImxXi3_uploads_w3iIh8aaz1xR0H0LhsSt_GIF%202023-03-30%20%EC%98%A4%ED%9B%84%205-42-34.webp?alt=media&#x26;token=62c4db2d-6e36-4e50-9c26-15c1854221f3" alt=""><figcaption><p>When 'timer' and 'message' Options Were Set Up</p></figcaption></figure></div>



### hideBuyAlert

{% hint style="info" %}
player.hideBuyAlert()
{% endhint %}

This function closes a player's purchase widget.

**Parameter**

None



### sendMessage

{% hint style="info" %}
&#x20;player.sendMessage(text: string, color: uint = 0xFFFFFF)
{% endhint %}

This function sends a private message to a player in the chat window.

**Parameters**

<table><thead><tr><th width="137.33333333333331">Name</th><th width="131">Type</th><th>Description</th></tr></thead><tbody><tr><td>text</td><td>String</td><td>Text to display on label</td></tr><tr><td>color</td><td>Uint</td><td>Color of text to be displayed (HexCode)<br>If left blank, it is set to white (0xFFFFFF).<br>➡️<a href="https://www.google.com/search?q=COLOR+PICKER&#x26;sxsrf=ALiCzsbc_6XvOn9SiJdEBkLmfLurJ4tvOA%3A1658153265956&#x26;ei=MWnVYrX3Ocv4wAOXk6-wBg&#x26;ved=0ahUKEwj105mjzoL5AhVLPHAKHZfJC2YQ4dUDCA4&#x26;uact=5&#x26;oq=COLOR+PICKER&#x26;gs_lcp=Cgdnd3Mtd2l6EAMyBAgjECcyBQgAEIAEMgUIABCABDIFCAAQgAQyBQgAEIAEMgUIABCABDIFCAAQgAQyBQgAEIAEMgUIABCABDIFCAAQgAQ6CwgAEIAEELEDEIMBOhEILhCABBCxAxCDARDHARDRAzoRCC4QgAQQsQMQgwEQxwEQrwE6CAgAEIAEELEDOhAIABCABBCHAhCxAxCDARAUOgoIABCABBCHAhAUSgQIQRgASgQIRhgAUABYhRVgvxZoAHABeACAAYwBiAHmC5IBBDAuMTKYAQCgAQHAAQE&#x26;sclient=gws-wiz"><mark style="color:purple;">Color Picker</mark></a></td></tr></tbody></table>

**Example**

Display a welcome message that is only shown to the designated player.

![](https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FNgYjfXIPMWoF0AvlElVz%2Fimage.png?alt=media\&token=eaafc84c-8a64-436a-9937-6945638040ad)

```jsx
App.onJoinPlayer.Add(function(player){
    player.sendMessage(`Welcome, ${player.name}!\nhttps://docs.zep.us/ Click the link to check the guide.`,0xffffff);
    });
```



### showPrompt

{% hint style="info" %}
player.showPrompt(text: string, function(inputText))
{% endhint %}

This function displays an input window and executes a callback function that runs according to a player's response.

**Parameters**

<table><thead><tr><th width="174.33333333333331">Name</th><th width="185">Type</th><th>Description</th></tr></thead><tbody><tr><td>text</td><td>String</td><td>Text to display on the input window</td></tr><tr><td>inputText</td><td>String</td><td>Text a player entered</td></tr></tbody></table>

**Example**

Create an input window that shows a "correct" message when entering "1234".

<figure><img src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FpB4bM4uPyTEeNndDof7M%2Fimage.png?alt=media&#x26;token=78e7b1fb-c997-4599-a3c4-6d27fdc095a8" alt=""><figcaption></figcaption></figure>

```javascript
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
	player.showPrompt("🔐 Please enter a password", function (inputText) {
		if (inputText == "1234") {
			player.showCenterLabel("Correct");
		} else {
			player.showCenterLabel("Incorrect");
		}
	});
});
```



### showConfirm

{% hint style="info" %}
player.showConfirm(text: string, function(result))
{% endhint %}

&#x20;This function displays an confirm window and executes a callback function that runs when a player clicks "OK". When a player clicks "Cancel," this callback function doesn't operate.

**Parameters**

<table><thead><tr><th width="174.33333333333331">Name</th><th width="179">Type</th><th>Description</th></tr></thead><tbody><tr><td>text</td><td>String</td><td>Text to display on the confirm window</td></tr><tr><td>result</td><td>Boolean</td><td>When a player clicks "OK", true</td></tr></tbody></table>

**Example**

Display a text to the chat window when "OK" is clicked.

<figure><img src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FFZGY9GcsUtGJGbuNfWDC%2Fimage.png?alt=media&#x26;token=ba4e39e8-9858-4385-a547-251053607375" alt=""><figcaption></figcaption></figure>

```javascript
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
	player.showConfirm("confirm", (result) => {
		App.sayToAll(result);
	});
});
```

### showAlert

{% hint style="info" %}
&#x20;player.showAlert(text: string, function())
{% endhint %}

This function displays an alert window and executes a callback function that runs when a player clicks "OK".

**Parameter**

<table><thead><tr><th width="174.33333333333331">Name</th><th width="214">Type</th><th>Description</th></tr></thead><tbody><tr><td>text</td><td>String</td><td>Text to display on the alert window</td></tr></tbody></table>

**Example**

Display a text to the chat window when "OK" is clicked.

<figure><img src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FmN4ntx4F5xxax1cLI6Sn%2Fimage.png?alt=media&#x26;token=9221404b-5df2-4191-9905-3cb3f45df1b8" alt=""><figcaption></figcaption></figure>

```javascript
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
	player.showAlert("alert", () => {
		App.sayToAll(player.name + " show alert.");
	});
});
```

### showWidgetResponsive

{% hint style="info" %}
```
player.showWidgetResponsive(fileName:string, marginTop:number, marginRight:number, marginBottom:number, marginLeft:number)
```
{% endhint %}

This function displays the widget by defining the top/bottom/left/right margin using a responsive percentage of the screen size.

**Parameters**

<table><thead><tr><th width="206.33333333333331">Name</th><th width="104">Type</th><th>Description</th></tr></thead><tbody><tr><td>fileName</td><td>String</td><td>Name of the file to call</td></tr><tr><td>margin top/left/right/bottom</td><td>String</td><td>Top/bottom/left/right margin as a percentage</td></tr></tbody></table>

**Example**

Check how the widget size changes when scaling the screen size.

{% file src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FiezlJfWQ5arHsV2ucCV1%2FshowWidgetResponsive.zip?alt=media&token=1801a388-6e38-4010-a41a-88e2b6b83d69" %}

<figure><img src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2Fr9fOxnehQDPz8q7v4UrM%2FwidgetResponsive.gif?alt=media&#x26;token=c8400aa1-d995-4ce5-9d4c-e16f2080f0f1" alt=""><figcaption></figcaption></figure>

```javascript
App.onJoinPlayer.Add(function (player) {
	player.tag = {};
});

// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
	player.tag.widget = player.showWidgetResponsive("result.html", 15, 15, 15, 15);
	player.tag.widget.onMessage.Add(function (player, data) {
		if (data.type == "close") {
			player.tag.widget.destroy();
			player.tag.widget = null;
		}
	});
});
```

### openWebLink

{% hint style="info" %}
```
player.openWebLink(url:string, popup:boolean=false)
```
{% endhint %}

This function opens a web URL in a new tab or window to a player.

**Parameters**

<table><thead><tr><th width="206.33333333333331">Name</th><th width="104">Type</th><th>Description</th></tr></thead><tbody><tr><td>url</td><td>String</td><td>URL adress to open</td></tr><tr><td>popup</td><td>boolean</td><td>When true: the URL opens as a new window</td></tr></tbody></table>

**Example**

Open a web URL in a new windwow.

```javascript
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
	player.openWebLink("https://docs-kr.zep.us", true);
});
```

<figure><img src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FBeBpa9BVVlOihsaEKMep%2Fimage.png?alt=media&#x26;token=e5af26b6-2bc7-4d52-b0c2-36fcab2080ac" alt=""><figcaption><p>Web Page in a New Window</p></figcaption></figure>



### showEmbed

{% hint style="info" %}
player.showEmbed(url: string, align: string, width: number, height: number, hasBackdrop: boolean = true)
{% endhint %}

This function opens a web URL as an embed in the designated location.

**Parameters**

<table><thead><tr><th width="153.33333333333331">Name</th><th width="104">Tyoe</th><th>Description</th></tr></thead><tbody><tr><td>url</td><td>String</td><td>URL adress to open</td></tr><tr><td>align</td><td>String</td><td>Embedding area<br>‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’</td></tr><tr><td>width<br>height</td><td>number</td><td>Width and hight size of the embedding area (px)</td></tr><tr><td>hasBackdrop</td><td>boolean</td><td>When true:  shadows appear on the outline of the embedding area</td></tr></tbody></table>

**Example**

Display a web URL as an embed

```javascript
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
	player.showEmbed("https://youtu.be/ztuTrpXJyks", "middle", 900, 600, true);
});
```

## 💻 Data Load Methods

<mark style="background-color:yellow;">**Data Load Methods at a Glance**</mark>

```jsx
// Compares the player's email with the specified email 
player.isEmail(email: string): boolean

// Calls the area location name of where the player is standing
player.getLocationName(): string
```

### isEmail

{% hint style="info" %}
player.isEmail(email: string): boolean
{% endhint %}

Depending on whether the corresponding player’s email is the same as the parameter value, the value will return as true when it matches and false when it does not match.

**Parameter**

<table><thead><tr><th width="126.33333333333331">Name</th><th width="117">Type</th><th>Description</th></tr></thead><tbody><tr><td>email</td><td>String</td><td>Email text that will be used for comparison</td></tr></tbody></table>

**Example**

Compare the player’s email to the specified text.

```jsx
// Activates function when q is pressed 
// **[App.addOnKeyDown Description (Link)](https://www.notion.so/Callbacks-7ac5078bab7c4f3180ae05463713581d)**
App.addOnKeyDown(81,function(player){
	let check = player.isEmail("supercat@supercat.co.kr");
	App.sayToAll(`check if the email matches: ${check}`)
})
```



### getLocationName

{% hint style="info" %}
&#x20;player.getLocationName : string
{% endhint %}

This displays the location name of where the player is standing.

Specific areas can be set up on the **Map Editor > Tile Effects** menu.

**Parameter**

* None

**Example**

Display the area name of the tile the avatar is standing on.

→ If there is no specified area set, it will be displayed as an empty space.

```jsx
// Activates function when q is pressed 
//App.addOnKeyDown Description 
App.addOnKeyDown(81,function(player){
	App.sayToAll(`Current area where the player is standing: ${player.getLocationName()}`)
})
```



## 🙍‍♂️ **User Control**

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

```jsx
// Spawns the player to the corresponding coordinates
player.spawnAt(tileX: int ,tileY: int, dir: int = 0)

// Spawns the player to the corresponding area 
player.spawnAtLocation(name: string ,dir:int = 0)

// Moves the player to the corresponding space's map 
player.spawnAtMap(spaceHashID string, mapHashID:string = null)
```



### spawnAt

{% hint style="info" %}
player.spawnAt(tileX: int ,tileY: int, dir: int = 0)
{% endhint %}

This moves the player’s avatar to look in the designated direction when on tileX and tileY coordinates.

**Parameters**

<table><thead><tr><th width="123.33333333333331">Name</th><th width="111">Type</th><th>Description</th></tr></thead><tbody><tr><td>tileX<br>tileY</td><td>Integer</td><td>The x and y coordinates values of where the player will be moved to</td></tr><tr><td>dir</td><td>Integer</td><td>Direction the avatar will look at<br>• Left: 1 • Up: 2 • Right: 3 • Down: 4<br>• Top-Left: 5 • Bottom-Left: 6 • Top-Right: 7 • Bottom-Right: 8</td></tr></tbody></table>

**Example**

Move the players that enter to the designated coordinates.

```jsx
// Activates function when a player enters
App.onJoinPlayer.Add(function (player) {
	player.spawnAt(5, 5, 1); // Moves the player to the 5,5 location and has them look to the left
});
```



### spawnAtLocation

{% hint style="info" %}
player.spawnAtLocation(name: string, dir:int = 0)
{% endhint %}

This moves the player’s avatar to a specific area called name and makes them look in a designated direction.

**Parameters**

<table><thead><tr><th width="111.33333333333331">Name</th><th width="113">Type</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>String</td><td>Name of the specific are the player will be moved to</td></tr><tr><td>dir</td><td>Integer</td><td>Direction the avatar will look at<br>• Left: 1 • Up: 2 • Right: 3 • Down: 4<br>• Top-Left: 5 • Bottom-Left: 6 • Top-Right: 7 • Bottom-Right: 8</td></tr></tbody></table>

**Example**

Move the players that enter to a specific area.

{% hint style="danger" %}
When there is more than one specific area with the same name, the player will be moved to one of those locations randomly.
{% endhint %}

```jsx
// Activates function when a player enters
App.onJoinPlayer.Add(function (player) {
// Spawns the player to the specific area called "test" and have them look to the left
	player.spawnAtLocation("test", 1); 
});
```



### spawnAtMap

{% hint style="info" %}
player.spawnAtMap(spaceHashID string, mapHashID:string = null)
{% endhint %}

This moves the player to the corresponding Space’s map.

**Parameters**

<table><thead><tr><th width="163.33333333333331">Name</th><th width="109">Type</th><th>Description</th></tr></thead><tbody><tr><td>spaceHashID</td><td>String</td><td>spaceHashID of the Space the player will be moved to</td></tr><tr><td>mapHashID</td><td>String</td><td>If the mapHashID is not mentioned, by default the player will be moved to the “Entry Map” of the corresponding Space.</td></tr></tbody></table>

**Example**

Move the players that enter the map to the ZEP Tutorial Map. ([<mark style="color:purple;">Understanding Spaces and Maps</mark>](../../zep-script-guide/appendix/understanding-spaces-and-maps))

```jsx
// Activates function when a player enters
App.onJoinPlayer.Add(function (player) {
	// Moves the player to the ZEP tutorial map 
	player.spawnAtMap("65jeBA", "2YvXMJ");
});
```



## 🔉 Sound Methods

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

```jsx
// Plays sound to the player 
player.playSound(fileName: string, loop: boolean = false)

// Plays the corresponding sound from the link to the player 
player.playSoundLink(link: string, loop: boolean = false)
```



### playSound

{% hint style="info" %}
player.playSound(fileName: string, loop: boolean = false, overlap: boolean = false)
{% endhint %}

This function plays sound to the corresponding player.

**Parameters**

<table><thead><tr><th width="128">Name</th><th width="98">Type</th><th>Description</th></tr></thead><tbody><tr><td>fileName</td><td>String</td><td>Name of the file being called</td></tr><tr><td>loop</td><td>boolean</td><td>true: repeatedly play on a loop<br>false: play one time</td></tr><tr><td>overlap</td><td>boolean</td><td>Whether sound overlap is available</td></tr></tbody></table>

**Example**

Set up a sound to play upon entry (file).

{% file src="https://3059601135-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MkvEvcz_LX5eDyvl13E%2Fuploads%2FelmeDts97HqqngNBz4Pi%2Fjoin.mp3?alt=media&token=6428acc7-8a92-4fc8-8a54-96495c2a9686" %}

```jsx
// Activates function when a player enters
App.onJoinPlayer.Add(function (player) {
	player.playSound("join.mp3",false);
});
```



### playSoundLink

{% hint style="info" %}
player.playSoundLink(link: string, loop: boolean = false)
{% endhint %}

This function plays a sound for all players.

{% hint style="success" %}
When the sound does not play even when the correct link is inputted.

It is highly likely that a CORS regulation was violated. In the case that a CORS regulation cannot be met, please upload the sound file and use the playSound function instead of the playSound Link function.
{% endhint %}

**Parameters**

<table><thead><tr><th width="126.33333333333331">Name</th><th width="117">Type</th><th>Description</th></tr></thead><tbody><tr><td>link</td><td>String</td><td>Sound url</td></tr><tr><td>loop</td><td>boolean</td><td>true: repeatedly play on a loop<br>false: play one time</td></tr></tbody></table>

**Example**

Set up a sound to play upon entry (sound url).

```jsx
// Activates function when a player enters
App.onJoinPlayer.Add(function (player) {
	player.playSoundLink("https://zep.us/assets/sounds/ring.mp3",false);
});
```



## 💠 Common **Methods**

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

```jsx
// Updates any player's field values that were changed 
player.sendUpdated()

// Saves the player's storage value 
player.save()
```



### sendUpdated

{% hint style="info" %}
player.sendUpdated()
{% endhint %}

This function applies the changed value whenever field values pertaining to App or Player are changed.

**Parameter**

* None



### save

{% hint style="info" %}
player.save()
{% endhint %}

This function applies the changed value whenever values pertaining to App or Player storage are changed.

**Parameter**

* None
