Methods
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 |
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 )
Map.putTileEffect(x: number, y: number, tileID: TileEffectType)
This function applies a tile effect to the specified coordinates.
Parameters
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);
});
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?
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);
});
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
|
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 });
});
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
});
});
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]}`)
}
})
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.
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);
});
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.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);
});
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.
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
});
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);
});
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();
});
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}`);
}
}
}
});
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.")
}
});
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]}`);
}
}
}
})

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]}`);
}
}
}
})
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!`)
})
Last modified 4mo ago