Methods

Introduction

Functions pertaining to Map’s tile effects, object upload, and other convenient feature functions for maps are provided below.
Name
Description
putTileEffect
Function to apply a tile effect to the specified coordinates
putObject
Function to place an object on the specified coordinates
putObjectMultiple
Function to install objects at once by entering coordinates to place objects in a two-dimensional array.
putObjectWithKey
Function to place an object with a key value on the specified coordinates
playObjectAnimation
Function to execute an object’s sprite animation on the specified coordinates
playObjectAnimationWithKey
Function to execute an object's sprite animation whose key value matches
moveObject
Function to move an object from one x and y axis coordinates to another x and y axis coordinates during an X amount of time
moveObjectWithKey
Function to move an object with a key value to the specified coordinates
clearAllObjects
Function to remove all objects created using ZEP script
getTile
Function to return the enum value of the tile at the x and y coordinates of the corresponding layer
hasLocation
Function to check if the corresponding location exists in the map and return true or false
getObjectsByType
Function to return the objects that correspond to Type
getTopObjectsByType
Function to return the top objects that correspond to Type
sayObjectWithKey
Function to display a word balloon above an object with a key value

📚 API Explanation and Example

Methods at a Glance
// Applies tile effect to the specified coordinates
Map.putTileEffect(x: number, y: number, tileID: TileEffectType)
// Places the object at the specified coordinates (Reference coordinates: Left-Top)
Map.putObject(x: number, y: number, dynamicResource: ScriptDynamicResource)
// Install objects at once by entering coordinates to place objects in a two-dimensional array
Map.putObjectMultiple(tileArray: array, type: PutObjectType, dynamicResource: ScriptDynamicResource, option: object);
// Places the object with a key value at the specified coordinates (Reference coordinates: Left-Top)
Map.putObjectWithKey(x: number, y: number, dynamicResource: ScriptDynamicResource, option: JsValue)
// Executes a sprite animation of the object at the specified coordinates
// (must be preceded by putObject)
Map.playObjectAnimation(x: number, y: number, name: string, loop: number)
// Executes an object's sprite animation whose key value matches
Map.playObjectAnimationWithKey(key: string,) animName: string, repeatCount: number)
// Removes all objects created by the ZEP script
Map.clearAllObjects()
// Moves the object from the corresponding coordinates to the target coordinates for time
// (in seconds)
Map.moveObject(x: number, y: number, targetX: number, targetY: number, time: number)
// Moves the object with a key value to the target coordinates
Map.moveObjectWithKey(key: string, targetX: number, targetY: number, path:boolean = true)
// Returns the type value of the tile at the x and y coordinates of the corresponding layer
Map.getTile(layer: number, x: number, y: number)
// Checks if the corresponding location exists in the map and returns true or false
Map.hasLocation(locationName: string)
// Returns the objects that correspond to Type
Map.getObjectsByType(type: number)
// Returns the top objects that correspond to Type
Map.getTopObjectsByType(type: number)
// Displays a word balloon above an object with a key value
Map.sayObjectWithKey( key: string, message: string )

putTileEffect

Map.putTileEffect(x: number, y: number, tileID: TileEffectType)
This function applies a tile effect to the specified coordinates.
Parameters
More information on TileEffectType can be found on the Tile Effect Type Detailed Explanation page.
Name
Type
Description
x, y
Number
Object’s x and y coordinates
tileID
TileEffectType
• TileEffectType.NONE: no effect •TileEffectType.IMPASSABLE: players cannot pass • TileEffectType.SPAWN: players spawn here • TileEffectType.PORTAL: move players to a different location •TileEffectType.PRIVATE_AREA: designates a private discussion area •TileEffectType.SPOTLIGHT: designates a spotlight area • TileEffectType.EMBED: adds a web link • TileEffectType.LOCATION: designated area for ZEP script •TileEffectType.AMBIENT_SOUND: sets background sounds •TileEffectType.TILE_EMBED: embeds something from the web •TileEffectType.WEB_PORTAL: a web portal •TileEffectType.SPACE_PORTAL: a portal to another Space
Example
Set up an IMPASSABLE tile effect.
// Activates function when q is pressed
// **[App.addOnKeyDown](https://www.notion.so/Callbacks-7ac5078bab7c4f3180ae05463713581d) Explanation [(Link)](https://www.notion.so/Callbacks-7ac5078bab7c4f3180ae05463713581d)**
App.addOnKeyDown(81, function (player) {
// Sets an impassible tile effect on coordinates 5, 5
Map.putTileEffect(5, 5, TileEffectType.IMPASSABLE);
});

putObject

