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.

29KB

sayObjectWithKey.zip

archive

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

Understanding Sprite Sheets

TileEffectType Detailed Explanation

What are Reference Coordinates?