Methods
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.
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. |
Name | Description |
|---|---|
isEmail | Function to compare the player’s email |
getLocationName | Displays the name of the specific location of where the player is standing |
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 |
Name | Description |
|---|---|
playSound | Function to play a sound file to a player |
playSoundLink | Function to play the sound URL to a player |
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 |
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)
player.showCenterLabel(text: string, color: uint = 0xFFFFFF, bgColor: uint = 0x000000, offset: int = 0, time: number = 3000)
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.
App.onJoinPlayer.Add(function(player){
player.showCenterLabel(`${player.name} has entered.`, 0x000000, 0xFFFF00, 500, 2000); // Displays as black text with a yellow background
});
player.showCustomLabel(text: string, color: number = 0xFFFFFF, bgColor: number = 0x000000, offset: number = 0, width = 100, opacity = 0.6, time: number = 3000);
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.
// 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
);
});
player.showWidget(fileName: string, align: string, width: integer, height: integer): ScriptWidget
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.
예제_showWidget(player).zip
1KB
Binary
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: "ㅅㅍㅋ",
});
});
player.showBuyAlert(itemName: string, price: number, callback: function)
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 page.
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();
}
})
Purchase Menu
When 'timer' and 'message' Options Were Set Up
player.hideBuyAlert()
This function closes a player's purchase widget.
Parameter
None
player.sendMessage(text: string, color: uint = 0xFFFFFF)
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.
App.onJoinPlayer.Add(function(player){
player.sendMessage(`Welcome, ${player.name}!\nhttps://docs.zep.us/ Click the link to check the guide.`,0xffffff);
});
player.showPrompt(text: string, function(inputText))
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".
// 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");
}
});
});
player.showConfirm(text: string, function(result))
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.
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
player.showConfirm("confirm", (result) => {
App.sayToAll(result);
});
});
player.showAlert(text: string, function())
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.
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
player.showAlert("alert", () => {
App.sayToAll(player.name + " show alert.");
});
});
player.showWidgetResponsive(fileName:string, marginTop:number, marginRight:number, marginBottom:number, marginLeft:number)
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.
showWidgetResponsive.zip
16KB
Binary
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;
}
});
});
player.openWebLink(url:string, popup:boolean=false)
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.
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
player.openWebLink("https://docs-kr.zep.us", true);
});
Web Page in a New Window
player.showEmbed(url: string, align: string, width: number, height: number, hasBackdrop: boolean = true)
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
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
player.showEmbed("https://youtu.be/ztuTrpXJyks", "middle", 900, 600, true);
});
Data Load Methods at a Glance
// 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
player.isEmail(email: string): boolean
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.
// 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("[email protected]");
App.sayToAll(`check if the email matches: ${check}`)
})
player.getLocationName : string
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.
// 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 at a Glance
// 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)
player.spawnAt(tileX: int ,tileY: int, dir: int = 0)
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.
// 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
});
player.spawnAtLocation(name: string, dir:int = 0)
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.
When there is more than one specific area with the same name, the player will be moved to one of those locations randomly.
// 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);
});
player.spawnAtMap(spaceHashID string, mapHashID:string = null)
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
// 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 at a Glance
// 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)
player.playSound(fileName: string, loop: boolean = false, overlap: boolean = false)
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).
join.mp3
20KB
Binary
// Activates function when a player enters
App.onJoinPlayer.Add(function (player) {
player.playSound("join.mp3",false);
});
player.playSoundLink(link: string, loop: boolean = false)
This function plays a sound for all players.
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.
Parameters