# 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

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

### Data Load

Name	Description
isEmail	Function to compare the player’s email
getLocationName	Displays the name of the specific location of where the player is standing

### **User Control**

Name	Description
spawnAt	Function to move the player’s avatar to a designated coordinate
spawnAtLocation	Function to move the player’s avatar to a designated location
spawnAtMap	Function to move a player to another Space or to another map

### Sound

Name	Description
playSound	Function to play a sound file to a player
playSoundLink	Function to play the sound URL to a player

### **Common**

Name	Description
sendUpdated	Function to apply the changed value whenever changes are made to any of the field values pertaining to Player
save	Function to apply the changed values to whenever changes are made to any Player storage values

## 📚 API Explanation and Example ### 🎨 **UI Methods** **UI at a Glance**

// 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();

// Sends a private message to a player in the chat window
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)

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

Name	Type	Description
text	String	Text to display on label
color	Unit	Color of text to be displayed (HexCode) If left blank, it is set to white (0xFFFFFF). ➡️Color Picker
bgColor	Unit	Background color of the message to be displayed as the label If left blank, it is set to black (0xFFFFFF).
offset	Integer	The higher the offset value, the location will be closer to the bottom. If left blank, 0 is the designated value.
time	number	Label display time (ms), default 3000 ms (3 seconds)

**Example** Display the label as yellow.

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

Name	Type	Description
text	String	Text to display on label (allows `span` tags)
color	Unit	Color of text to be displayed (HexCode) If left blank, it is set to white (0xFFFFFF). ➡️Color Picker
bgColor	Unit	The background color of the message to be displayed as the label If left blank, it is set to black (0xFFFFFF).
offset	number	The higher the offset value, the location will be closer to the bottom. If left blank, 0 is the designated value.
width	number	A value that sets the label's width to n% (default 100)
opacity	number	A value that sets the label background's transparency (default 0.6, range 0 to 1)
time	number	Label display time (ms), default 3000 ms (3 seconds)

**Example** Decorate the label using HTML tags. ![](/files/b1soWdVMlEUhjkgkgIb9) ```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 X 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**

Name	Type	Description
fileName	String	Name of the file being called
align	String	Location to display widget ’popup’, ‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’
width height	Integer	Width and height size area to display the widget (px)

**Example** Replicate the Korean consonant quiz widget. {% file src="/files/h9F9tY4b6MC3PgPS9Ccy" %}

```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 {% 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**

Name	Type	Description
itemName	String	Name of the item to display in the purchase widget
price	Number	Price of the item (Currency: ZEM)
callback	Function	Callback functions to execute when a purchase is completed
payToSpaceOwner	Boolean	When false: the revenue goes to the app owner When true: the revenue goes to the map owner (Default value: false)
option	Object	You can set the following options. `message` : Sets the text to be displayed in the purchase widget. `timer` : You can set the time (ms) for displaying the purchase widget.

**Example** Purchase an item and save data in player.storage.

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)
		}
		);
	}
});

// Activates function when W is pressed - Refund
App.addOnKeyDown(87, function (player) {
	let pStorage = JSON.parse(player.storage);
	if( pStorage && 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();
	}
})

When 'timer' and 'message' Options Were Set Up

### hideBuyAlert {% hint style="info" %} player.hideBuyAlert() {% endhint %} This function closes a player's purchase widget. **Parameter** None ### sendMessage {% hint style="info" %} player.sendMessage(text: string, color: uint = 0xFFFFFF) {% endhint %} This function sends a private message to a player in the chat window. **Parameters**

Name	Type	Description
text	String	Text to display on label
color	Uint	Color of text to be displayed (HexCode) If left blank, it is set to white (0xFFFFFF). ➡️Color Picker

**Example** Display a welcome message that is only shown to the designated player. ![](/files/cuGfdJHBJmSxKFG0d5Iz) ```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**

Name	Type	Description
text	String	Text to display on the input window
inputText	String	Text a player entered

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

```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 %} 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**

Name	Type	Description
text	String	Text to display on the confirm window
result	Boolean	When a player clicks "OK", true

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

```javascript // Activates function when q is pressed App.addOnKeyDown(81, function (player) { player.showConfirm("confirm", (result) => { App.sayToAll(result); }); }); ``` ### showAlert {% hint style="info" %} 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**

Name	Type	Description
text	String	Text to display on the alert window

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

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

Name	Type	Description
fileName	String	Name of the file to call
margin top/left/right/bottom	String	Top/bottom/left/right margin as a percentage

**Example** Check how the widget size changes when scaling the screen size. {% file src="/files/ABiTDBeAVLtByk4zkXF1" %}

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

Name	Type	Description
url	String	URL adress to open
popup	boolean	When true: the URL opens as a new window

**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); }); ```

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

Name	Tyoe	Description
url	String	URL adress to open
align	String	Embedding area ‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’
width height	number	Width and hight size of the embedding area (px)
hasBackdrop	boolean	When true: shadows appear on the outline of the embedding area

**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 **Data Load Methods at a Glance** ```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**

Name	Type	Description
email	String	Email text that will be used for comparison

**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" %} 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** **User Control at a Glance** ```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**

Name	Type	Description
tileX tileY	Integer	The x and y coordinates values of where the player will be moved to
dir	Integer	Direction the avatar will look at • Left: 1 • Up: 2 • Right: 3 • Down: 4 • Top-Left: 5 • Bottom-Left: 6 • Top-Right: 7 • Bottom-Right: 8

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

Name	Type	Description
name	String	Name of the specific are the player will be moved to
dir	Integer	Direction the avatar will look at • Left: 1 • Up: 2 • Right: 3 • Down: 4 • Top-Left: 5 • Bottom-Left: 6 • Top-Right: 7 • Bottom-Right: 8

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

Name	Type	Description
spaceHashID	String	spaceHashID of the Space the player will be moved to
mapHashID	String	If the mapHashID is not mentioned, by default the player will be moved to the “Entry Map” of the corresponding Space.

**Example** Move the players that enter the map to the ZEP Tutorial Map. ([Understanding Spaces and Maps](/zep-script/zep-script-guide/appendix/understanding-spaces-and-maps.md)) ```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 **Sound Methods at a Glance** ```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**

Name	Type	Description
fileName	String	Name of the file being called
loop	boolean	true: repeatedly play on a loop false: play one time
overlap	boolean	Whether sound overlap is available

**Example** Set up a sound to play upon entry (file). {% file src="/files/5LOpJdHZOfVW9UOoRMSJ" %} ```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**

Name	Type	Description
link	String	Sound url
loop	boolean	true: repeatedly play on a loop false: play one time

**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** **Common Methods at a Glance** ```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 --- # 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/scriptplayer/methods.md?ask= ``` 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.