# Methods ### Introduction These functions provide convenient techniques such as UI display, moving or kicking users, and playing sound. Methods can be divided into [**UI**](#ui)**,** [**User Control**](#user-control)**,** [**Sound**](#sound)**,** [**Communication**](#communication)**,** and [**Common**](#common) depending on their purpose. ### UI

Name	Description
loadSpritesheet	Function to read a sprite sheet picture file and make it an object
showCenterLabel	Function to display text for 3 seconds at the designated location for all players
showCustomLabel	Function to display text for 3 seconds at the designated location for all players You can decorate text by inserting `span` tags in the text part.
showWidget	Function to load the HTML file as a widget at the align position specified for all players
showYoutubeWidget	Function to call the YouTube video corresponding to the link to the widget

### **User Control**

Name	Description
spawnPlayer	Function to move players to the designated X and Y coordinates
kickPlayer	Function to kick players
forceDestroy	Function to shut down the mini-game app
clearChat	Function to delete all chat history
getPlayerByID	Function to return a player corresponding to an id

### Sound

Name	Description
playSound	Function to play the sound file
playSoundLink	Function to play the sound URL
stopSound	Function to stop all the playing sound
changeAttackSound	Function to change the poke (Z key) sound effects

### Communication

Name	Description
httpGet	Function to request for HTTP Get
httpPost	Function to request for HTTP Post
httpPostJson	Function to request for HTTP Post in JSON

### Common

Name	Description
sendUpdated	Function to apply the updated app/player-related field values when changes are made
save	Function to apply the updated app/player storage values

## 📚 API Explanation and Example ### 🎨 **UI Methods** **UI at a Glance** ```jsx // Reads a sprite sheet picture file, making it an object App.loadSpritesheet(fileName: string, frameWidth: integer, frameHeight: integer, anims: array, frameRate: integer): ScriptDynamicResource // Displays text for 1 second at the designated location for all players App.showCenterLabel(text: string, color: uint = 0xFFFFFF, bgColor: uint = 0x000000, offset: int = 0) // Displays text for 1 second at the designated location for all players, customizable App.showCustomLabel(text: string, color: number = 0xFFFFFF, bgColor: number = 0x000000, offset: number = 0, width = 100, opacity = 0.6); // Displays text in the chat window App.sayToAll(text: string, color: uint = 0xFFFFFF) // Loads the corresponding HTML file as a widget at the align position specified for all players App.showWidget(fileName: string, align: string, width: integer, height: integer): ScriptWidget // Plays the video from the YouTube link at the specified align position for all players App.showYoutubeWidget(link: string, align: string, width: integer, height: integer): ScriptWidget ``` ### loadSpritesheet {% hint style="info" %} App.loadSpritesheet(fileName: string, frameWidth: integer, frameHeight: integer, anims: array, frameRate: integer): ScriptDynamicResource {% endhint %} This function reads a sprite sheet picture file and makes it an object. To better understand ScriptDynamicResource, please refer to the [Understanding Sprite Sheets](/zep-script/zep-script-guide/appendix/understanding-sprite-sheets.md) page. **Parameters**

Name	Type	Description
fileName	String	Name of the file to be loaded
frameWidth frameHeight	Integer	The frame’s width and height pixel size
anims	Array	Array of frame image numbers to be set as animation
frameRate	Integer	Rate of data displayed per frame frameRate: 8 → displays 8 images per second

**Example** Paintman - Apply a Blueman sprite image {% file src="/files/YwgdxBSfI7HogLMbJTjj" %} ```jsx // One frame's size 48x64 let blueman = App.loadSpritesheet('blueman.png', 48, 64, { left: [5, 6, 7, 8, 9], // image moving left up: [15, 16, 17, 18, 19], down: [0, 1, 2, 3, 4], right: [10, 11, 12, 13, 14], dance: [20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37], down_jump: [38], left_jump: [39], right_jump: [40], up_jump: [41], }, 8); // Avatar image changes when the player enters App.onJoinPlayer.Add(function(player){ player.sprite = blueman; player.sendUpdated(); }); ``` ### showCenterLabel {% hint style="info" %} App.showCenterLabel(text: string, color: uint = 0xFFFFFF, bgColor: uint = 0x000000, offset: int = 0, time: number = 3000) {% endhint %} This function displays text for 3 seconds at the designated location for all players. **Parameters**