Map.putObject(x: number, y: number, dynamicResource: ScriptDynamicResource, option: JsValue)
This function places the object at the specified coordinates. (Reference coordinates: Left-Top) → What are Reference Coordinates?
To better understand ScriptDynamicResource, please refer to the Understanding Sprite Sheets page.
You can delete the object installed from script by sending the null value to parameter.
Map.putObject(x, y, null);
Parameters
Name
Type
Description
x, y
Number
x, y coordinates of where the tile effect will be applied
dynamicResource
ScriptDynamicResource
Variable name of the saved sprite.
loop
Number
Specify the number of times to repeat the animation
option
Object
Input { overlap: true } in the parameter field to recognize the object from App EventListener such as onObjectTouched and onObjectAttacked.
Example
Create the blueman object.
// Creates an blueman.png and save the blueman variable
let blueman = App.loadSpritesheet("blueman.png");
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
// Executes the blueman object on coordinates 5, 5
Map.putObject(5, 5, blueman, {overlap: true});
});
// Activates function when w is pressed
App.addOnKeyDown(81, function (player) {
// Delets the object on corrdinates 5, 5
Map.putObject(5, 5, null);
});

putObjectMultiple

Map.putObjectMultiple(tileArray: array, type: PutObjectType, dynamicResource: ScriptDynamicResource, option: object);
This function installs objects at once by entering coordinates to place objects in a two-dimensional array. This allows you to reduce the load when you install many objects at once.
Parameters
Name
Type
Description
tileArray
Array
Enter a two-dimensional array defining the coordinates where you want to place the objects. (Maximum length limited to 10)
type
PutObjectType
PutObjectType.STROKE
  • Once a path is created by connecting the coordinates defined in the tileArray array in order, objects are placed in all coordinates along the created path.
dynamicResource
ScriptDynamicResource
Image resources loaded using App.loadSpriteSheet
option
Object
In order for App EventListener to recognize an object, such as onObjectTouched and onObjectAttached, you should enter {overlap:true} in the parameter box.
Example
Place objects in a square or circle.
const _mark = App.loadSpritesheet("mark.png");
// Activates function when q is pressed - Place in a square
App.addOnKeyDown(81, function (player) {
const tileArray = [
[5, 5],
[9, 5],
[9, 9],
[5, 9],
[5, 5],
];
Map.putObjectMultiple(tileArray, PutObjectType.STROKE, _mark, { overlap: true });
});
// Activates function when w is pressed - Place in a circle
App.addOnKeyDown(87, function (player) {
const tileArray = [
[10, 5],
[8, 7],
[8, 10],
[10, 12],
[13, 12],
[15, 10],
[15, 7],
[13, 5],
[10, 5],
];
Map.putObjectMultiple(tileArray, PutObjectType.STROKE, _mark, { overlap: true });
});

putObjectWithKey

Map.putObjectWithKey(x: number, y: number, dynamicResource: ScriptDynamicResource, option: JsValue)
This function places an object on the specified coordinates (Reference coordinates: Left-Top)
Parameters
Name
Type
Description
x, y
Number
x, y coordinates of where the object will be placed
dynamicResource
ScriptDynamicResource
Variable name of the saved sprite.
option
Object
Sets the attributes including key values, moveSpeed, overlap, useDirAnim etc.
Example
Create the blueman object with a key value.
let blueman = App.loadSpritesheet("blueman.png");
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
Map.putObjectWithKey(18, 6, blueman, {
overlap: true,
movespeed: 100, // move speed, default: 80
key: "TestBlueMan", // key value
useDirAnim: true // Option to play animation after recognizing the direction
});
});

getObjectWithKey

Map.getObjectWithKey(key: String)
This function gets the information of the object with the corresponding key value.
Parameter
Name
Type
Description
key
String
The key value of the object to get information from
Example
Create an object with a key value and display the related data.
let blueman = App.loadSpritesheet("blueman.png");
App.onStart.Add(function() {
Map.putObjectWithKey(18, 6, blueman, {
overlap: true,
movespeed: 80,
key: "TestBlueMan", // Key value
});
});
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
let object_blueman = Map.getObjectWithKey("TestBlueMan");
for(let data in object_blueman){
App.sayToAll(`${data}: ${object_bluemane[data]}`)
}
})

playObjectAnimation

Map.playObjectAnimation(x: number, y: number, name: string)
This function activates the object animation at the corresponding coordinates.
The above function must be preceded by the Map.putObject function.
Check the Understanding Sprite Sheets page if it’s your first time hearing about sprite sheets.
Parameters
Name
Type
Description
x, y
Number
x, y coordinates of where the tile effect will be applied
name
String
let variable = App.loadSpritesheet(...) The saved variable name of the sprite must be inputted as below: → ‘#’ + variable.id
Example
Set up a dancing blueman object.
// One frame's size 48x64
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], // Animation comprised of 21st ~ 38th image
8
);
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
Map.putObject(5, 5, blueman_dance, { overlap: true });
Map.playObjectAnimation(5, 5, "#" + blueman_dance.id, -1);
});

