# Hello ZEP Script
> **What is ZEP Script?**
>
> ZEP Script is a powerful scripting language designed to operate on ZEP.
>
> It offers a wide range of foundational systems such as avatar and object manipulation, payment integration, chat functionality, and real-time capabilities. Even if you're new to coding, ZEP Script makes it easy to get started.
>
> With ZEP Script, you can unleash your creativity and build a variety of applications, including games, calendars, visitor lists, utility apps, and much more. The possibilities are endless!
>
> Start exploring the world of ZEP Script and create your very own metaverse app.
## ZEP Script Use Cases
ZEP Script is easy to use, and anyone can use it!
Unique Maps Created with ZEP Script
### 🕹️Games
You can develop a wide range of enjoyable games with the help of ZEP Script.
#### Rabbit Mountain
🐰 [Visit Now](https://zep.us/play/8jqEO4) (only available in Korean)
In this Rabbit Mountain map, players control their avatars to ascend the mountain while avoiding rolling snowball obstacles.
These descending snowballs were created using the gameplay elements from the mini-game "Avoid Poop."
#### Bonbon School Detectives (Escape Room)
🕵️ [Visit Now](https://zep.us/play/D9JMjl)
Step into the shoes of a detective in this immersive escape room game. Players must uncover clues, solve puzzles, and complete tasks within a limited time frame to escape from the game setting.
Experience the excitement of this captivating game with the applied vignette effect.
#### Boxing Arena
🥊 [Visit Now](https://zep.us/play/yOw9Av)
Experience the intense Boxing Arena, inspired by the mini-game "Boxing Match."
Press Z to throw punches at another player. Safeguard your HP blocks and strive to be the last survivor.
The last survivor earns the title of the Boxing King.
### 🎉 Events
With ZEP Script, you can plan and host interactive events that engage participants.
#### Klaytn Museum
✈️ [Visit Now](https://zep.us/play/DwPndd) (only available in Korean)
Immerse yourself in the Klaytn Museum, a Space that showcases the technical prowess of Klaytn through the utilization of ZEP Script.
#### UNICEF Sponsors Event Space
The mission and work of UNICEF are brought to life through the implementation of ZEP Script. Users can explore interactive maps and engage in natural learning experiences.
#### Jet Land Event Space
✈️ [Visit Now](https://zep.us/play/D63k6z) (only available in Korean)
This Space is themed around the Samsung vacuum cleaner brand "Jet". With its theme park-inspired design, users can immerse themselves in a variety of games and entertainment options brought to life through the power of ZEP Script.
You can provide users with an exciting and enjoyable experience, showcasing the fun elements created using ZEP Script.
# ZEP Script Guide
Anyone can create an app that runs in ZEP!
ZEP Script boasts a number of functions beyond what is included in the Map Editor. ZEP Script allows users to change avatar or object sprite sheets, customize the UI, turn invisible, etc.
You can create your very own metaverse app using ZEP Script. Create unique games, calendars, visitors’ lists, utility apps, and so much more!
## Index
### [ZEP Script Development Guide](/zep-script/zep-script-guide/zep-script-development-guide)
* Javascript Development Tips
* TypeScript Development Tips
* ZEP Script Deployment Guide
### [API Documentation](/zep-script/zep-script-api)
* ScriptAPP
* ScriptMap
* ScriptPlayer
* ScriptWidget
### [Explore ZEP Script](/zep-script/zep-script-guide/explore-zep-script)
* [Tutorials](/zep-script/zep-script-guide/explore-zep-script/tutorials)
* Displaying a Message
* Changing Avatar Image
* Using HTML
* Communicating with an External API
* Creating a 2-second Stun Effect
* [ZEP Script Example Code](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code)
* Timer
* Zombie Game
* Paintman Game
* Hangul Quiz Game
* Avoid Poop Game
* Boxing Game
* Sidebar App
* Race
### [ZEP Script FAQ](/zep-script/zep-script-guide/zep-script-faq)
### [Appendix](/zep-script/zep-script-guide/appendix)
## Tutorials (Available in Korean)
{% embed url="" %}
Step-by-step :fire: [**metaverse development guidance**](https://zepxsparta.oopy.io/) on ZEP!
# ZEP Script Development Guide
Updated 2022.08.01
## Getting Started
### Introduction
Anyone can create apps that run on the metaverse platform ZEP.
ZEP Script supports various functions, such as character/object manipulation and custom UI.
From creative games to productivity apps like calendars and guestbooks, anyone can create their own metaverse apps!
:fire: **ZEP Script Use Cases**
### Development Environment
* JavaScript (ES6)
:bulb: **JavaScript Development Tips**
* Typescript
:computer: **TypeScript Development Guide**
* Canvas
* Web browser (Desktop/Mobile)
### Categories
{% hint style="info" %}
Apps developed using ZEP Script can be applied to a map by selecting one of the three types below. To connect the app and the map, please refer to the [**Deployment Guide**](/zep-script/zep-script-guide/zep-script-development-guide/zep-script-deployment-guide).
{% endhint %}
**1) Mini-Game**
Mini-Games are installable apps that can be installed and used on any map. In Spaces where you have permission to embed, you can embed these apps by clicking the **Mini-Game** button in the sidebar on the left side of the screen. The app runs the moment that it is embedded. The user that embedded the app can terminate it by **jumping on it using the space bar**.
**2) Normal App**
Normal Apps are apps that can only work on certain maps. After developing and uploading a Normal App, users with **Admin** **or higher permissions** can apply it. To apply apps, go to the sidebar > **Settings** > **Map Settings** > **Add Normal App**. Scripts can be applied without any additional app installation steps, although only to maps that you have permission to edit.
**3) Sidebar App**
Sidebar apps are apps that are displayed as an icon on the left sidebar of the PC. After developing and uploading a Sidebar App, you can add it from the sidebar > **App** > **App Management** list from the play screen of a map in which you have owner permission. In a Space where a sidebar app is installed, the sidebar app is displayed to everyone who enters the Space.
# JavaScript Development Tips
By using the **zep-script-SDK** library, you can keep your folder structure neat and make the project compression process simpler than before. Let’s take a look at how to use the **zep-script-SDK**.
### 1. Install **node.js**
{% hint style="info" %}
Visit to download and install node.js.
We recommend installing the LTS version, which is the most stable version.
{% endhint %}
### 2. Organize Project Folders
To use the library, the project folder should be organized as follows:
The **res** folder is where you put the images, sounds, and html files to be used in the app.
→ The folder name must be **res**.
### 3. Create a Project as a Zip File Using the CLI
Now when you deploy your app, you can use the CLI to create a project as a zip file with a command.
The CLI can be run from the terminal for MacOS, Windows PowerShell in windows, or the terminal environment provided since Windows 11.
> **Running PowerShell on Windows**
>
> **Shift + right-click** in the empty space of the folder in which main.js is located.
>
> Choose **`Open PowerShell window here`** or **`Open command window here`**.
>
> 
>
> A **Windows PowerShell** or **Command Prompt** window will launch as follows:
>
> 
Open a command window in the folder where the **main.js** file is located and enter the following command to create a compressed file.
```powershell
npx zep-script archive
```
If the compression process was successful, you can check that a compressed file has been created in the folder as follows:
Finally, after creating the zip file, you’re ready to deploy your app.
### 4. Deploy a Project
**1.** **Deploy on a website**
You can deploy your app by uploading the zip file created above.
Refer to the [ZEP Script Deployment Guide](/zep-script/zep-script-guide/zep-script-development-guide/zep-script-deployment-guide) and distribute your app!
**2. Deploy using CLI**
You can deploy the zip file created by using CLI.
Create a `zep-script.json` file as below and set the app to upload. (Make sure not to change the file name.)
```json
{
"appId": "Zjkgoj", // app ID
"name": "Template", // app name
"description": "Template application" , // app description
"type": "normal" // app type ( "normal" or "minigame" or "sidebar" )
}
```
⭐ appID: Enter the ID of the app to upload.
* To change an existing app, access , select an app to upload, and then enter the text appended to apps/ in the address bar. (E.g., "Zjkgoj" for the reference image below)
Open a command window in the folder where the **main.js** file is located and enter the following command to create a compressed file.
```powershell
npx zep-script publish
```
Account verification is required during the app upload process.
When the email input section appears below, enter the email address of the account that owns the app to be deployed.
When you see the message saying, **Sending login code to your email**, go to the mailbox of the email you entered above. Check the verification code and enter it to the command window to start deploying.
The deploy process is complete when a green checkmark appears on the left of **Publishing…** as shown below.
You can see your app has been deployed in the [**My Apps**](https://zep.us/me/apps) page as described above in the **zep-script.json** file.
For more information about the library, please refer to the contents of the GitHub repository below.\
[ zep-script-sdk/packages/zep-script-cli at main · zep-us/zep-script-sdk](https://github.com/zep-us/zep-script-sdk/tree/main/packages/zep-script-cli)
# ZEP Script Deployment Guide
This document explains how to deploy an app created with ZEP Script.
## STEP 1
Select all of the files to be used, including the **main.js** file developed with ZEP Script, image files, and widget files, and compress them.
{% hint style="danger" %}
Note:
* The app’s file name and type must be set as “**main.js**”.
* **Select the individual files together** to compress. Do not compress a folder.
* The supported filename extension is \***.zip**.
{% endhint %}
{% file src="/files/xIP0lpNQrmPxD4Y2wHCU" %}
## STEP 2
Create an account on ZEP and sign in, on the [**My Spaces**](https://zep.us/spaces/me) page click **Your Profile Name** > [**My apps (Beta)**](https://zep.us/me/apps).
## STEP 3
3\) Click **Upload app** on the [**My apps (Beta)**](https://zep.us/me/apps) page.
## STEP 4
Click the **Upload** button after filling out the **App name**, **Description**, selecting the app **Type**, and uploading the **Icon**, and compressed **ZEP script file**.
This is how the app name and icon appear. (Mini-Game)
## STEP 5
You can install apps to your desired maps according to their App Type.
* **Normal App:**
Enter **Map Editor** on a map for which you have an Editor role or higher and in the **Map manager** in the bottom left corner click ⚙️ > **Edit** to bring up the **Map Setting** pop-up and select your App from the Application drop-down menu.
* **Mini-Game:**
Enter the play screen > Select the **Mini-Game** button on the side bar.
## 🚧 Debugging and Error Messages
When the app is executed, error messages will be displayed in red text in the chat message box for all who have permission settings of Staff or higher.
# TypeScript Development Tips
### ⭐ Things to Note When Developing in TypeScript
When developing with TypeScript, you must put the **Script** keyword in front of the **App, Map, Player,** or **Widget** keywords.
```jsx
// When developing in JavaScript
App.sayToAll("Hello World!");
// When developing in TypeScript
ScriptApp.sayToAll("Hello World!");
```
### 1. Install **node.js**
{% hint style="info" %}
Visit to download and install node.js.
We recommend installing the LTS version, which is the most stable version.
{% endhint %}
### 2. Create the Project Folder
A sample project for developing in ZEP Script can be downloaded through the CLI.
The CLI can be run from the terminal for MacOS, Windows PowerShell in windows, or the terminal environment provided since Windows 11.
> **Running PowerShell on Windows**
>
> **Shift + right-click** in the empty space of the folder in which main.js is located.
>
> Choose **`Open PowerShell window here`** or **`Open command window here`**.
>
> 
>
> A **Windows PowerShell** or **Command Prompt** window will launch as follows:
>
> 
Enter the command to create the project folder as follows:
```bash
npx zep-script init MyZepApp --npm
```
If the message `Project {Folder Name} initialized successfully` is displayed as seen above, the environment for developing **ZEP Script** with TypeScript is now ready.
### 3. Browse the Folder Structure
If you go to the created project folder, you can see the files as follows:
The **res** folder is an abbreviation of "**resources"** and is where you put images or html files needed for the app.
The **main.ts** file created here is where you write the app development code.
This **main.ts** file contains sample code as seen below. You can refer to this code for development.
With the exception of the **main.ts file and res folder,** the remaining files and folders are configuration files for developing ZEP Script with TypeScript, and you do not need to modify them separately during development.
### 4. Create a JavaScript Build
Since **ZEP Script** can only be executed through JavaScript, it must go through a build process that converts TypeScript to JavaScript.
Open a command window in the folder where the **main.js** file is located and enter the following command to create a new build.
```bash
npx zep-script build
```
If the build is created successfully, you can see that a folder named **dist** has been created.
The **dist** folder contains the **main.js** file that was created by converting the TypeScript code written in the **main.ts** into JavaScript.
### 5. Create a Compressed File
To distribute an app created with ZEP Script, you need to create a zip file that contains the main.js file and the images and html files to be used in the app.
Open a command window in the root of your project’s folder and enter the following command to create a compressed file.
```powershell
npx zep-script archive
```
If the compression process was successful, you can check that a compressed file has been created in the folder as follows:
Finally, after creating the zip file, you’re ready to deploy the app.
### 6. Deploy a Project
1. **Deploy on a website**
You can deploy your app by uploading the zip file created above.
Refer to the [ZEP Script Deployment Guide](/zep-script/zep-script-guide/zep-script-development-guide/zep-script-deployment-guide) and distribute your app!
**2. Deploy using CLI**
You can deploy the zip file created by using CLI.
Open the zep-script.json file in the project folder and run the app to upload.
(Make sure to create the zep-script.json file.)
```json
{
"appId": "Zjkgoj", // app ID
"name": "Template", // app name
"description": "Template application" , // app description
"type": "normal" // app type( "normal" or "minigame" or "sidebar" )
}
```
⭐ appID: Enter the ID of the app to upload.
* To change an existing app, access , select an app to upload, and then enter the text appended to apps/ in the address bar. (E.g., "Zjkgoj" for the reference image below)
Once set, run PowerShell in the project folder path and enter a command for deployment as below.
```powershell
npm run deploy or npx zep-script publish
```
When the email input section appears below, enter the email address of the account that owns the app to be deployed.
When you see the message saying, **Sending login code to your email**, go to the mailbox of the email you entered above. Check the verification code and enter it to the command window to start deploying.
The deploy process is complete when a green checkmark appears on the left of **Publishing…** as shown below.
You can see your app has been deployed in the [My Apps](https://zep.us/me/apps) page as described above in the **zep-script.json** file.
For more information about the library, please refer to the contents of the GitHub repository below.\
[zep-script-sdk/packages/zep-script-cli at main · zep-us/zep-script-sdk](https://github.com/zep-us/zep-script-sdk/tree/main/packages/zep-script-cli)
# Explore ZEP Script
### Tutorial
Follow the tutorial to gradually familiarize yourself with ZEP Script!
* [Displaying a Message](/zep-script/zep-script-guide/explore-zep-script/tutorials/displaying-a-message)
* [Understanding the ZEP App Lifecycle](/zep-script/zep-script-api/scriptapp/lifecycle)
* [Changing Avatar Image](/zep-script/zep-script-guide/explore-zep-script/tutorials/changing-avatar-image)
* [Using HTML](/zep-script/zep-script-guide/explore-zep-script/tutorials/using-html)
* [Communicating with an External API](/zep-script/zep-script-api)
* [Create a 2-second Stun Effect](/zep-script/zep-script-guide/explore-zep-script/tutorials/creating-a-2-second-stun-effect)
### ZEP Script Example Code
* [Timer](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/timer)
* [Zombie Game](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/zombie-game)
* [Paintman Game](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/paintman-game)
* [Hangul Quiz Game](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/hangul-quiz-game)
* [Avoid Poop Game](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/avoid-poop-game)
* [Boxing Game](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/boxing-game)
* [Sidebar App](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/sidebar-app)
* [Race](/zep-script/zep-script-guide/explore-zep-script/zep-script-example-code/race)
# Tutorials
### Tutorial
Follow the tutorial to gradually familiarize yourself with ZEP Script!
* [Displaying a Message](/zep-script/zep-script-guide/explore-zep-script/tutorials/displaying-a-message)
* [Understanding the ZEP App Lifecycle](/zep-script/zep-script-api/scriptapp/lifecycle)
* [Changing Avatar Image](/zep-script/zep-script-guide/explore-zep-script/tutorials/changing-avatar-image)
* [Using HTML](/zep-script/zep-script-guide/explore-zep-script/tutorials/using-html)
* [Communicating with an External API](/zep-script/zep-script-guide/explore-zep-script/tutorials/communicating-with-an-external-api)
* [Create a 2-second Stun Effect](/zep-script/zep-script-guide/explore-zep-script/tutorials/creating-a-2-second-stun-effect)
# Displaying a Message
Displaying a Message - Hello world
1. Let’s try displaying a message in the center of the app. The default center label is set to a black background with white text.
```jsx
// main.js
App.showCenterLabel("Hello world");
```
2\. Result
{% hint style="warning" %}
Please Note
* For the tutorial, we recommend setting the app type to Mini-Game.
* The JSON file name must be “main”. Please create a new text file and name it main.js.
* If you do not know how to deploy an app, please refer to the [**ZEP Script Deployment Guide**](/zep-script/zep-script-guide/zep-script-development-guide/zep-script-deployment-guide).
{% endhint %}
# Changing Avatar Image
1. Prepare a sample sprite sheet with the animation. If you do not have one, please download the image below.
{% hint style="danger" %}
If you are using a sprite sheet you did not create, please be cautious of copyright law.
{% endhint %}
2\. As seen in the image above, single frames of the same size are aligned in each frame into a sprite sheet image. The file extension must be a PNG file.
* TIP : For avatars, we recommend the following frame size of 48(px) x 64(px) for each action frame.
{% hint style="success" %}
A **sprite sheet** is a bitmap image file that has several small graphic frames aligned. It is used when developing a game to create a 2D animation by compiling frames of a continuous pose of a character or avatar into one image file.
{% endhint %}
3\. Load a sprite sheet by using the following `App.loadSpritesheet` API.
{% code overflow="wrap" %}
```jsx
App.loadSpritesheet(fileName: string, frameWidth: integer, frameHeight: integer, anims: array, frameRate: integer): ScriptDynamicResource
```
{% endcode %}
* First Argument(fileName): Adds the file extension in the name of the sprite sheet
* Second Argument(frameWidth): Width of one action frame size (px)
* Third Argument(frameHeight): Height of one action frame size (px)
* Fourth Argument(anims): Animation name determined in ZEP (left, right, up, down) and numbers of each image index
{% hint style="success" %}
Image index number order starts from 0 with the top-left image.
{% endhint %}
* Fifth Argument(frameRate): Determine how many frames will repeat within 1 second.
4\. `player.sendUpdated()` needs to be written to apply the player’s attribute change
5\. Example Code
{% code overflow="wrap" %}
```jsx
// Creates a variable named blueman in JavaScript grammar
let blueman = null;
// Reads and saves the variable's sprite sheet
blueman = App.loadSpritesheet('blueman.png', 48, 64, {
left: [5, 6, 7, 8, 9], // left is an animation name that is already walking in the predetermined left direction
up: [15, 16, 17, 18, 19], // Index numbers in the file to be used for each name
down: [0, 1, 2, 3, 4],
right: [10, 11, 12, 13, 14],
}, 8); // 8 frames per second.
// Switches the player's avatar to the blueman image when player enters
App.onJoinPlayer.Add(function(player){
player.sprite = blueman;
// Applies the player attribute changes when executed
player.sendUpdated();
})
```
{% endcode %}
6\. Usage
```jsx
// Saves at the same time the variable is called
let blueman = App.loadSpritesheet('blueman.png', 48, 64, {
left: [5, 6, 7, 8, 9],
up: [15, 16, 17, 18, 19],
down: [0, 1, 2, 3, 4],
right: [10, 11, 12, 13, 14],
}, 8);
```
{% hint style="success" %}
Imagine avatar changes not only applied upon entry but under other special conditions too. Think about them and then try creating them!
{% endhint %}
{% hint style="warning" %}
Please Note
* For the tutorial, we recommend setting the app type to Mini-Game.
* The JSON file name must be “main”. Please create a new text file and name it main.js.
* If you do not know how to deploy an app, please refer to the [**ZEP Script Deployment Guide**](/zep-script/zep-script-guide/zep-script-development-guide/zep-script-deployment-guide).
{% endhint %}
# Using HTML
1. You can draw any shape of UI on the ZEP canvas. In ZEP, UI elements are expressed through HTML.
2. You can bring an HTML file to a certain location using the `App.showWidget()`function. In this case, the file name, alignment, as well as width and height of the widget can be configured using arguments. Please refer to the [ScriptApp’s Methods](/zep-script/zep-script-api/scriptapp/methods) page for more information on values for alignment.
3. You can send the desired value to the HTML file using the `sendMessage()` method to the created variable.
4. Write the HTML syntax as shown below (my.html) and then use `addEventListener` to receive the message sent from main.js.
* main.js
```jsx
//Set in advance the UI location values as variables
let position = 'middle';
let width = 400;
let height = 400;
// Create a tag called "state" using "my.html" and pass the value "hello"
let _widget = App.showWidget('my.html', position, width, height);
_widget.sendMessage({
state: "hello",
});
```
* my.html
{% code overflow="wrap" %}
```html
-
```
{% endcode %}
{% hint style="warning" %}
Please Note
\- For the tutorial, we recommend setting the app type to Installable App.
\- The JSON file name must be “main.” Please create a new text file and name it “main.js.”
\- If you do not know how to deploy an app, please refer to the [**ZEP Script Deployment Guide**](/zep-script/zep-script-guide/zep-script-development-guide/zep-script-deployment-guide).
{% endhint %}
# Communicating with an External API
You can send GET, POST, etc. requests with arguments to an external API.
### httpGet
Changes the nicknames of the users who have just entered with the [Korean Nickname Generator](https://nickname.hwanmoo.kr/) API.
{% code overflow="wrap" %}
```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();
}
);
});
```
{% endcode %}
### httpPost
Receives the header and data sent from the app in response and displays it in the chat window.
{% code overflow="wrap" %}
```jsx
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
App.httpPost(
"https://postman-echo.com/post",
{
"test-header": "zep",
},
{
name: "zepscript",
},
(res) => {
let response = JSON.parse(res);
App.sayToAll(`header sent: ${response.headers["test-header"]}`, 0xffffff);
App.sayToAll(`data sent: ${response.form.name}`, 0xffffff);
}
);
});
```
{% endcode %}
{% hint style="warning" %}
Please Note
\- For the tutorial, we recommend setting the app type to Mini-Game.
\- The JSON file name must be “main.” Please create a new text file and name it “main.js.”
\- If you do not know how to deploy an app, please refer to the [**ZEP Script Deployment Guide**](/zep-script/zep-script-guide/zep-script-development-guide/zep-script-deployment-guide).
{% endhint %}
***
# Creating a 2-Second Stun Effect
### Creating a 2-Second Stun Effect
```jsx
let _players = App.players;
// Event when player enters
App.onJoinPlayer.Add(function(p) {
p.tag = {
stun : false, // Whether stunned, false
sTime : 2, //Set stun effect to 2 seconds
};
_players = App.players;
});
// When the player attacks another player (Z key)
App.onUnitAttacked.Add(function(sender, x, y, target) {
if(!target.tag.stun)
{
target.tag.stun = true; // Change whether stunned to true
target.moveSpeed = 0; // Change movement speed to 0
target.sendUpdated();
}
});
App.onUpdate.Add(function(dt){
for(let i in _players) {
let p = _players[i];
// If whether stunned is true
if(p.tag.stun)
{
p.tag.sTime -= dt; //Subtract dt for each update until the stun effect duration becomes 0.
if(p.tag.sTime <= 0) // When the stun effect duration becomes under 0,
{
p.tag.stun = false; // Change whether stunned to false
p.tag.sTime = 2; // Reset duration to 2 seconds
p.moveSpeed = 80; // Normalize movement speed
p.sendUpdated();
}
}
}
});
// Event when player exits
App.onLeavePlayer.Add(function(p) {
p.moveSpeed = 80; // Normalize movement speed
p.sendUpdated();
_players = App.players;
});
```
{% hint style="warning" %}
Please Note
\- For the tutorial, we recommend setting the app type to Mini-Game.
\- The JSON file name must be “main.” Please create a new text file and name it “main.js.”
\- If you do not know how to deploy an app, please refer to the [**ZEP Script Deployment Guide**](/zep-script/zep-script-guide/zep-script-development-guide/zep-script-deployment-guide).
{% endhint %}
***
***
# ZEP Script Example Code
## Timer
You can create a timer that works in ZEP. You can modify it to fit your personal development style and use it in ZEP.
## Zombie Game
This is a working Zombie Game script that can be run from the \[Side Bar] > \[Mini-Game] menu. You can modify it to fit your personal development style and use it.
## Paintman Game
This is a working Paintman Game script that can be run from the \[Side Bar] > \[Mini-Game] menu. You can modify it to fit your personal development style and use it.
## Hangul Quiz Game
This is a working Hangul Quiz Game script that can be run from the \[Side Bar] > \[Mini-Game] menu. You can modify it to fit your personal development style and use it.
## Avoid Poop Game
This is a working Avoid Poop Game script that can be run from the \[Side Bar] > \[Mini-Game] menu. You can modify it to fit your personal development style and use it.
## Boxing Game
This is a working Duel Game script that can be run from the \[Side Bar] > \[Mini-Game] menu. You can modify it to fit your personal development style and use it.
## Sidebar App
A sidebar app is an app that is displayed as an icon on the PC’s left side of the screen.
Using the examples provided below, you can create your sidebar app to match your personal developer needs.
### Race
This is a working Race Game script that can be run from the \[Side Bar] > \[Mini-Game] menu. You can modify it to fit your personal development style and use it.
# Timer
**Example (Timer) -**
```jsx
let _timer = 90;
let _stateTimer = 0;
App.onUpdate.Add(function(dt){
_stateTimer += dt;
if(_stateTimer >= 1){
_stateTimer = 0;
_timer -= 1;
}
if(_timer <= 0){
// time over then...
}
})
```
# Zombie Game
**1) File**
{% file src="/files/xjv0rlORoylqsNm97lTh" %}
**2) main.js**
{% code overflow="wrap" %}
```jsx
// load sprite
let monster = App.loadSpritesheet('monster.png', 96, 96, {
// defined base anim
left: [8, 9, 10, 11],
up: [12, 13, 14, 15],
down: [4, 5, 6, 7],
right: [16, 17, 18, 19],
}, 8);
const STATE_INIT = 3000;
const STATE_READY = 3001;
const STATE_PLAYING = 3002;
const STATE_JUDGE = 3004;
const STATE_END = 3005;
let _start = false; // Whether the game starts
let _players = App.players; // App.players : get total players
let _lastSurvivor = null;
let _zombieKing = [];
let _state = STATE_INIT;
let _stateTimer = 0; // Timer to check status value
let _live = 0; // number of survivors
let _resultstr;
function startApp()
{
if(_players.length > 2)
{
// Set the number of zombies
let zombiCnt = Math.floor(_players.length * 0.1);
if(zombiCnt < 1)
zombiCnt = 1;
let allPlayer = [];
let zombieIdx = [];
for(let i = 0; i < _players.length; ++i)
{
allPlayer.push(_players[i]);
}
for(let i = 0; i < zombiCnt; ++i)
{
let index = Math.floor(allPlayer.length * Math.random());
if(!zombieIdx.includes(allPlayer[index].id))
{
zombieIdx.push(allPlayer[index].id);
allPlayer.splice(index, 1);
}
}
// give players zombie attribute
for(let i in _players)
{
let p = _players[i];
// create and utilize option data using tags.
p.tag = {};
if(zombieIdx.includes(p.id))
{
p.tag.zombie = true;
p.tag.attack = 0;
}
else
{
p.tag.zombie = false;
p.tag.attack = 0;
_live++;
}
// Must use this method to call and update player properties
p.sendUpdated();
}
_start = true;
}
else
{
App.showCenterLabel(`Playable number of people: 3 or more`);
startState(STATE_END);
}
}
function startState(state)
{
_state = state;
_stateTimer = 0;
switch(_state)
{
case STATE_INIT:
startApp();
break;
case STATE_READY:
App.showCenterLabel("The game will start soon.");
for(let i in _players)
{
let p = _players[i];
p.moveSpeed = 0;
// Change the attribute of zombies
if(p.tag.zombie)
{
p.title = '';
p.sprite = monster;
}
p.sendUpdated();
}
break;
case STATE_PLAYING:
for(let i in _players)
{
let p = _players[i];
// Change speed and label text according to player status
if(p.tag.zombie)
{
p.moveSpeed = 85;
p.showCenterLabel('Infect people!');
}
else
{
p.moveSpeed = 80;
p.showCenterLabel('Survive from zombies!');
}
p.sendUpdated();
}
break;
case STATE_JUDGE:
for(let i in _players) {
let p = _players[i];
p.moveSpeed = 0;
p.sendUpdated();
}
judgement(_live);
break;
case STATE_END:
_start = false;
for(let i in _players)
{
let p = _players[i];
p.moveSpeed = 80;
p.title = null;
p.sprite = null;
p.sendUpdated();
}
// Clear all objects in the map
Map.clearAllObjects();
break;
}
}
function checkSuvivors()
{
let resultlive = 0;
for(let i in _players)
{
let p = _players[i];
if(!p.tag.zombie)
{
_lastSurvivor = p;
++resultlive;
}
}
return resultlive;
}
function judgement(number)
{
// The highest number of attacks among all players
let attack = 0;
for(let i in _players)
{
let p = _players[i];
if(p.tag.attack > attack)
attack = p.tag.attack;
}
zombieKing = [];
for(let i in _players)
{
let p = _players[i];
if(p.tag.attack == attack)
zombieKing.push(p);
}
let index = Math.floor(Math.random() * zombieKing.length);
if(number == 1) // when there are survivors
resultstr = `${_lastSurvivor.name} is the last survivor!\nThe Strongest Zombie [` + zombieKing[index].name + '] Number of infections : ' + attack;
else if(number == 0) // when there are no survivors
resultstr = `No survivors.\nThe Strongest Zombie [` + zombieKing[index].name + '] Number of infections : ' + attack;
}
App.onStart.Add(function(){
startState(STATE_INIT);
});
// event triggered when players join the Space
App.onJoinPlayer.Add(function(p) {
p.tag = {
zombie : false,
attack : 0,
};
if(_start) {
p.tag.zombie = true;
p.sprite = monster;
p.sendUpdated();
judgement(checkSuvivors());
}
_players = App.players;
});
// event triggered when players leave the Space
App.onLeavePlayer.Add(function(p) {
if(_start) {
judgement(checkSuvivors());
}
p.title = null;
p.sprite = null;
p.moveSpeed = 80;
p.sendUpdated();
_players = App.players;
});
// event triggered when the game block is pressed
App.onDestroy.Add(function() {
App.stopSound();
});
// event triggered when player touches other players
App.onPlayerTouched.Add(function(sender, target, x, y) {
if(_state != STATE_PLAYING)
return;
if(!sender.tag.zombie)
return;
if(target.tag.zombie)
return;
target.tag.zombie = true;
target.sprite = monster;
sender.tag.attack += 1;
target.sendUpdated();
_live = checkSuvivors();
if(_live >= 2)
{
App.showCenterLabel(`${target.name} is infected!\n(${_live} survivors!)`);
return;
}
else
startState(STATE_JUDGE);
});
// called every 20ms
// param1 : deltatime ( elapsedTime )
App.onUpdate.Add(function(dt) {
if(!_start)
return;
_stateTimer += dt;
switch(_state)
{
case STATE_INIT:
App.showCenterLabel("Become a zombie and infect people. The host is faster.\nPeople do their best to run away and be the last survivor.");
if(_stateTimer >= 5)
startState(STATE_READY);
break;
case STATE_READY:
if(_stateTimer >= 3)
startState(STATE_PLAYING);
break;
case STATE_PLAYING:
break;
case STATE_JUDGE:
App.showCenterLabel(resultstr);
if(_stateTimer >= 5)
startState(STATE_END);
break;
case STATE_END:
break;
}
});
```
{% endcode %}
# Paintman Game
**1) File**
{% file src="/files/BmuLdFk5OK4uGJUEFAtg" %}
**2) main.js**
{% code overflow="wrap" %}
```jsx
// load sprite
let redman = App.loadSpritesheet('redman.png', 48, 64, {
left: [5, 6, 7, 8, 9], // defined base anim
up: [15, 16, 17, 18, 19], // defined base anim
down: [0, 1, 2, 3, 4], // defined base anim
right: [10, 11, 12, 13, 14], // defined base anim
}, 8);
// load sprite
let blueman = App.loadSpritesheet('blueman.png', 48, 64, {
left: [5, 6, 7, 8, 9],
up: [15, 16, 17, 18, 19],
down: [0, 1, 2, 3, 4],
right: [10, 11, 12, 13, 14],
}, 8);
const STATE_INIT = 3000;
const STATE_READY = 3001;
const STATE_PLAYING = 3002;
const STATE_JUDGE = 3004;
const STATE_END = 3005;
// load sprite
let red = App.loadSpritesheet('red.png');
let blue = App.loadSpritesheet('blue.png');
let tomb = App.loadSpritesheet('tomb.png');
let _start = false;
let _gameEnd = false;
let _state = STATE_INIT;
let _stateTimer = 0;
let _timer = 90;
let _objects = {};
let _redScore = 0;
let _blueScore = 0;
// for using hash key
let HEIGHT_KEY = 10000000;
let _blueTeam = [];
let _redTeam = [];
let _players = App.players; // App.players : get total players
let TEAM_COUNTER = 0;
let _resultStr = '';
function startState(state)
{
_state = state;
_stateTimer = 0;
switch(_state)
{
case STATE_INIT:
_start = true;
_stateTimer = 0;
_timer = 90;
_redScore = 0;
_blueScore = 0;
_objects = {};
for(let i in _players) {
let p = _players[i];
// create and utilize option data using tags.
p.tag = {
x: p.tileX,
y: p.tileY,
sturn : false,
sTime : 1,
super : false,
team: Math.floor(TEAM_COUNTER % 2),
};
TEAM_COUNTER++;
if(p.tag.team == 0)
_redTeam.push(p);
else if(p.tag.team == 1)
_blueTeam.push(p);
p.sprite = p.tag.team == 0 ? redman : blueman;
p.sendUpdated();
}
break;
case STATE_READY:
for(let i in _players) {
let p = _players[i];
p.moveSpeed = 0;
p.sendUpdated();
}
break;
case STATE_PLAYING:
for(let i in _players) {
let p = _players[i];
p.moveSpeed = 80;
p.sendUpdated();
}
break;
case STATE_JUDGE:
for(let i in _players) {
let p = _players[i];
p.moveSpeed = 0;
p.sendUpdated();
}
break;
case STATE_END:
_start = false;
for(let i in _players) {
let p = _players[i];
p.moveSpeed = 80;
p.title = null;
p.sprite = null;
p.sendUpdated();
}
// remove all objects created by the zep-scripts
Map.clearAllObjects();
break;
}
}
App.onStart.Add(function(){
startState(STATE_INIT);
});
// when player join the space event
App.onJoinPlayer.Add(function(p) {
p.tag = {
x: p.tileX,
y: p.tileY,
sturn : false,
sTime : 1,
super : false,
team: Math.floor(TEAM_COUNTER % 2),
};
if(p.tag.team == 0)
_redTeam.push(p);
else if(p.tag.team == 1)
_blueTeam.push(p);
TEAM_COUNTER++;
p.nameColor = p.tag.team == 0 ? 16711680 : 255;
p.sprite = p.tag.team == 0 ? redman : blueman;
p.sendUpdated();
_players = App.players;
});
// when player leave the space event
App.onLeavePlayer.Add(function(p) {
p.moveSpeed = 80;
p.title = null;
p.sprite = null;
p.sendUpdated();
_players = App.players; // update all plyers for update(dt)
});
// when player touched objects event
App.onDestroy.Add(function() {
Map.clearAllObjects();
})
// when player attacked other player event (z key)
App.onUnitAttacked.Add(function(sender, x, y, target) {
if(_state != STATE_PLAYING)
return;
// not stun, not invincible, not on the same team
if(!target.tag.sturn && sender.tag.team != target.tag.team && !target.tag.super)
{
target.tag.sturn = true;
target.moveSpeed = 0;
target.sendUpdated();
}
});
// called every 20ms
// param1 : deltatime ( elapsedTime )
App.onUpdate.Add(function(dt) {
if(!_start)
return;
_stateTimer += dt;
switch(_state)
{
case STATE_INIT:
App.showCenterLabel("The team that has painted the most land wins.\nHitting another teammate stuns them for 1 second.");
if(_stateTimer >= 5)
{
startState(STATE_READY);
}
break;
case STATE_READY:
App.showCenterLabel("The game will start soon.");
if(_stateTimer >= 3)
{
startState(STATE_PLAYING);
}
break;
case STATE_PLAYING:
App.showCenterLabel(_timer + `\nRED TEAM VS BLUE TEAM\n` + _redScore + " VS " + _blueScore);
if(_stateTimer >= 1) {
_stateTimer = 0;
_timer--;
}
// time over
if(_timer <= 0)
{
if(_redScore > _blueScore)
{
for(let i in _players) {
let p = _players[i];
p.title = null;
if(p.tag.team == 1)
{
p.sprite = tomb;
p.moveSpeed = 0;
p.sendUpdated();
}
}
_resultStr = 'RED TEAM VS BLUE TEAM\n' + _redScore + " VS " + _blueScore + '\nRED TEAM WIN';
}
else if(_redScore < _blueScore)
{
for(let i in _players) {
let p = _players[i];
p.title = null;
if(p.tag.team == 0)
{
p.sprite = tomb;
p.moveSpeed = 0;
p.sendUpdated();
}
_resultStr = 'RED TEAM VS BLUE TEAM\n' + _redScore + " VS " + _blueScore + '\nBLUE TEAM WIN';
}
}
else
{
for(let i in _players) {
let p = _players[i];
p.title = null;
p.sprite = null;
p.sendUpdated();
}
_resultStr = 'RED TEAM VS BLUE TEAM\n' + _redScore + " VS " + _blueScore + '\nDRAW';
}
startState(STATE_JUDGE);
}
else
{
for(let i in _players) {
let p = _players[i];
// for speed buff
if(_timer == 30 || _timer == 20 || _timer == 10)
{
if(_redScore > _blueScore)
{
if(p.tag.team == 1)
{
// set player title
p.title = '';
p.moveSpeed = 90;
p.sendUpdated();
}
else
{
p.title = null;
p.moveSpeed = 80;
p.sendUpdated();
}
}
else if(_redScore < _blueScore)
{
if(p.tag.team == 0)
{
p.title = '';
p.moveSpeed = 90;
p.sendUpdated();
}
else
{
p.title = null;
p.moveSpeed = 80;
p.sendUpdated();
}
}
}
// strun state check
if(p.tag.sturn)
{
p.tag.sTime -= dt;
if(p.tag.sTime <= 0)
{
p.tag.sturn = false;
p.tag.super = true;
p.tag.sTime = 1;
p.moveSpeed = 80;
p.sendUpdated();
}
}
// invincible state check
if(p.tag.super)
{
p.tag.sTime -= dt;
if(p.tag.sTime <= 0)
{
p.tag.super = false;
p.tag.sTime = 1;
p.sendUpdated();
}
}
// paint tile and update score
if(p.tag.x != p.tileX || p.tag.y != p.tileY) {
p.tag.x = p.tileX;
p.tag.y = p.tileY;
let oldValue = _objects[p.tileY * HEIGHT_KEY + p.tileX];
if(oldValue == p.tag.team)
continue;
if(oldValue == 0) {
_redScore--;
} else if(oldValue == 1) {
_blueScore--;
}
if(p.tag.team == 0)
_redScore++;
else
_blueScore++;
_objects[p.tileY * HEIGHT_KEY + p.tileX] = p.tag.team;
Map.putObject(p.tileX, p.tileY, p.tag.team == 0 ? red : blue,
{
overlap: true,
});
}
}
}
break;
case STATE_JUDGE:
App.showCenterLabel(_resultStr);
if(_stateTimer >= 5)
{
startState(STATE_END);
}
break;
case STATE_END:
break;
}
});
```
{% endcode %}
# Hangul Quiz Game
**1) File**
{% file src="/files/O9uj3kkZcQcQSn5TqguV" %}
**2) main.js**
{% code overflow="wrap" %}
```jsx
const STATE_INIT = 3000;
const STATE_READY = 3001;
const STATE_PLAYING = 3002;
const STATE_JUDGE = 3004;
const STATE_END = 3005;
const WORD_LINES = [
'한글날 휴게소 현기증 형광펜 호날두 허니문 하노이 핫도그 홍두깨 헤드셋 해돋이 한라봉 한라산 호랑이 허리띠 현미경 흰머리 황무지 햄버거 학부모 휘발유 허벅지 하수구 호신술 홍수아 화승총 허스키 햄스터 해운대 활주로 휴지통 화장품 회초리 핫팬츠 하회탈',
'피규어 팔꿈치 포도주 피라냐 피라미 피뢰침 프리킥 프라하 포미닛 팥빙수 표백제 판소리 피시방 팔씨름 피아노 편의점 파자마 포장지 표지판 파충류 파출부 파출소 포청천 팬클럽 포켓볼 피카소 피카츄 폭탄주 피터팬',
'태극기 태권도 턱걸이 테니스 트렁크 터미널 퇴마사 토마토 탬버린 투석기 턱시도 탕수육 토스트 태양계 티아라 타이밍 탈의실 트위터 퇴직금 통조림 태진아 태평양 테헤란',
'캥거루 콧구멍 코끼리 캐나다 콩나물 코너킥 컨디션 코러스 카메라 카메오 키보드 콤바인 코뿔소 케이크 코코넛 카타르 칵테일 커플링',
'참기름 철가방 초능력 축농증 취두부 청계천 책갈피 책꽂이 초능력 축농증 창덕궁 차두리 최루탄 최면술 칠면조 청바지 청소년 출석부 찹쌀떡 청와대 첫인상 치와와 초인종 추어탕 초음파 침전물 청첩장 초콜릿 치트키 출판사 챔피언 침팬지 최홍만',
'계기판 개나리 기내식 강낭콩 교도관 고드름 골동품 기러기 가로등 가래떡 글러브 그림자 기모노 금메달 거머리 교무실 공무원 건망증 구미호 김병만 국방부 거북선 광복절 곱빼기 가속도 각선미 기숙사 가오리 걸음마 강의실 거짓말 교차로 골키퍼 과태료 김태원 김태희 건포도 곰팡이 골판지 공포탄 김흥국 광화문 공휴일 고현정 꽹과리 까나리 깍두기 꽃다발 꽃등심 꼽등이 까마귀 까치발 깐풍기',
'케첩 킹카 킹콩 컨닝 채찍 창문 참깨 천국 축구 출근 친구 치과 취권 채권 초과 족발 절벽 젖병 주부 전복 중복 정복 절반 족보 쟁반 주번 좀비 제비 사과 사기 시급 시계 손금 선거 수능 설날 스님',
'모래 미래 미로 만루 떡밥 딸기 떡국 두유 득음 뉴욕 노을 낙엽 녹용 노인 눈물 냉면 나비 나방 가위 거울 근육 기타 깃털 구토 굴뚝 개념 그네 구름 기린 경마 경매 고막 가방 공부 고백 간병 갈비 김밥 거봉 군밤 기분 건빵 가시'
];
let WORDS = [];
let _state = STATE_INIT;
let _stateTimer = 0;
let _timer = 0;
let _choanswer = '';
let _answer = '';
let _start = false;
let _widget = null; // using for contents UI
let _players = App.player;
let _result = '';
for(let w in WORD_LINES)
WORDS = WORDS.concat(WORD_LINES[w].trim().split(' '));
function cho_hangul(str) {
cho = ["ㄱ","ㄲ","ㄴ","ㄷ","ㄸ","ㄹ","ㅁ","ㅂ","ㅃ","ㅅ","ㅆ","ㅇ","ㅈ","ㅉ","ㅊ","ㅋ","ㅌ","ㅍ","ㅎ"];
result = "";
for (let i = 0; i < str.length; ++i ) {
code = str.charCodeAt(i)-44032;
if(code>-1 && code<11172) result += cho[Math.floor(code/588)];
else result += str.charAt(i);
}
return result;
}
App.onStart.Add(function(){
startState(STATE_INIT);
});
// when chatting event
// player : person who chatted
// text : chat text
// return : enter chatting box
// return false or true : not appear in chatting box
App.onSay.add(function(player, text) {
if(_state == STATE_PLAYING)
{
if(_answer == text)
{
_result = player.name + '님 정답!\n정답은 ' + _answer;
startState(STATE_JUDGE);
}
}
});
function startState(state) {
_state = state;
_stateTimer = 0;
switch(_state)
{
case STATE_INIT:
if(_widget)
{
_widget.destroy();
_widget = null;
}
_answer = WORDS[Math.floor(Math.random() * WORDS.length)];
_timer = 60;
_choanswer = cho_hangul(_answer);
// called html UI
// param1 : file name
// param2 : position
// [ top, topleft, topright, middle, middleleft, middleright, bottom, bottomleft, bottomright, popup ]
// param3 : width size
// param4 : height size
_widget = App.showWidget('widget.html', 'top', 200, 300);
_widget.sendMessage({
state: _state,
timer: _timer,
answer: _choanswer,
});
startState(STATE_READY);
break;
case STATE_READY:
_start = true;
startState(STATE_PLAYING);
break;
case STATE_PLAYING:
App.showCenterLabel('목표: 초성힌트로 단어를 찾아내세요.',0xFFFFFF, 0x000000, 115);
_widget.sendMessage({
state: _state,
timer: _timer,
answer: _choanswer,
});
break;
case STATE_JUDGE:
break;
case STATE_END:
if(_widget)
{
_widget.destroy();
_widget = null; // must to do for using again
}
_start = false;
break;
}
}
App.onLeavePlayer.Add(function(p) {
p.title = null;
p.sprite = null;
p.moveSpeed = 80;
p.sendUpdated();
});
App.onDestroy.Add(function() {
_start = false;
if(_widget)
{
_widget.destroy();
_widget = null;
}
});
App.onUpdate.Add(function(dt) {
if(!_start)
return;
_stateTimer += dt;
switch(_state)
{
case STATE_INIT:
break;
case STATE_READY:
_start = true;
break;
case STATE_PLAYING:
if(_stateTimer >= 1)
{
_stateTimer = 0;
_timer -= 1;
}
if(_timer == 0)
{
_result = '정답은 ' + _answer + ' 입니다.';
startState(STATE_JUDGE);
}
break;
case STATE_JUDGE:
App.showCenterLabel(_result, 0xFFFFFF, 0x000000, 115);
if(_stateTimer >= 3)
startState(STATE_END);
break;
case STATE_END:
break;
}
});
```
{% endcode %}
# Avoid Poop Game
**1) File**
{% file src="/files/ONRP4uB453pfiGKlpSyo" %}
**2) main.js**
{% code overflow="wrap" %}
```jsx
// load sprite
let poop = App.loadSpritesheet('poop.png', 48, 43, [0], 16);
// load sprite
let tomb = App.loadSpritesheet('tomb.png', 32, 48, {
left: [0], // defined base anim
right: [0], // defined base anim
up: [0], // defined base anim
down: [0], // defined base anim
});
const STATE_INIT = 3000;
const STATE_READY = 3001;
const STATE_PLAYING = 3002;
const STATE_JUDGE = 3004;
const STATE_END = 3005;
let _level = 1;
let _levelTimer = 15;
let _levelAddTimer = 0;
let _start = false;
let _timer = 90;
let _poops = [];
let _stateTimer = 0;
let _genTime = 0;
let _dropTime = 0;
let _live = 0;
let _players = App.players; // App.players : get total players
function startApp()
{
_start = true;
_stateTimer = 0;
_genTime = 0;
_dropTime = 0;
_timer = 90;
for(let i in _players) {
let p = _players[i];
// create and utilize option data using tags.
p.tag = {
alive : true,
};
}
}
function startState(state)
{
_state = state;
_stateTImer = 0;
switch(_state)
{
case STATE_INIT:
startApp();
break;
case STATE_READY:
break;
case STATE_PLAYING:
// Show Label
App.showCenterLabel("Game Start");
break;
case STATE_JUDGE:
for(let i in _poops) {
let b = _poops[i];
Map.putObject(b[0], b[1], null);
}
break;
case STATE_END:
_start = false;
for(let i in _players) {
let p = _players[i];
p.sprite = null;
p.moveSpeed = 80;
p.sendUpdated();
}
break;
}
}
function checkSuvivors() {
if(!_start)
return;
let alive = 0;
for(let i in _players) {
let p = _players[i];
if(!p.sprite) {
lastSurvivor = p;
++alive;
}
}
return alive;
}
App.onStart.Add(function() {
startState(STATE_INIT);
});
// when player join the space event
App.onJoinPlayer.Add(function(p) {
// create and utilize option data using tags.
if(_start)
{
p.tag = {
alive : false,
};
// change move speed
p.moveSpeed = 20;
// change sprite image
p.sprite = tomb;
// when player property changed, have to call this method
p.sendUpdated();
}
_players = App.players;
});
// when player leave the space event
App.onLeavePlayer.Add(function(p) {
p.title = null;
p.sprite = null;
p.moveSpeed = 80;
p.sendUpdated();
_players = App.players; // App.players : get total players
});
// when player touched objects event
App.onObjectTouched.Add(function(sender, x, y, tileID) {
if(!_start)
return;
if(!sender.tag.alive)
return;
sender.tag.alive = false;
sender.sprite = tomb;
sender.moveSpeed = 40;
sender.sendUpdated();
_live = checkSuvivors();
if(_live == 1 || _live == 0)
{
startState(STATE_JUDGE);
}
else
{
if(_stateTimer >= 1)
{
_stateTimer = 0;
_timer--;
if(_timer <= 0)
{
startState(STATE_JUDGE);
}
}
}
});
// when the game block is pressed event
App.onDestroy.Add(function() {
for(let i in _poops) {
let b = _poops[i];
Map.putObject(b[0], b[1], null);
}
});
// called every 20ms
// param1 : deltatime ( elapsedTime )
App.onUpdate.Add(function(dt) {
if(!_start)
return;
_stateTimer += dt;
switch(_state)
{
case STATE_INIT:
App.showCenterLabel(`Avoid falling poop.`);
if(_stateTimer >= 5)
{
startState(STATE_READY);
}
break;
case STATE_READY:
App.showCenterLabel(`The game will start soon.`);
if(_stateTimer >= 3)
{
startState(STATE_PLAYING);
}
break;
case STATE_PLAYING:
_genTime -= dt;
if(_genTime <= 0) {
_genTime = Math.random() * (0.5 - (_level * 0.05));
let b = [Math.floor(Map.width * Math.random()),-1];
_poops.push(b);
if(b[1] >= 0)
Map.putObject(b[0], b[1], poop, {
overlap: true,
});
}
_dropTime -= dt;
if(_dropTime <= 0) {
_dropTime = Math.random() * (0.5 - (_level * 0.08));
for(let i in _poops) {
let b = _poops[i];
Map.putObject(b[0], b[1], null);
b[1]++;
if(b[1] < Map.height) {
Map.putObject(b[0], b[1], poop, {
overlap: true,
});
}
}
for(let k = _poops.length - 1;k >= 0;--k) {
let b = _poops[k];
if(b[1] >= Map.height)
_poops.splice(k, 1);
}
}
_levelAddTimer += dt;
if(_levelAddTimer >= _levelTimer)
{
_level++;
_levelAddTimer = 0;
if(_level > 6)
{
_level = 6;
}
}
break;
case STATE_JUDGE:
if(_live == 1)
{
App.showCenterLabel(`${lastSurvivor.name} is last suvivor`);
}
else if(_live == 0)
{
App.showCenterLabel(`There are no survivors.`);
}
else
{
App.showCenterLabel(`Final survivors : ` + _live);
}
if(_stateTimer >= 5)
{
startState(STATE_END);
}
break;
case STATE_END:
break;
}
});
```
{% endcode %}
# Boxing Game
**1) File**
{% file src="/files/uqC4e3BTx5EF3l84tQtD" %}
**2) main.js**
{% code overflow="wrap" %}
```jsx
let ghost = App.loadSpritesheet("ghost.png", 32, 48, {
left: [2],
right: [1],
up: [3],
down: [0],
});
let redBoxing = App.loadSpritesheet("redBoxing.png");
const STATE_INTRO = 3001;
const STATE_INIT = 3002;
const STATE_RULE = 3003;
const STATE_PLAYING = 3004;
const STATE_JUDGE = 3005;
const STATE_END = 3006;
let lastSurvivor = null;
let _start = false;
let _players = App.players;
let _state = STATE_INIT;
let _stateTimer = 0;
let _alive = 0;
let _widget = null;
function init() {
for (let i in _players) {
let p = _players[i];
setHPgage(p, p.tag.hp);
p.sendUpdated();
}
_alive = checkSuvivors();
}
function startState(state) {
_state = state;
_stateTimer = 0;
switch (_state) {
case STATE_INTRO:
for (let i in _players) {
let p = _players[i];
if (p.tag.widget) {
p.tag.widget.destroy();
p.tag.widget = null;
}
}
// Game starts
_start = true;
_widget = App.showWidget("intro.html", "middle", 350, 340);
App.playSound("intro.wav");
break;
case STATE_INIT:
init();
break;
case STATE_RULE:
_widget = App.showWidget("rule.html", "middle", 400, 200);
for (let i in _players) {
let p = _players[i];
p.moveSpeed = 0;
p.sendUpdated();
}
break;
case STATE_PLAYING:
if (_widget) {
_widget.destroy();
_widget = null;
}
_widget = App.showWidget("status.html", "top", 700, 300);
for (let i in _players) {
let p = _players[i];
p.moveSpeed = 80;
p.sendUpdated();
}
break;
case STATE_JUDGE:
break;
case STATE_END:
if (_widget) {
_widget.destroy();
_widget = null;
}
_start = false;
for (let i in _players) {
let p = _players[i];
p.sprite = null;
p.attackSprite = null;
p.title = null;
p.sprite = null;
p.moveSpeed = 80;
p.sendUpdated();
}
Map.clearAllObjects();
break;
}
}
// Functions for displaying HP blocks
function setHPgage(p, hp) {
switch (hp) {
case 5:
p.title = "▮▮▮▮▮";
break;
case 4:
p.title = "▮▮▮▮";
break;
case 3:
p.title = "▮▮▮";
break;
case 2:
p.title = "▮▮";
break;
case 1:
p.title = "▮";
break;
}
}
// Functions for checking the number of surviving players
function checkSuvivors() {
let alive = 0;
for (let i in _players) {
let p = _players[i];
if (p.tag.alive) {
lastSurvivor = p;
++alive;
}
}
return alive;
}
App.onStart.Add(function () {
startState(STATE_INTRO);
});
App.onJoinPlayer.Add(function (p) {
p.tag = {
widget: null,
alive: true,
hp: 5,
shield: false,
time: 1, // Property for setting the invincible status for 1 sec after getting hit
};
p.attackSprite = redBoxing;
// When a new player enters during the game, set the player dead
if (_start) {
p.moveSpeed = 5;
p.sprite = ghost;
p.tag.alive = false;
p.sendUpdated();
}
_players = App.players;
});
App.onLeavePlayer.Add(function (p) {
p.attackSprite = null;
p.title = null;
p.sprite = null;
p.moveSpeed = 80;
p.sendUpdated();
_players = App.players;
});
// When attacking another player
App.onUnitAttacked.Add(function (sender, x, y, target) {
if (_state != STATE_PLAYING) return;
// If the attacker is dead, return
if (!sender.tag.alive) return;
// If the target is alive, and "shield" is "false"
if (target.tag.alive && !target.tag.shield) {
target.tag.hp--; // Reduce the target's health by 1.
// When the target's health becomes 0
if (target.tag.hp == 0) {
target.title = null; // Delete title
target.tag.alive = false; // alive property false
target.sprite = ghost; // Avatar turn into a ghost
target.moveSpeed = 5; // moveSpeed 80 -> 5
target.sendUpdated(); // Update target property
_alive = checkSuvivors();
// When there is a single last survivor
if (_alive == 1) {
if (_widget) {
_widget.destroy();
_widget = null;
}
// Show all connected players the result.html widget
_widget = App.showWidget("result.html", "top", 1055, 500);
// Send the last survivor's nickname to display in the widget
_widget.sendMessage({
alive: _alive,
name: lastSurvivor.name,
});
App.playSound("result.wav");
_stateTimer = 0;
startState(STATE_JUDGE);
}
} else {
// Target becomes invincible for 1 sec after getting hit (shield = true)
target.tag.shield = true;
setHPgage(target, target.tag.hp);
target.sendUpdated();
}
}
});
App.onUpdate.Add(function (dt) {
if (!_start) return;
_stateTimer += dt;
switch (_state) {
case STATE_INTRO:
// Display the intro.html widget for 5 secs and start STATE_INIT
if (_stateTimer >= 5) {
if (_widget) {
_widget.destroy();
_widget = null;
}
App.stopSound();
startState(STATE_INIT);
}
break;
case STATE_INIT:
startState(STATE_RULE);
break;
// Display the rule.html widget for 3 secs and start STATE_PLAYING
case STATE_RULE:
if (_stateTimer >= 3) {
if (_widget) {
_widget.destroy();
_widget = null;
}
startState(STATE_PLAYING);
}
break;
case STATE_PLAYING:
// Update the number of survivors of the status.html widget
if (_widget) {
_widget.sendMessage({
suvivors: _alive,
});
}
for (let i in _players) {
let p = _players[i];
// Skip if the player is dead
if (!p.tag.alive) continue;
// Shield property becomes false after 1 sec
if (p.tag.shield) {
p.tag.time -= dt;
if (p.tag.time <= 0) {
p.tag.shield = false;
p.tag.time = 1; // Reset shield duration to 1 sec
}
}
}
_alive = checkSuvivors();
// Display the result.html widget if the number of a survivor is 1 or 0
if (_alive == 1) {
if (_widget) {
_widget.destroy();
_widget = null;
}
_widget = App.showWidget("result.html", "top", 1055, 500);
_widget.sendMessage({
alive: _alive,
name: lastSurvivor.name,
});
App.playSound("result.wav");
startState(STATE_JUDGE);
} else if (_alive == 0) {
if (_widget) {
_widget.destroy();
_widget = null;
}
_widget = App.showWidget("result.html", "top", 1055, 500);
_widget.sendMessage({
alive: _alive,
});
App.playSound("result.wav");
startState(STATE_JUDGE);
}
break;
//Display the result.html widget for 5 secs and start STATE_END
case STATE_JUDGE:
if (_stateTimer >= 5) {
startState(STATE_END);
}
break;
case STATE_END:
break;
}
});
// Function executes when the app is closed or the game block is destroyed.
App.onDestroy.Add(function () {
// Delete all objects installed by the app
Map.clearAllObjects();
});
```
{% endcode %}
# Sidebar App
A simple example that shows a sidebar app widget and closes it by clicking the X button.
To put an image in a widget, you need to **base64 encode the image** and wrap it in **an img tag** as shown in the example html code.
**1) File**
{% file src="/files/IrprvrbrAP4NhqowTcqk" %}
**2) main.js**
```jsx
// Function that works when the sidebar app is touched (clicked).
App.onSidebarTouched.Add(function (p) {
p.tag.widget = p.showWidget("widget.html", "sidebar", 350, 350);
p.tag.widget.onMessage.Add(function (player, data) {
if (data.type == "close") {
player.showCenterLabel("Widget has been closed.");
player.tag.widget.destroy();
player.tag.widget = null;
}
});
});
// Function is called when the player enters
App.onJoinPlayer.Add(function (p) {
p.tag = {
widget: null,
};
});
// Function is called when the player exits
App.onLeavePlayer.Add(function (p) {
if (p.tag.widget) {
p.tag.widget.destroy();
p.tag.widget = null;
}
});
```
**3) Image of the Sidebar App Running**
const STATE_INIT = 3000;
const STATE_READY = 3001;
const STATE_PLAYING = 3002;
const STATE_JUDGE = 3004;
const STATE_END = 3005;
const STATE_INTRO = 3006;
let _players = App.players;
let _state = STATE_INIT;
let _start = false;
let _stateTimer = 0;
let _countDown = 10;
let _finishCountDown = false;
let _finishCount = 30;
let _finishTimer = 0;
let _delayTimer = 0;
let _playerBaseSpeed = 120;
let _rank = 1;
let _rankList = [];
// When all players pass the finish line
function finishCheck(){
let allPlayer = 0;
let finishedPlayer = 0;
for(let p of _players){
if(!p)
continue;
if(p.tag.isNotPlayer)
continue;
if(p.tag.isFinish)
finishedPlayer++;
allPlayer++;
}
if(finishedPlayer == allPlayer)
return true
return false;
}
// Check if the race map is normally set; if not, return the error message
function checkSetting(){
let warningMsg = '';
if (!Map.hasLocation("race_start_point")) {
warningMsg = 'race_start_point';
}
if (!Map.hasLocation("race_end_point")) {
warningMsg = 'race_end_point';
}
if (!Map.hasLocation("race_finish_point")) {
warningMsg = 'race_finish_point';
}
return warningMsg;
}
function startState(state){
_state = state;
_stateTimer = 0;
switch (state) {
case STATE_INIT:
for(let p of _players){
//Check the user who started Race app
if(p.id == App.creatorID){
if(p.isMobile)
//Widget for mobile users
p.tag.widget = p.showWidget("setting.html", "bottom", 440, 340);
else
//Widget for desktop users
p.tag.widget = p.showWidget("setting.html", "middle", 440, 340);
p.tag.widget.sendMessage({
str_title : 'Run',
str_title_text1 : "A race to see who reaches the finish line the fastest",
str_title_text2 : 'Click the Start Running button to start the game',
str_title_start : "Start",
str_title_how : "How to set up a map"
});
p.tag.widget.onMessage.Add(function (sender, msg) {
//Delete the displayed widget when quitting the game
if (msg.type == "cancle") {
if(p.tag.widget_warning){
p.tag.widget_warning.destroy();
p.tag.widget_warning = null;
}
if(p.tag.widget){
p.tag.widget.destroy();
p.tag.widget = null;
}
} else {
// Check the necessary settings for the map
let warning = checkSetting();
if(warning !== ''){
if(p.tag.widget_warning){
p.tag.widget_warning.destroy();
p.tag.widget_warning = null;
}
if(p.isMobile)
p.tag.widget_warning = App.showWidget("warning.html", "top", 440, 60);
else
p.tag.widget_warning = App.showWidget("warning.html", "bottom", 440, 250);
p.tag.widget_warning.sendMessage({
str_warningText : 'Race track needs to be set up',
str_warningText2 : ' needed)',
str_warningText3 : 'Run',
warningMsg: warning,
})
} else {
if(p.tag.widget){
p.tag.widget.destroy();
p.tag.widget = null;
}
startState(STATE_INTRO);
_start = true;
}
}
})
}
}
break;
case STATE_INTRO:
App.showCenterLabel("\n minigame - RUN \n\n", 0xffffff, 0x000000, 120); ;
break;
case STATE_READY:
for(let p of _players){
if(p.tag.start)
continue;
//Locate all players to "race_start_point"
p.spawnAtLocation("race_start_point");
p.moveSpeed = 0;
p.sendUpdated();
}
break;
case STATE_PLAYING:
App.showCenterLabel("Start!!", 0xffffff, 0x000000, 120); ;
for(let p of _players){
if(p.tag.start)
continue;
p.moveSpeed = _playerBaseSpeed;
p.sendUpdated();
}
break
// Process the game result
case STATE_JUDGE:
for(let i =0 ; i <_rankList.length; i++){
let rank = '';
if(i == 0)
rank = '1st';
else if(i == 1)
rank = '2nd';
else if(i == 2)
rank = '3rd';
else
rank = `${i + 1}th`;
//Display the ranking when the game ends
App.sayToAll(`${rank} : ${_rankList[i].name} !`);
}
for(let p of _players){
p.moveSpeed = 80;
p.sendUpdated();
}
_start = false;
break
// Process the game end
case STATE_END:
for(let p of _players){
//Spawn all players to "race_end_point" when the game ends
p.spawnAtLocation("race_end_point");
if(p.tag.isNotPlayer)
p.tag.isNotPlayer = false;
}
_start = false;
break
}
}
App.onLeavePlayer.add(function(p){
_players = App.players;
p.moveSpeed = 80;
p.sendUpdated();
})
// Process when a player enters the Space
App.onJoinPlayer.Add(function (p) {
p.tag = {};
//Process when a player enters after the game has started
if (_start) {
p.tag.isNotPlayer = true;
} else {
p.tag.isNotPlayer = false;
p.tag.speedTimer = 0;
p.tag.isFinish = false;
p.tag.speedChnage = false;
p.sendUpdated();
}
//Locate a player who enters after the game has started to "race_end_point"
if(p.tag.isNotPlayer)
p.spawnAtLocation("race_end_point");
_players = App.players;
});
App.onStart.Add(function(){
startState(_state);
//When a player passes through the locations "speed_set_40", "speed_set_60", "speed_set_140", and "speed_set_160"
//its speed becomes the value of the location for 2secs and become normal (_playerBaseSpeed) again
//e.g. passing "speed_set_40" turns the player's speed to 40
let speed = [40,60,140,160];
for(let i =0; i<speed.length; i++){
App.addOnLocationTouched(`speed_set_${speed[i]}`, function(p){
if(_state !== STATE_PLAYING)
return;
p.moveSpeed = speed[i];
p.tag.speedTimer = 0;
p.tag.speedChnage = true;
//A label saying "Speed increased" or "Speed reduced" appears to the player when the speed has changed
let str = '';
if(i == 0)
str = 'Speed greatly reduced';
else if(i == 1)
str = 'Speed reduced';
else if(i == 2)
str = 'Speed increased';
else
str = 'Speed greatly increased';
p.showCenterLabel(`${str}`, 0xffffff, 0x000000, 120);
p.sendUpdated();
})
}
//"speed_set_random" means the player's speed will become one of 40, 60, 140, or 160 in a random way for 2 secs
App.addOnLocationTouched(`speed_set_random`, function(p){
if(_state !== STATE_PLAYING)
return;
p.moveSpeed = speed[Math.floor(Math.random() * 4)];
//A label saying "Speed increased" or "Speed reduced" appears to the player when the speed has changed
let str = '';
if(p.moveSpeed == 40)
str = 'Speed greatly reduced';
else if(p.moveSpeed == 60)
str = 'Speed reduced';
else if(p.moveSpeed == 140)
str = 'Speed increased';
else
str = 'Speed greatly increased';
p.showCenterLabel(`${str}`, 0xffffff, 0x000000, 120);
p.tag.speedTimer = 0;
p.tag.speedChnage = true;
p.sendUpdated();
})
//When a player passes the finish line
App.addOnLocationTouched("race_finish_point", function(p){
if(p.tag.isFinish)
return;
if(p.tag.isNotPlayer)
return;
_delayTimer = 0;
// When the first runner passes the finish line, a 30-second countdown begins
if(!_finishCountDown)
_finishCountDown = true;
// Check if any player passes the finish line first time
p.tag.isFinish = true;
_rankList.push(p);
_rank++;
})
});
App.onUpdate.Add(function(dt){
_stateTimer += dt;
if(_start){
for(let p of _players){
if(p.tag.isNotPlayer)
p.showCenterLabel("game is in progress, please wait..",0xffffff, 0x000000, 120);
}
}
switch (_state) {
case STATE_INIT:
break;
case STATE_INTRO:
if(_stateTimer >= 3){
startState(STATE_READY);
}
break;
case STATE_READY:
//A 10-second countdown begins at the start line
App.showCenterLabel(`${_countDown} seconds later the race will start. `,0xffffff, 0x000000, 120);
if(_stateTimer >= 1){
_stateTimer = 0;
_countDown --;
}
//The race begins when the countdown is over (when "_countDown" becomes 0)
if(_countDown <= 0)
startState(STATE_PLAYING);
break;
case STATE_PLAYING:
for(let p of _players){
if(finishCheck() && _rankList.length == 0){
p.showCenterLabel("There is no winner",0xffffff, 0x000000, 120);
p.spawnAtLocation("race_end_point");
startState(STATE_END);
}
// else if(finishCheck())
// startState(STATE_JUDGE);
if(p.tag.isNotPlayer)
continue;
if(p.tag.speedChnage)
p.tag.speedTimer += dt;
//The speed returns to normal (_playerBaseSpeed) after 2 secs whichever tile players pass
if(p.tag.speedTimer >= 2 && p.tag.speedChnage){
p.moveSpeed = _playerBaseSpeed;
p.tag.speedChnage = false;
p.sendUpdated();
}
}
if(_finishCountDown)
{
_delayTimer += dt;
//When the first player passes the finish line, a label showing the name and a countdown number appears above the player avatar's head
if(_delayTimer <=1.5)
App.showCenterLabel(`${_rankList[_rankList.length -1].name} ${_rank - 1} place ! \n\n ${_finishCount} seconds later the race will end`,0xffffff, 0x000000, 120);
else
App.showCenterLabel(`${_finishCount} seconds later the race will end`,0xffffff, 0x000000, 120);
_finishTimer += dt;
if(_finishTimer >= 1){
_finishCount--;
_finishTimer = 0;
}
// When the countdown is over or every player has finished, move to the next state
if(_finishCount == 0 || finishCheck()){
startState(STATE_JUDGE);
}
}
break;
case STATE_JUDGE:
//A label appears that says who the winner is for 5 sec
if(_stateTimer <= 5){
App.showCenterLabel(`- Winner - \n\n ${_rankList[0].name}`,0xffffff, 0x000000, 120);
}
//A label appears that says "You will soon be transported to the waiting room" for 5 sec
else if(_stateTimer > 5 && _stateTimer <= 10 ){
App.showCenterLabel("You will soon be transported to the waiting room",0xffffff, 0x000000, 120);
}
else {
startState(STATE_END);
}
break;
case STATE_END:
break;
}
});
***
# ZEP Script FAQ
#### Q. Can I change the avatar’s appearance using ZEP Script?
{% hint style="success" %}
Yes, after loading the sprite sheet, you can apply it and change the avatar’s appearance when a specific event occurs. Please check the [Changing Avatar Image](/zep-script/zep-script-guide/explore-zep-script/tutorials/changing-avatar-image) page.
{% endhint %}
#### Q. Is ZEP Script free to use?
{% hint style="success" %}
Yes, developing and deploying apps using ZEP Script is free.
{% endhint %}
#### Q. Is it possible to charge users using ZEP Script?
{% hint style="success" %}
Not at this time, but we plan to add a cash purchase and cryptocurrency purchase feature.
{% endhint %}
#### Q. Can I sell an app created using ZEP Script?
{% hint style="success" %}
It is not possible currently, but it will be in a future update.
{% endhint %}
#### Q. Is there an easier way to debug an app created using ZEP Script without deploying it?
{% hint style="success" %}
We are preparing an improved developer environment, but it is not available at this time.
{% endhint %}
#### Q. Can I use a different programming language to develop ZEP Script?
{% hint style="success" %}
Currently, the ZEP Script development environment only supports JavaScript.
{% endhint %}
#### Q. I would like to link with my own server API. How do I do this?
{% hint style="success" %}
ZEP Script supports JavaScript API Call. For more information, please refer to the [Communicating with an External API](/zep-script/zep-script-guide/explore-zep-script/tutorials/communicating-with-an-external-api) page.
{% endhint %}
# Appendix
* [ZEP Script Use Cases](/zep-script/zep-script-guide/appendix/zep-script-use-cases)
* [Understanding Spaces and Maps](/zep-script/zep-script-guide/appendix/understanding-spaces-and-maps)
* [JavaScript Keycode List](/zep-script/zep-script-guide/appendix/javascript-keycode-list)
* [Understanding Sprite Sheets](/zep-script/zep-script-guide/appendix/understanding-sprite-sheets)
* [TileEffectType Detailed Explanation](/zep-script/zep-script-guide/appendix/tileeffecttype-detailed-explanation)
* [What are Reference Coordinates?](/zep-script/zep-script-guide/appendix/what-are-reference-coordinates)
* [Communicating with an External API](/zep-script/zep-script-guide/explore-zep-script/tutorials/communicating-with-an-external-api)
* [How to Use URL Query Strings](/zep-script/zep-script-guide/appendix/how-to-use-url-query-strings)
* [Grammar Available for Widgets](/zep-script/zep-script-guide/appendix/grammar-available-for-widgets)
* [Object Interaction with ZEP Script](/zep-script/zep-script-guide/appendix/object-interaction-with-zep-script)
* [Object npcProperty](/zep-script/zep-script-guide/appendix/object-npcproperty)
# ZEP Script Use Cases
## Games
Here you can see some examples of games that were developed using ZEP Script.
### 🗃 ZEP Script Use Cases
You can use **ZEP Script** to create a variety of fun games.
Check out some games development cases that are used.
### Saving Private Kang: Lingtea X Kingdom of the Winds: Yeon
Kingdom of the Wind: Yeon, ZEP, and Lingtea collaborated to create a quest-style game called **“Saving Private Kang.”**
### Arcade-Style Mini-Game: Lingtea X Kingdom of the Winds: Yeon
Kingdom of the Wind: Yeon, ZEP, and Lingtea collaborated to create an arcade-style mini-game featuring imagery from Kingdom of the Wind: Yeon, such as squirrels and acorns.
This is a very cutely expressed game.
### Paintman Game at the SUPERCAT Job Fair
This is a “Paintman” game that was played at the SUPERCAT Job Fair.
Using ZEP Script, you can even develop games for groups of 100 people or more!
### Omok Game Developed by ZEP Users
There are more and more cases of ZEP users designing games using ZEP Script. Omok that is played with ZEP characters! Isn’t that fun?
## Events
Here you can see some examples of ZEP Script being used for events.
###
### 🗃 ZEP Script Use Cases
By using **ZEP Script,** you can create a more interactive event.
See some examples of events using **ZEP Script** below.
### **Klaytn Museum**
This is an example of effectively demonstrating the technical strengths of the Klaytn blockchain by implementing **ZEP Script**.
Conveyor belt implemented using ZEP Script
# Understanding Spaces and Maps
The relationship between a Space and its maps
A Space is a unit of a group of one or more maps.
Spaces and maps have a **HashID** to distinguish them from other Spaces or maps.
One of the maps included in a Space has the “Entry Map” property, and if you access a Space with only a spaceHashID and no mapID, you will be moved to the map with the “Entry Map” property.
If you go into the ZEP Map Editor, you can see the following URL format:
Here you can see that **Ak42Xz** is the **SpaceHashID** while **25g3RQ** is the **MapHashID**.
# JavaScript Keycode List
```jsx
//
App.loadSpritesheet(fileName: string, frameWidth: integer, frameHeight: integer, anims: array, frameRate: integer)
```
### frameWidth & frameHeight
Each Blueman sprite has an image size of 48 px\*64 px.
If 48 and 64 are specified for frameWidth and frameHeight respectively, each image will be numbered from 0 to 41.
## anims
anims refers to an array to assign animations to.
The form is different if the sprite is being used for an avatar compared to when the sprite is being used for an object.
### Example 1) Dancing Blueman Object
The dancing Blueman object animation corresponds to images 21 to 38 as shown in the code below.
You can use image numbers by specifying them as an array.
{% code overflow="wrap" %}
```jsx
let blueman_dance = App.loadSpritesheet(
"blueman.png",
48,
64,
[20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37], // Images from 21 to 38 form animation
8
);
```
{% endcode %}
### Example 2) Using Blueman as an Avatar Image
Unlike objects, avatars can trigger various animations based on which keys the player presses. In this case, you can input { } brackets in the anims parameter and specify an image array for the animation name as follows. There are a total of 9 types of animations that can be assigned to a character as seen below, and they can be omitted if the sprite sheet doesn’t contain frames for a specific animation.
```jsx
let blueman = App.loadSpritesheet('blueman.png', 48, 64, {
left: [5, 6, 7, 8, 9], // images that moves 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);
// Player avatar changes when the player enters
App.onJoinPlayer.Add(function(player){
player.sprite = blueman;
player.sendUpdated();
});
```
### Example 3) As a Single Image
If the sprite is a single image, you do not need to enter any parameters except for the file name.
```jsx
let blueman = App.loadSpritesheet('blueman.png')
```
A single image can also be applied as a character image. However, since no animation is specified, the image will be the same no matter which direction it moves.
***
# TileEffectType Detailed Explanation
This page explains how to use Tile Effects (TileEffectType) when using the function `Map.putTileEffect`. For more information on Tile Effects, please refer to the link provided below.
:fire: [**Tile Effects**](broken://pages/mLgIqpsZNwnpWkSA5B7A)
## 📗 Basic Tile Effects
### TileEffectType.NONE
A tile effect that has no effect.
**Example**
```jsx
//Erases tile effects on the specified coordinates
Map.putTileEffect(x, y, TileEffectType.NONE);
```
### **TileEffectType.IMPASSABLE**
A tile effect that does not allow users to pass.
**Example**
```jsx
//Sets an IMPASSABLE tile effect on the corresponding coordinates
Map.putTileEffect(x, y, TileEffectType.IMPASSABLE);
```
### **TileEffectType.SPAWN**
A tile effect that spawns users to a coordinate when the user enters the map.
**Example**
```jsx
//Sets the SPAWN tile effect on the corresponding coordinates
Map.putTileEffect(x, y, TileEffectType.SPAWN);
```
## 🌀 Portal Tile Effects
### TileEffectType.PORTAL
A tile effect that moves users to a **different specified location area** or a **different map within the space**.
**Parameter**
Name
Type
Description
type
Number
When the type is 0, can set a portal tile that allows players to another map within the Space. When the type is 1, can set a portal tile that allows players to move to another specific location within the map.
targetMapID
String
The MapID value of the target map
label
String
The text value to display over the portal
triggerByTouch
Boolean
When true: activates when contact is made When false: activates when f is pressed
invisible
Boolean
When true: hide the default portal image When false: show the default portal image
locationName
String
Value of the target location’s name (If type is 1, this value is a required field.)
**Example**
{% code overflow="wrap" %}
```jsx
// when type: 0
// Installs a portal tile that leads to another map in the Space
Map.putTileEffect(x, y, TileEffectType.PORTAL, {
type: 0, // Required
locationName: "TEST", // Optional
targetMapID: "gyV1N2", // Required
label: "PORTAL-TYPE0", // Optional
triggerByTouch: true // Optional, "false" is default
});
// If type: 1
// Installs a portal tile that leads to a target area in the same map
Map.putTileEffect(x, y, TileEffectType.PORTAL, {
type: 1, // Required
label: "PORTAL-TYPE1", // Optional
locationName: "TEST", // Required
invisible: true, // Optional, hiding the default portal image
triggerByTouch: true // Optional, "false" is default
});
```
{% endcode %}
### TileEffectType.SPACE\_PORTAL
A tile effect that moves participants to another Space.
**Parameter**
Name
Type
Description
label
String
The text value to display over the portal
targetMapID
String
The SpaceID value of the target Space
https://zep.us/play/[Space ID]
locationName
String
Value of the target location’s name
triggerByTouch
Boolean
When true: activates when contact is made When false: activates when f is pressed
invisible
Boolean
When true: hide the default portal image When false: show the default portal image
**Example**
```jsx
// Installs a portal tile that leads to another Space
Map.putTileEffect(x, y, TileEffectType.SPACE_PORTAL, {
label: "SPACE_PORTAL", // Optional
targetMapID: "zydmYD", //Required
locationName: "SPACE1", // Optional
invisible: true, // Optional, "false" is default
triggerByTouch: true, // Optional, "false" is default
});
```
## 🌐 Embed Tile Effects
### TileEffectType.EMBED
A tile effect that opens a web link in a new window.
**Parameter**
Name
Type
Description
link
String
Value of the web URL
align2
String
Location where to show the window ’popup’, ‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’
label
String
The text value to display over the portal
triggerByTouch
Boolean
When true: activates when contact is made When false: activates when f is pressed
invisible
Boolean
When true: hide the default portal image When false: show the default portal image
**Example**
// Installs a portal effect that opens a web link in a new window
Map.putTileEffect(x, y, TileEffectType.EMBED, {
link: "https://zep.us/", // Required
align2: "top", // Required
label: "ZEP-SCRIPT-EMBED", // Optional
});
### TileEffectType.WEB\_PORTAL
A tile effect that opens a web link in a new tab.
**Parameter**
Name
Type
Description
link
String
Value of the web URL
label
String
The text value to display over the portal
invisible
Boolean
When true: hide the default portal image When false: show the default portal image
**Example**
```jsx
// Installs a tile effect that opens a web link in a new tab.
Map.putTileEffect(x, y, TileEffectType.WEB_PORTAL, {
link: "https://zep.us/", // Required
label: "ZEP-SCRIPT-WEB-PORTAL", // Optional
invisible: true, // Optional, "false" is default
});
```
### TileEffectType.TILE\_EMBED
A tile effect that embeds a web URL in a designated area.
**Parameter**
Name
Type
Description
link
String
Value of the web URL
width
number
Width of the designated area (number of tiles)
height
number
Height of the designated area (number of tiles)
**Example**
```jsx
// Installs a web in a designated area
Map.putTileEffect(x, y, TileEffectType.TILE_EMBED, {
link: "https://zep.us/", // Required
width: 5, // Required
height: 5, // Required
});
```
## 💠 Utility Tile Effects
### TileEffectType.PRIVATE\_AREA
A tile effect that has a private area effect.
**Parameter**
Name
Type
Description
id
Number
ID Value of the private area
impassable
Boolean
When true: sets the private area "impassable"
param1
String
When param1 is "true", only one person is allowed per tile
**Example**
```jsx
// Installs a private area in the designated coordinates
Map.putTileEffect(18, 15, TileEffectType.PRIVATE_AREA, {
id: 3, // Required
impassable: false, // Optional, "false" is default
param1: "true", // Optional, "false" is default
});
```
### TileEffectType.LOCATION
A tile effect for a map location.
**Parameter**
Name
Type
Description
label
String
The text value to display over the tile
name
String
Name of the map location
width
number
Width of the designated area (number of tiles)
height
number
Height of the designated area (number of tiles)
**Example**
```jsx
// Installs a map location in the designated coordinates
Map.putTileEffect(x, y, TileEffectType.LOCATION, {
label: "LOCATION", // Optional
name: "zep-script-location", // Required
width: 3, // Required
height: 2, // Required
});
```
### TileEffectType.AMBIENT\_SOUND
A tile effect for ambient sound.
**Parameter**
Name
Type
Description
link
String
Name of the sound file to play (included in the ZIP file)
activeDistance
Number
Radius of ambient sound (number of tiles)
triggerByTouch
Boolean
When true: activates when contact is made When false: activates when f is pressed
**Example**
```jsx
Map.putTileEffect(x, y, TileEffectType.AMBIENT_SOUND, {
link: "ring.mp3", // Required
activeDistance: 1, // Required
triggerByTouch: false, // Optional
});
```
# What are Reference Coordinates?
Reference coordinates are standards of where the image will be displayed when the object is placed.
What will happen when the object image is placed on 3, 3 with the reference coordinates of Left-Top as displayed below?
The image will be placed on the 3, 3 tile box like below if the reference coordinates are Left-Top.
# Communicating with an External API
You can send GET, POST, etc. requests with arguments to an external API.
### httpGet
Change the nicknames of the users who have just entered with the [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
Receive the header and data sent from the app in response and display in the chat window.
```jsx
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
App.httpPost(
"https://postman-echo.com/post",
{
"test-header": "zep",
},
{
name: "zepscript",
},
(res) => {
let response = JSON.parse(res);
App.sayToAll(`header sent: ${response.headers["test-header"]}`, 0xffffff);
App.sayToAll(`data sent: ${response.form.name}`, 0xffffff);
}
);
});
```
{% hint style="warning" %}
Please Note
* For the tutorial, we recommend setting the app type to Mini-Game.
* The JSON file name must be “main”. Please create a new text file and name it main.js.
* If you do not know how to deploy an app, please refer to the [**ZEP Script Deployment Guide**](/zep-script/zep-script-guide/zep-script-development-guide/zep-script-deployment-guide).
{% endhint %}
# How to Use URL Query Strings
A URL query string is a data delivery method that provides input data at the end of the URL.\
**E.g.,** `https://zep.us/play/{mapHashId}?{parameter}={value}`
You can deliver data to a ZEP Space or ZEP Script using a URL query strings.
## URL Query String Parameters Available in ZEP
### 1. name
When users who are not signed in enter a Space, you can set their nickname as the value passed as the name parameter.
* Example: `https://zep.us/play/{mapHashId}?name=A`
:warning: Make sure to deactivate nickname settings pop-up for guests!
### 2. customData
You can pass data to ZEP Script player objects.\
You can create a whitelist function, such as identifying users by passing user identification information such as SSO token information to ZEP Script.
**Example 1** \
Receive user information with customData and apply it. (Normal app, sidebar app recommended)
⚡ URL used for example
`https://zep.us/play/{mapHashId}?customData={"name":"customUser", "moveSpeed":150, "title":"customTitle"}`
```jsx
App.onJoinPlayer.Add(function (player) {
// Checks if there is customData passed
if (player.customData) {
// Converts customData to object and uses
let playerCustomData = JSON.parse(player.customData);
if (playerCustomData.hasOwnProperty("name")) {
player.name = playerCustomData["name"];
}
if (playerCustomData.hasOwnProperty("moveSpeed")) {
player.moveSpeed = playerCustomData["moveSpeed"];
}
if (playerCustomData.hasOwnProperty("title")) {
player.title = playerCustomData["title"];
}
App.sayToAll("customData applied");
player.sendUpdated();
}
// Displays message if there is no customData passed
else {
App.sayToAll("customData not delivered.");
}
});
```
When customData is Successfully Applied
When Failed to Receive customData
**Example 2**
Create a simple token-based whitelist function. (Normal app, sidebar app recommended)
{% file src="/files/O7bDMCIodHZcWxeLsOK9" %}
✅ A token with base64 encryption in the browser developer tools (F12) has been created as follows:
⚡ URL used for example
`https://zep.us/play/{mapHashId}?customData=JTdCJTIydG9rZW4lMjIlM0ElMjIlRUMlOUMlQTAlRUMlQTAlODAxJTJGd2hpdGVMaXN0JTIyJTdE`
```jsx
App.onJoinPlayer.Add(function (player) {
player.tag = {};
if (player.customData) {
let token = player.customData;
// Sends token to widget to decrypt
player.tag.widget = player.showWidget("main.html", "topleft", 1, 1);
player.tag.widget.sendMessage({
type: "decode",
token: token,
});
player.tag.widget.onMessage.Add(function (player, data) {
if (data.type == "decode") {
let decodedToken = data.decodedToken;
App.sayToAll(decodedToken);
// Receives the decrypted code and converts it to an object
let playerData = JSON.parse(decodedToken);
let playerName = playerData["token"].split("/")[0];
let isTrusted = playerData["token"].split("/")[1];
if (isTrusted == "whiteList") {
player.name = playerName;
player.title = "verified user";
player.sendUpdated();
}
player.tag.widget.destroy();
player.tag.widget = null;
}
});
} else {
App.sayToAll("customData not delivered.");
}
});
```
```powershell
// Script used in widget
window.addEventListener("message", function (e) {
if (e.data.type == "decode") {
// Decrypt the base64 token
decodedToken = decodeURIComponent(atob(e.data.token));
window.parent.postMessage({
type: "decode",
decodedToken: decodedToken
}, "*")
}
})
```
When Successfully Verified with a Token
# How to Change the Mobile Interaction Button
You can customize the mobile interaction button by using `App.loadSpriteSheet`.
> Note: The size of the mobile button image is 180 x 180 px.
```
// let button_image = App.loadSpritesheet("button_image.png");
let button;
App.onStart.Add(function () {
// add button
button = App.addMobileButton(8, 145, 75, function (player) {
App.sayToAll(`${player.name}, has tapped the button.`)
});
button.image = button_image;
button.sendUpdated();
});
```
Example of the Updated Mobile Button
# Grammar Available for Widgets
## Open a Webpage in a New Window
You can open a webpage in a new window by entering the codes below within the widget's `
```
# Methods
### Introduction
This function closes the widget or sends data to the widget from the App.
Name
Description
sendMessage
Function to send data to the widget from the App
destroy
Function to close the widget
## 📚 API Explanation and Example
### **Methods at a Glance**
```jsx
// Sends a message to the created widget
widget.sendMessage(object: any)
// Closes widget
widget.destroy()
```
### sendMessage
{% hint style="info" %}
widget.sendMessage(object: any)
{% endhint %}
This sends data to the widget from the App.
**Parameter**
Name
Type
Description
object
any
Data being sent to the widget from the App E.g. { name : “test”, message : “message” }
**Example**
Send text and image data to the widget.
{% file src="/files/rjlLqABtWu1UkpIdF4dQ" %}
```jsx
// Activates function when a player enters
App.onJoinPlayer.Add(function (player) {
player.tag = {
widget: null,
};
player.tag.widget = player.showWidget("sample.html", "top", 300, 300);
player.tag.widget.onMessage.Add(function (player, data) {
if (data.type == "close") {
player.showCenterLabel("The widget closed.");
player.tag.widget.destroy();
player.tag.widget = null;
}
});
player.sendUpdated();
});
// Activates function when q is pressed
// Sends blueman image and text to the widget
// **[App.addOnKeyDown](https://www.notion.so/Callbacks-7ac5078bab7c4f3180ae05463713581d) Explanation [(Link)](https://www.notion.so/Callbacks-7ac5078bab7c4f3180ae05463713581d)**
App.addOnKeyDown(81, function (player) {
if (player.tag.widget) {
player.tag.widget.sendMessage({
text: "Blueman",
});
}
});
```
**sample.html**: Section where the text and image data is received and displayed
```jsx
window.addEventListener("message", function (e) {
let text = e.data.text;
let content = document.getElementById("content");
if (content) {
while (content.hasChildNodes()) {
content.removeChild(content.firstChild);
}
let content_image = document.createElement("img");
content_image.setAttribute("src", BLUEMAN);
content_image.setAttribute("class", "cover");
content.append(content_image);
}
if (text) {
document.getElementById("text").innerText = text;
}
});
const BLUEMAN = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAADAAAABACAYAAABcIPRGAAAACXBIWXMAAA7DAAAOwwHHb6hkAAAF+UlEQVRoge2ZX2hTVxzHPxk+lOFDbJCtHYVYmpCO7qHEsDWtyFrppkLtxDD3v8hgm7TLgw42Xeek6wSnD7XgJhvi0G1CpDphlHWdIiN3jrb40CDlRmyhKA7XGvaw9WFw9nBzbm9u7k1zb9L5sHzhkntPfuec7/fc3/md8zsXKqigggoqqKCCCiqooIL/Kzyr3L5Y7b5Wo1GddF1wUC+cVw+udr+uIYxXXXBQv4/0Tgvz/zbXQ4VoVoRoVoSo2fORkM8YCMpn46+8KFHAIyXTz+JG1MPjbx7OKYv0The0vxEt3ZNKFaCPXrMiuPfVoaIrNiuCZkWv/lDcSPh83bYuwgouhGHOyHbckCjpDTzqi+j3htHUn41ldv/Pqwdz2vmvIHy+7pyIY3cVa+P2LbidRULG+Cp/EID0WAzQYr8ss8LSnKqvCYHOhF4G+lrhiNMaR7RtkB6LrUhcosofJOBPsDSnkh6L6SLcomQBVuS9wZCtfUadATQhdQzq9d2iJAHSFSR5SVyStILRpsofBFVrpxQRbiAA0REKC0AEOhMi0jtd1IQlO2kjvdMi0JnIaQcXk9j1G+gIhfX7pTmVibEYi+p1oKOo+tXBp3JGvSMU5ueZKcc8XAuo9Xq4mxFc7uujKbwWb2AU7j/Q/ly/zr5i1mYxOUomrZKa6mPoJ4Var7uAWNJCVuv10BRuwBswRR8pxAxTuTcQpCnc4Jo8lCmMAkRfeifnWfnuc1c2TuFGurjc10di4lcAho4PlEwivq8fgFikha7hYUe8Cr0Bc0TQG20KN9AUbuDQF2dzDIwjbDe6djaH336tCLr5sBMgIr3TejxfnPqGhYVLAtPIxCItlpWLcQ2jjV07xcBqEotAZ4J/Xm4CtJW2OvwKPl83aG/FU98TJzV1a7nG+nW5kUc+W102dVJTt6jviYNDtzYLEIHORN5WQIowwJP11Rwo4+dRxs8X7NDOxqnvSxgFCJ+vWye/5tsUaz/eVWiz5ekaHiaTVu3D5kq4/4BMWnVNHpYFCJ+vO2eUM+oMf/R8Cmjb3ux22dyJp74nbikiumV3wWdJ3o3b5BAwk/cGQ2TUGX2PDkXt08XtM0PagmbwayPpHLcpE3lLAbCcYPy1MMHCwqViOxEAuhAbGIgX225B5IVRt+TlXKnv0TIzbY/UoBucnIdj/RpxaZsei+WFZqfwACLyzCbuLT5vJu6IvJz8H+xcQkkq7K3LNzw5D9HWKEdGqgBtntnMLUcCkCImrv/ipA6AGLkyAaCT+nqfD4DT5xJEW6O6oZJU2POq9nbeOL4AaGIBdrZHzO06FgBZEQCbt+/KM7z2wwVC/M3Z65Oynhi5MkFowxMA7HgriTcYYvNjV/jsw3dtO3zvkxNc+72djDrD96daAZiZveNahLlCwYxIJjHGxOPm7F1dgIT6Y/4ASASfu6DfSwHgXoR5JfYUuiTxjlCY22eGWEyO8uSGWk6fS7BjkyZkaU7l4tVJy84uXp3Ug4S0b/TX0Oiv4YVnN5J1R0dppZN8QFzu66NreJiOUBhv9GlAizZd/XH2Dwzp5I6MVHFkJGXRhDZPluZU2LSWmdk7NPpr9H+liJ3tkaKjk6OMrG33NhaTo3z5/utawf0HtO3elmOTOnqK8S3byagzedf4lu2kjp7SbZWkkteHVVkhOPE3YVykMmlVv69u3cr+gSF9cq50LiQn+7H+ODdn79Lor+Hi1UmUpMKB9qCjVdrprBdygUpN3cK4IzWuBTKPMAoxl8k1YP/AEAAHXtRcUu6pqlu3FsXPcVIvk3iz65hHvZjnQGeCvXUG8i7gNKn31PfE86JEXXDQctTtYDy5q++JZ8+TllHs6IO7U4m8tcN4Lip3svfm1JzzUhmhMhYNZpTf9HunO9RyfO4UVkmP8cjcfBRvhDyWd8upbB/5rCDzCNM3YisYF0xHKIsAY/IjYUqCLEVY1XOKcggoZoQt4eaLjBllO1r0/nlCv89uy/Py5/RYTN/xlgvleAOuSWXrPfwv9W0tG2lr2QjYjr6ERyZNxjr/a/wLheTsVoCMSQ0AAAAASUVORK5CYII="
```
### destroy
{% hint style="info" %}
widget.destroy()
{% endhint %}
This function closes the widget.
**Parameter**
* None
**Example**
* **Event Listeners**