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

NameDescription

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

NameDescription

isEmail

Function to compare the player’s email

getLocationName

Displays the name of the specific location of where the player is standing

User Control

NameDescription

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

NameDescription

playSound

Function to play a sound file to a player

playSoundLink

Function to play the sound URL to a player

Common

NameDescription

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

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

NameTypeDescription

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

showCustomLabel

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

NameTypeDescription

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

showWidget

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

NameTypeDescription

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.

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

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.

Please refer to the Settlement Guide for more detailed information on ZEP settlement.

Parameters

NameTypeDescription

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

hideBuyAlert

player.hideBuyAlert()

This function closes a player's purchase widget.

Parameter

None

sendMessage

player.sendMessage(text: string, color: uint = 0xFFFFFF)

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

Parameters

NameTypeDescription

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

showPrompt

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

NameTypeDescription

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

showConfirm

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

NameTypeDescription

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

showAlert

player.showAlert(text: string, function())

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

Parameter

NameTypeDescription

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

showWidgetResponsive

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

NameTypeDescription

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.

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

player.openWebLink(url:string, popup:boolean=false)

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

Parameters

NameTypeDescription

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

showEmbed

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

NameTyoeDescription

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

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

isEmail

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

NameTypeDescription

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("supercat@supercat.co.kr");
	App.sayToAll(`check if the email matches: ${check}`)
})

getLocationName

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

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)

spawnAt

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

NameTypeDescription

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

spawnAtLocation

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

NameTypeDescription

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

spawnAtMap

player.spawnAtMap(spaceHashID string, mapHashID:string = null)

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

Parameters

NameTypeDescription

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)

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

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

player.playSound(fileName: string, loop: boolean = false, overlap: boolean = false)

This function plays sound to the corresponding player.

Parameters

NameTypeDescription

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

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

playSoundLink

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

NameTypeDescription

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

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

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

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

sendUpdated

player.sendUpdated()

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

Parameter

  • None

save

player.save()

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

Parameter

  • None

PreviousFieldNextScriptWidget

Last updated