playObjectAnimationWithKey

Map.playObjectAnimation(key: string, animName: string, repeatCount: number)
This function executes the object's sprite animation whose key value matches.
The Map.putObjectWithKey function must preceed this function.
If you are not familiar with sprite images, please refer to the Understanding Sprite Sheets page!
Parameters
Name
Type
Description
key
String
The key value of the object
animName
String
The name of the animation to play
repeatCount
Number
Specify the number of times to repeat the animation ("-1" means infinite.)
Example
Set up a dancing blueman object.
blueman_sprite
var blueman_sprite = 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],
dance: [20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37],
idle: [0],
},
8
);
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
Map.putObjectWithKey(10, 10, blueman_sprite, {
overlap: true,
movespeed: 80, // default: 80
key: "blueman",
});
// play the "dance" animation
Map.playObjectAnimationWithKey("blueman", "dance", -1);
});

moveObject

Map.moveObject(x: number, y: number, targetX: number, targetY: number, time: number)
This function moves the object from the object’s x and y coordinates to the target x and y coordinates for a certain amount of time (secs).
The above function must be preceded by the Map.putObject function.
Check the Understanding Sprite Sheets page if it’s your first time hearing about sprite sheets.
Parameters
Name
Type
Description
x, y
Number
Object’s x and y coordinates
targetX, targetY
Number
Target location’s x and y coordinates
time
Number
Time(seconds) to reach the target location.
Example
Move the blueman object.
// One frame's size 48x64
let blueman_move_right = App.loadSpritesheet(
"blueman.png",
48,
64,
[10, 11, 12, 13, 14], // Animation comprised of the 11th ~ 15th images
8
);
// Activates function when q is pressed
// **[App.addOnKeyDown](https://www.notion.so/Callbacks-7ac5078bab7c4f3180ae05463713581d) Explanation [(Link)](https://www.notion.so/Callbacks-7ac5078bab7c4f3180ae05463713581d)**
App.addOnKeyDown(81, function (player) {
Map.putObject(5, 5, blueman_right, { overlap: true });
Map.playObjectAnimation(5, 5, "#" + blueman_right, -1);
Map.moveObject(5, 5, 10, 5, 3) // At (5,5) move to (10,5) in 3 seconds
});

moveObjectWithKey

Map.moveObjectWithKey(key: string, targetX: number, targetY: number, path:boolean = true)
This function moves an object with a key value to the specified coordinates.
💡 When "path" is "true", the object doesn't move when the target location is an impassable tile or unreachable.
Parameters
Name
Type
Description
key
String
Object's key value
targetX, targetY
Number
Target location’s x and y coordinates
path
Boolean
true: cannot pass an impassable tile false: can pass an impassable tile
Example
How moveObjectWithKey works
let blueman = App.loadSpritesheet('blueman.png', 48, 64, {
left: [5, 6, 7, 8, 9], // Image that moves to the 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],
}, 10);
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
Map.putObjectWithKey(18, 6, blueman, {
overlap: true,
movespeed: 50, // default: 80
key: "TestBlueMan",
useDirAnim: true // Option to play animation after recognizing the direction
});
Map.moveObjectWithKey("TestBlueMan", 10, 10, true);
});

clearAllObjects()

Map.clearAllObjects()
This function removes all objects created by the ZEP script.
Parameter
  • None
Example
Remove all created objects.
let blueman = App.loadSpritesheet("blueman.png");
// Activates function when q is pressed
// **[App.addOnKeyDown](https://www.notion.so/Callbacks-7ac5078bab7c4f3180ae05463713581d) Explanation [(Link)](https://www.notion.so/Callbacks-7ac5078bab7c4f3180ae05463713581d)**
App.addOnKeyDown(81, function (player) {
// Creates 5 blueman objects starting from coordinates 5, 5
Map.putObject(5, 5, blueman, {overlap: true});
Map.putObject(6, 5, blueman, {overlap: true});
Map.putObject(7, 5, blueman, {overlap: true});
Map.putObject(8, 5, blueman, {overlap: true});
Map.putObject(9, 5, blueman, {overlap: true});
});
// Activates function when w is pressed
App.addOnKeyDown(87, function (player) {
// Removes all objects created using script
Map.clearAllObjects();
});

getTile