Name	Type	Description
text	String	Text to display on the 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 label where a message is displayed If left blank, it is set to black (0x000000).
offset	Integer	The larger the offset value, the closer the displayed position is toward the bottom of the screen. If left blank, it is set to 0.
time	number	Label display time (ms), default 3000 ms (3 seconds)

**Example** ssDisplay a message label with the yellow background.

```jsx App.onJoinPlayer.Add(function(player){ App.showCenterLabel(`${player.name} has entered.`, 0x000000, 0xFFFF00, 200, 2000); // Display with the yellow background and black text }); ``` ### showCustomLabel {% hint style="info" %} App.showCustomLabel(text: string, color: number = 0xFFFFFF, bgColor: number = 0x000000, offset: number = 0, width = 100, opacity = 0.6, time: number = 3000); {% endhint %} This function displays text for 1 second at the designated location for all players. You can decorate text by inserting `span` tags in the text part. **Parameters**

Name	Type	Description
text	String	Text to display on the label (span tags allowed)
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 label where a message is displayed If left blank, it is set to black (0x000000).
offset	number	The larger the offset value, the closer the displayed position is toward the bottom of the screen. If left blank, it is set to 0.
width	number	Value to set the label‘s width to n%. (default value: 100)
opacity	number	Value to set the transparency of the label’s background (default value: 0.6, range: 0-1)
time	number	Label display time (ms), default 3000 ms (3 seconds)

**Example** Format the label based on the HTML tags.

```jsx // Activates function when q is pressed App.addOnKeyDown(88, function (player) { // Style of the box to put x in 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"; App.showCustomLabel( `You can run the example by pressing the X button.`, 0xffffff, // white text 0, // black background 300, // offset 300 20, // width 20% 1 // transparency 1 -> opacity ); }); ``` ### sayToAll {% hint style="info" %} App.sayToAll(text: string, color: uint = 0xFFFFFF) {% endhint %} This function displays text in the chat window. **Parameters**

Name	Type	Description
text	String	Text to display in the chat window
color	Unit	Color of text to be displayed (HexCode) If left blank, it is set to white (0xFFFFFF). ➡️Color Picker

**Example** Display an entrance message in light blue.

```jsx // Executes when a player enters App.onJoinPlayer.Add(function (player) { App.sayToAll(`${player.name} has entered.`, 0x00ffff); // Displays in light blue }); ``` ### showWidget {% hint style="info" %} App.showWidget(fileName: string, align: string, width: integer, height: integer): ScriptWidget {% endhint %} This function loads the HTML file as a widget at the align position specified for all players. **Parameters**

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

**Example** Create a Hangul game widget. {% file src="/files/d35Asvsn12MVyFJN3aVK" %}

```jsx let _widget = null; // Executes when a player enters App.onJoinPlayer.Add(function (player) { _widget = App.showWidget("widget.html", "top", 200, 300); // Displays the widget at the top of the screen in the 200x300 area _widget.sendMessage({ timer: 15, answer: "ㅅㅍㅋ", }); }); ``` ### showYoutubeWidget {% hint style="info" %} App.showYoutubeWidget(link: string, align: string, width: integer, height: integer): ScriptWidget {% endhint %} This function calls the YouTube video corresponding to the link to the widget. **Parameters**

Name	Type	Description
link	String	YouTube video’s url
align	String	Where to display the widget ’popup’, ‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’
width height	Integer	Width and height of the area to display the widget (px)

**Example** Display a YouTube widget.

```jsx // Executes when a player enters App.onJoinPlayer.Add(function (player) { App.showYoutubeWidget("https://www.youtube.com/watch?v=SXnMGIR8cjY","top",600,500); }); ``` ## 🙍‍♂️**User Control Methods** **User Control at a Glance** ```jsx // Moves the player corresponding to playerID to tileX, tileY coordinates App.spawnPlayer(playerID: string, tileX: integer, tileY: integer) // Kicks the player corresponding to playerID // The kicked user will not be able to access the space for 24 hours. App.kickPlayer(playerID: string) // Shuts down the mini-game app App.forceDestroy(); // Deletes all chat history. App.clearChat(); //Retuns a player corresponding to the id App.getPlayerID(playerID:string); ``` ### spawnPlayer {% hint style="info" %} App.spawnPlayer(playerID: string, tileX: integer, tileY: integer) {% endhint %} This function moves the player corresponding to playerID to tileX and tileY coordinates. **Parameters**

Name	Type	Description
playerID	String	The player’s ID value
tileX tileY	Integer	The X and Y coordinates to move the player

**Example** Move an entering player to the designated coordinates. ```jsx // Executes when a player enters App.onJoinPlayer.Add(function (player) { App.spawnPlayer(player.id, 5, 5); // Moves the player to 5, 5 }); ``` ### kickPlayer {% hint style="info" %} App.kickPlayer(playerID: string) {% endhint %} This function kicks the player corresponding to playerID. **Parameter**

Name	Type	Description
playerID	String	The player’s ID value

**Example** Create a command for kicking. ⛔ The kicked user will not be able to access the Space for 24 hours. Please use this command carefully. ```jsx // Executes when a player enters chat // Command format '!nickname to kick' App.onSay.Add(function (player, text) { let players = App.players; if (text.indexOf("!Kick") == 0) { let nickname = text.slice(4); for (let i in players) { let p = players[i]; if (p.name == nickname) { App.kickPlayer(p.id); break; } } } }); ``` ### ### forceDestroy {% hint style="info" %} App.forceDestroy(); {% endhint %} This function shuts down the mini-game app. **Example** End the mini-game app by force. ``` // Activates function when q is pressed App.addOnKeyDown(81, function (player) { App.forceDestroy(); }); ``` ### ### clearChat {% hint style="info" %} App.clearChat(); {% endhint %} This function deletes all chat history. **Example** Press Q to delete the chat history. ```jsx // Activates function when q is pressed App.addOnKeyDown(81, function (player) { App.clearChat(); }); ``` ### ### getPlayerByID {% hint style="info" %} App.getPlayerByID(playerID: string); {% endhint %} This function returns a player corresponding to the id. **Example** How to use App.getPlayerByID ```jsx // Activates function when q is pressed App.addOnKeyDown(81, function (player) { const myPlayer = App.getPlayerByID(player.id); }); ``` ## 🔉 **Sound Methods** **Sound at a Glance** ```jsx // Plays the sound file to all players App.playSound(fileName: string, loop: boolean = false) // Plays the sound corresponding to the link to all players App.playSoundLink(link: string, loop: boolean = false) // Stops all playing sounds App.stopSound() // Changes the poke (Z key) sound effects App.changeAttackSound(fileName:string) ``` ### playSound {% hint style="info" %} App.playSound(fileName: string, loop: boolean = false) {% endhint %} This function plays the sound file to all players. **Parameters**

Name	Type	Description
fileName	String	Name of the file to be loaded
loop	boolean	true: play on repeat false: play once

**Example** Apply entrance music when a player enters (file). {% file src="/files/zUOeUpWps95aXuKgp9JX" %} ```jsx // Executes when a player enters App.onJoinPlayer.Add(function (player) { App.playSound("join.mp3",false); }); ``` ### playSoundLink {% hint style="info" %} App.playSoundLink(link: string, loop: boolean = false) {% endhint %} This function plays the sound corresponding to the link to all players. {% hint style="success" %} When the link does not play even though it is correct: You have probably violated the CORS policy. If you cannot follow the CORS policy, it is recommended to use playSound by uploading the music file instead of playSoundLink. {% endhint %} **Parameters**

Name	Type	Description
link	String	Sound url
loop	boolean	true: play on repeat false: play once