Map.getTile(layer: number, x: number, y: number)
Return the type value of the tile at the x and y coordinates of the corresponding layer. If no tile, returns "-1."
Parameters
Name
Type
Description
layer
Number
Values corresponding to the layer 0 = Floor (floor tile), 1 = WALL (wall tile), 2 = TileEffect (tile effects), 3 = Object (objects), 5 = TopObject (top objects),
x, y
Number
X and Y coordinates
Example
Check the types of all objects in the map.
const LayerType = {
FLOOR: 0,
WALL: 1,
TILE_EFFECTS: 2,
OBJECTS: 3,
TOP_OBJECTS: 5,
};
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
let layer = LayerType.OBJECTS;
for (let x = 0; x < Map.width; x++) {
for (let y = 0; y < Map.height; y++) {
let data = Map.getTile(layer, x, y);
if (data >= 0) {
App.sayToAll(`(${x},${y}) type: ${data}`);
}
}
}
});

hasLocation

Map.hasLocation(locationName: String)
This function checks if the corresponding location exists in the map and returns true or false accordingly.
Parameter
Name
Type
Description
locationName
String
Name of the location
Example
Create a function that checks if the location is installed.
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
if(Map.hasLocation("test")){
App.sayToAll("Test location is installed.")
} else {
App.sayToAll("Test location is not installed.")
}
});

getObjectsByType

Map.getObjectsByType(type: numer) : array
This function returns the objects that correspond to Type.
Parameter
Name
Type
Description
type
Number
Type value of the object
Example
Check all type of objects.
const ObjectType = {
NONE : 0,
SHOW_NOTE : 1,
SHOW_IMAGE : 2,
PASSWORD_DOOR : 3,
LINK_WEBSITE : 4,
EMBED_WEBSITE : 5,
API_CALL : 6,
REPLACE_IMAGE : 7,
NFT_GIVEAWAY : 8,
NFT_DOOR : 9,
POST_MESSAGE : 10,
SHOW_CHAT_BALLOON : 11,
FT_DOOR : 12,
POST_MESSAGE_TO_APP : 13,
DONATION_DOOR : 14,
IMPASSABLE : 15,
INTERACTION_WITH_ZEPSCRIPTS : 16,
TOKEN_DONATION_DOOR : 17,
CHANGE_OBJECT : 18,
ANIMATION : 19,
}
// Activates function when q is pressed
App.addOnKeyDown(81,function(player){
for(let key in ObjectType){
let type = ObjectType[key];
let arr = Map.getObjectsByType(type);
let index = 0;
for(let obj of arr){
for(let key in obj){
App.sayToAll(`${key}: ${obj[key]}`);
}
}
}
})

getTopObjectsByType

Map.getTopObjectsByType(type: numer) : array
This function returns the top objects that correspond to each type.
Parameter
Name
Type
Description
type
Number
Type value of the object
Example
Check all types of top objects.
const ObjectType = {
NONE : 0,
SHOW_NOTE : 1,
SHOW_IMAGE : 2,
PASSWORD_DOOR : 3,
LINK_WEBSITE : 4,
EMBED_WEBSITE : 5,
API_CALL : 6,
REPLACE_IMAGE : 7,
NFT_GIVEAWAY : 8,
NFT_DOOR : 9,
POST_MESSAGE : 10,
SHOW_CHAT_BALLOON : 11,
FT_DOOR : 12,
POST_MESSAGE_TO_APP : 13,
DONATION_DOOR : 14,
IMPASSABLE : 15,
INTERACTION_WITH_ZEPSCRIPTS : 16,
TOKEN_DONATION_DOOR : 17,
CHANGE_OBJECT : 18,
ANIMATION : 19,
}
// Activates function when q is pressed
App.addOnKeyDown(81,function(player){
for(let key in ObjectType){
let type = ObjectType[key];
let arr = Map.getTopObjectsByType(type);
let index = 0;
for(let obj of arr){
for(let key in obj){
App.sayToAll(`${key}: ${obj[key]}`);
}
}
}
})

sayObjectWithKey

Map.sayObjectWithKey( key: string, message: string )
This function displays a word balloon above an object with a key value.
Parameters
Name
Type
Description
key
String
The key value of the object
message
String
Message to display in a word balloon
Example
Display a word balloon above an object with a key value.
sayObjectWithKey.zip
29KB
Binary
const objectKey = "TestBlueMan";
// Activates function when q is pressed
App.addOnKeyDown(81, function (player) {
Map.putObjectWithKey(18, 6, blueman, {
npcProperty: { name: "BlueMan", hpColor: 0x03ff03, hp: 100, hpMax: 100 },
overlap: true,
movespeed: 100,
key: objectKey,
useDirAnim: true
});
});
// Activates function when w is pressed
App.addOnKeyDown(87, function(player){
Map.sayObjectWithKey(objectKey, `I'm BlueMan!`)
})

Appendix

Last modified 4mo ago