**Example** Apply the entrance music when a player enters (sound url). ```jsx // Executes when a player enters App.onJoinPlayer.Add(function (player) { App.playSoundLink("https://zep.us/assets/sounds/ring.mp3",false); }); ``` ### stopSound {% hint style="info" %} App.stopSound(); {% endhint %} This function stops all playing sounds. **Parameter** * None **Example** Create a function that stops sound upon pressing q. ```jsx // Activates function when q is pressed App.addOnKeyDown(81,function(p){ App.stopSound(); }) ``` ### changeAttackSound {% hint style="info" %} App.changeAttackSound(fileName:string) {% endhint %} This function changes the poke (Z key) sound effects. **Parameter**

Name	Type	Description
fileName	String	Name of the sound file to use

**Example** How to use changeAttackSound ```javascript App.onStart.Add(function(){ App.changeAttackSound("attack.mp3"); })j ``` ## 📡 Communication **Methods** **Communication at a Glance** ```jsx // Executes HTTP Get request to the URL App.httpGet(url: string, headers: object, callback: ((string) => void)) // Executes HTTP Get posting to the URL App.httpPost(url: string, headers: object, body: object, callback: ((string) => void)) // Executes HTTP Post to the URL App.httpPostJson(url: string, headers: object, body: object, callback: ((string) => void)) ``` ### httpGet {% hint style="info" %} App.httpGet(url: string, headers: object, function(res: string){}) {% endhint %} This function calls for HTTP Get request. **Parameters**

Name	Type	Description
url	String	Address to send the request to
headers	Object	Request header
res	String	Response to the request

**Example** Change the nickname of an entering player using [Korean Nickname Generator](https://nickname.hwanmoo.kr/) API.

```jsx // Executes when a player enters App.onJoinPlayer.Add(function (player) { App.httpGet( "https://nickname.hwanmoo.kr/?format=json&count=1&max_length=6&whitespace=_", null, function (res) { // Change the response to a json object let response = JSON.parse(res); player.name = response.words[0]; player.sendUpdated(); } ); }); ``` ### httpPost {% hint style="info" %} App.httpPost(url: string, headers: object, body: object, function(res: string)) {% endhint %} This function calls for HTTP Post request. **Parameters**

Name	Type	Description
url	String	Address to send the request to
headers	Object	Request header
body	Object	Request body (form data)
res	String	Response to the request

**Example** Receive the header and data sent by the app as a response and display in the chat window. As shown in the example, key and value should be written in the form of a string, and the requesting server should receive form data and be able to process it. ```jsx // Activates function when q is pressed App.addOnKeyDown(81, function (player) { App.httpPost( "https://postman-echo.com/post", { "test-header": "zep", }, { "id": "ox2wd", "name": "zepscript", "number" : "5" }, (res) => { // Changes the response to a json object let response = JSON.parse(res); App.sayToAll(`header sent: ${response.headers["test-header"]}`, 0xffffff); App.sayToAll(`data sent: ${response.form.id}`, 0xffffff); App.sayToAll(`data sent: ${response.form.name}`, 0xffffff); App.sayToAll(`data sent: ${response.form.number}`, 0xffffff); } ); }); ``` ### httpPostJson {% hint style="info" %} App.httpPostJson(url: string, headers: object, body: object, function(res: string)) {% endhint %} This function calls for HTTP Post request in JSON. **Parameters**

Name	Type	Description
url	String	Address to send the request to
headers	Object	Request header. If blank, enter { }.
body	Object	Request body (JSON data)
res	String	Response to the request

**Example** Receive the data sent by the app as a response and display in the chat window. ```jsx // Activates function when q is pressed App.addOnKeyDown(81, function (player) { App.httpPostJson( "https://postman-echo.com/post", {}, { name: "zepscript", }, (res) => { App.sayToAll(`${res}`, 0xffffff); // Changes the response to a json object let response = JSON.parse(res); App.sayToAll(`data sent: ${response.data.name}`, 0xffffff); } ); }); ``` ## 💠 **Common Methods** **Common Methods at a Glance** ```jsx // Applies the changed values whenever App related field values are changed App.sendUpdated() // Saves App storage value App.save() ``` *** ### sendUpdated {% hint style="info" %} App.sendUpdated() {% endhint %} This function applies the updated app-related field values when changes are made. **Parameter** * None ### save {% hint style="info" %} App.save() {% endhint %} This function applies the updated app storage values when changes are made. **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/scriptapp/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.