Methods

소개
Map에 타일 효과나 오브젝트 설치 등 맵과 관련된 편리한 기능을 제공하는 함수들 입니다.
이름
설명
putTileEffect
지정한 좌표에 타일 효과를 적용하는 함수입니다
putObject
지정한 좌표에 오브젝트를 놓는 함수입니다.
putObjectMultiple
오브젝트를 배치할 좌표들을 2차원 배열로 입력하여 한 번에 오브젝트를 설치하는 기능입니다.
putObjectWithKey
지정한 좌표에 키 값을 가진 오브젝트를 놓는 함수입니다.
getObjectWithKey
해당 키 값을 가지고 있는 오브젝트의 정보를 가져옵니다.
playObjectAnimation
해당 좌표에 있는 오브젝트의 스프라이트 애니메이션을 실행시키는 함수입니다.
playObjectAnimationWithKey
key 값이 일치하는 오브젝트의 스프라이트 애니메이션을 실행시키는 함수입니다.
moveObject
x, y 좌표에 위치한 오브젝트를 지정한 x, y 좌표로 time 초 동안 움직이는 함수입니다.
moveObjectWithKey
키 값을 가진 오브젝트를 지정한 x,y 좌표로 움직이는 함수입니다.
clearAllObjects
ZEP 스크립트로 생성된 모든 오브젝트를 제거하는 함수입니다.
getTile
해당하는 레이어의 x,y 좌표에 있는 타일의 enum 값을 반환하는 함수입니다.
hasLocation
맵에 해당 로케이션이 있는지 체크하여 true/false를 반환하는 함수입니다.
getObjectsByType
Type에 해당하는 오브젝트들을 반환하는 함수입니다.
getTopObjectsByType
Type에 해당하는 상단 오브젝트들을 반환하는 함수입니다.
sayObjectWithKey
key 값을 가진 오브젝트 위에 말풍선을 표시하는 함수입니다.

📚 API 설명 및 예제

Methods 함수 한 눈에 보기
// 지정된 좌표에 타일효과를 적용
Map.putTileEffect(x: number, y: number, tileID: TileEffectType)
// 지정된 좌표에 오브젝트를 놓음 (기준 좌표 : Left-Top)
Map.putObject(x: number, y: number, dynamicResource: ScriptDynamicResource)
// 오브젝트를 배치할 좌표들을 2차원 배열로 입력하여 한 번에 오브젝트를 설치하는 기능입니다.
Map.putObjectMultiple(tileArray: array, type: PutObjectType, dynamicResource: ScriptDynamicResource, option: object);
// 지정된 좌표에 키 값을 가진 오브젝트를 놓음 (기준 좌표 : Left-Top)
Map.putObjectWithKey(x: number, y: number, dynamicResource: ScriptDynamicResource, option: JsValue)
// 해당 좌표에 있는 오브젝트의 스프라이트 애니메이션을 실행시킴 (putObject가 선행되어야 함)
Map.playObjectAnimation(x: number, y: number, name: string, loop: number)
// key 값이 일치하는 오브젝트의 스프라이트 애니메이션을 실행시키는 함수입니다.
Map.playObjectAnimationWithKey(key: string,) animName: string, repeatCount: number)
// ZEP 스크립트로 생성된 모든 오브젝트를 제거
Map.clearAllObjects()
// 해당 좌표의 오브젝트를 타겟 좌표로 time(초) 동안 이동
Map.moveObject(x: number, y: number, targetX: number, targetY: number, time: number)
// 해당 키 값을 가진 오브젝트를 타겟 좌표로 이동
Map.moveObjectWithKey(key: string, targetX: number, targetY: number, usePath:Boolean= true, time=0 )
// 해당하는 레이어의 x, y 좌표에 있는 타일의 타입 값을 리턴
Map.getTile(layer: number, x: number, y: number)
// 맵에 해당하는 로케이션이 있는지 true/false 값으로 리턴
Map.hasLocation(locationName: string)
// Type에 해당하는 오브젝트들을 반환하는 함수입니다.
Map.getObjectsByType(type: number)
// Type에 해당하는 상단 오브젝트들을 반환하는 함수입니다.
Map.getTopObjectsByType(type: number)
// key 값을 가진 오브젝트 위에 말풍선을 표시하는 함수입니다.
Map.sayObjectWithKey( key: string, message: string )

putTileEffect

Map.putTileEffect(x: number, y: number, tileID: TileEffectType)
지정한 좌표에 타일 효과를 적용하는 함수입니다.
파라미터
TileEffectType에 대한 자세한 설명은 TileEffectType 상세 설명 페이지를 참고해주세요.
이름
타입
설명
x, y
Number
타일 효과를 설치할 x, y 좌표
tileID
TileEffectType
• TileEffectType.NONE : 없음 •TileEffectType.IMPASSABLE : 통과 불가 • TileEffectType.SPAWN : 스폰
• TileEffectType.PORTAL : 포털 • TileEffectType.PRIVATE_AREA : 프라이빗 공간 • TileEffectType.SPOTLIGHT : 스포트라이트 • TileEffectType.EMBED : 웹 링크 • TileEffectType.LOCATION : 지정 영역 • TileEffectType.AMBIENT_SOUND : 배경 음악 • TileEffectType.TILE_EMBED : 웹 임베드 • TileEffectType.WEB_PORTAL : 웹 포털 • TileEffectType.SPACE_PORTAL : 스페이스 포털
예제
IMPASSABLE 타일 효과 설치해보기
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81, function (player) {
// 5, 5 좌표에 IMPASSABLE 타일 효과 설치
Map.putTileEffect(5, 5, TileEffectType.IMPASSABLE);
});

putObject

Map.putObject(x: number, y: number, dynamicResource: ScriptDynamicResource, option: JsValue)
지정한 좌표에 오브젝트를 놓는 함수입니다. ( 기준 좌표: Left Top ) → 기준 좌표란?
ScriptDynamicResource에 대한 이해를 돕는 스프라이트시트 이해하기 문서를 확인해보세요!
null 값을 파라미터로 전달하여 스크립트로 설치한 오브젝트를 삭제 할 수 있습니다.
Map.putObject(x, y, null);
파라미터
이름
타입
설명
x, y
Number
오브젝트를 놓을 x, y 좌표
dynamicResource
ScriptDynamicResource
App.loadSpritesheet 함수로 로드한 이미지
option
Object
onObjectTouched, onObjectAttacked 와 같은 App EventListener에서 오브젝트를 인식하려면 파라미터 란에 { overlap: true } 입력해야 합니다.
예제
블루맨 오브젝트 생성해보기
// blueman.png를 객체화 하여 blueman 변수에 저장
let blueman = App.loadSpritesheet("blueman.png");
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
// 5, 5 좌표에 blueman 오브젝트 생성
Map.putObject(5, 5, blueman, {overlap: true});
});
// w 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
// 5, 5 좌표에 있는 오브젝트를 삭제
Map.putObject(5, 5, null);
});

putObjectMultiple

Map.putObjectMultiple(tileArray: array, type: PutObjectType, dynamicResource: ScriptDynamicResource, option: object);
오브젝트를 배치할 좌표들을 2차원 배열로 입력하여 한 번에 오브젝트를 설치하는 기능입니다. 이 기능을 사용하면 한 번에 많은 오브젝트를 설치할 경우 부하를 줄이는 효과를 얻을 수 있습니다.
파라미터
이름
타입
설명
tileArray
Array
오브젝트를 배치할 좌표들을 정의할 2차원 배열을 입력할 수 있습니다. (최대 길이 10 제한)
type
PutObjectType
PutObjectType.STROKE
  • tileArray 배열에 정의된 좌표들을 순서대로 연결하여 경로를 생성한 다음, 생성된 경로 상의 모든 좌표들에 오브젝트를 배치합니다.
dynamicResource
ScriptDynamicResource
App.loadSpritesheet 함수로 로드한 이미지
option
Object
onObjectTouched, onObjectAttacked 와 같은 App EventListener에서 오브젝트를 인식하려면 파라미터 란에 { overlap: true } 입력해야 합니다.
예제
사각형, 원 모양으로 오브젝트 배치하기
PutObjectType.STROKE 사각형 모양으로 배치
PutObjectType.STROKE 원 모양으로 배치
const _mark = App.loadSpritesheet("mark.png");
// Q를 누르면 동작하는 함수 - 사각형 모양으로 배치
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 });
});
// W를 누르면 동작하는 함수 - 원 모양으로 배치
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)
지정한 좌표에 키 값을 가진 오브젝트를 놓는 함수입니다. ( 기준 좌표: Left Top )
관련 문서: 오브젝트 npcProperty
파라미터
이름
타입
설명
x, y
Number
오브젝트를 놓을 x, y 좌표
dynamicResource
ScriptDynamicResource
App.loadSpritesheet 함수로 로드한 이미지
옵션 (option)
값을 입력하지 않아도 Default 값이 적용됩니다
이름
타입
설명
key
String
오브젝트의 키 값 (Default: null)
moveSpeed
Number
오브젝트의 이동속도
(Default: 80)
useDirAnim
Boolean
방향을 인지해서 애니메이션을 재생하는 옵션 (Default: false)
offsetX
Number
오브젝트 이미지의 배치 기준점의 X좌표 (Default: 0)
offsetY
Number
오브젝트 이미지의 배치 기준점의 Y좌표 (Default: 0)
npcProperty
Object
npcProperty 관련 내용은 문서를 참고해주세요. (Default: null)
예제
키 값을 가진 블루맨 오브젝트 생성해보기
let blueman = App.loadSpritesheet("blueman.png");
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
Map.putObjectWithKey(18, 6, blueman, {
overlap: true, // 충돌 이벤트 감지
movespeed: 100, // 이동속도, 기본값: 80
key: "TestBlueMan", // 키 값
useDirAnim: true, // 방향을 인지해서 애니메이션을 재생하는 옵션
offsetX: -8, // 오브젝트 이미지의 배치 기준점의 X좌표를 조정
offsetY: -32,// 오브젝트 이미지의 배치 기준점의 Y좌표를 조정
});
});
// w 키를 누르면 동작하는 함수
App.addOnKeyDown(87, function (player) {
// 오브젝트 삭제
Map.putObjectWithKey(18, 6, null, {
key: "TestBlueMan", // 키 값
});
});

getObjectWithKey

Map.getObjectWithKey(key: String)
해당 키 값을 가지고 있는 오브젝트의 정보를 가져옵니다.
파라미터
이름
타입
설명
key
String
정보를 가져올 오브젝트의 key 값
예제
키 값을 가진 오브젝트를 생성하고 관련 데이터를 채팅창에 출력해보기.
let blueman = App.loadSpritesheet("blueman.png");
App.onStart.Add(function() {
Map.putObjectWithKey(18, 6, blueman, {
overlap: true,
movespeed: 80,
key: "TestBlueMan", // 키 값
});
});
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
let object_blueman = Map.getObjectWithKey("TestBlueMan");
for(let data in object_blueman){
App.sayToAll(`${data}: ${object_blueman[data]}`)
}
})

playObjectAnimation

Map.playObjectAnimation(x: number, y: number, name: string, loop: number)
해당 좌표에 있는 오브젝트의 스프라이트 애니메이션을 실행시키는 함수입니다.
해당 좌표 지점에 Map.putObject 함수가 선행되어야합니다.
스프라이트 이미지를 처음 들어보신다면 스프라이트시트 이해하기 문서를 확인해보세요!
파라미터
이름
타입
설명
x, y
Number
타일 효과를 적용할 x, y 좌표
name
String
let 변수 = App.loadSpritesheet(...) 스프라이트를 저장한 변수 이름을 다음과 같이 입력해야 합니다. → ‘#’ + 변수.id
loop
number
애니메이션 반복 횟수 ( -1: 계속반복)
예제
춤추는 블루맨 오브젝트 설치해보기
// 한 프레임의 사이즈 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], // 21번째 ~ 38번째 이미지로 애니메이션을 구성
8
);
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
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)
key 값이 일치하는 오브젝트의 스프라이트 애니메이션을 실행시키는 함수입니다.
Map.putObjectWithKey함수가 선행되어야합니다.
스프라이트 이미지를 처음 들어보신다면 스프라이트시트 이해하기 문서를 확인해보세요!
파라미터
이름
타입
설명
key
String
오브젝트의 키값
animName
String
플레이할 애니메이션의 이름
repeatCount
Number
애니메이션 반복 횟수 ( -1 입력시 무한반복 )
예제
춤추는 블루맨 오브젝트 설치해보기
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
);
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
Map.putObjectWithKey(10, 10, blueman_sprite, {
overlap: true,
movespeed: 80, // default: 80
key: "blueman",
});
// "dance" 애니메이션 재생
Map.playObjectAnimationWithKey("blueman", "dance", -1);
});

moveObject

Map.moveObject(x: number, y: number, targetX: number, targetY: number, time: number)
x, y 좌표에 위치한 오브젝트를 targetX, targetY로 time 초 동안 움직이는 함수입니다.
해당 좌표 지점에 Map.putObject 함수가 선행되어야합니다.
스프라이트 이미지를 처음 들어보신다면 스프라이트시트 이해하기 문서를 확인해보세요!
파라미터
이름
타입
설명
x, y
Number
오브젝트가 위치한 x, y 좌표
targetX, targetY
Number
목적지 x, y 좌표
time
Number
목적지까지 걸리는 시간(초)
예제
블루맨 이동시켜보기
// 한 프레임의 사이즈 48x64
let blueman_right = App.loadSpritesheet(
"blueman.png",
48,
64,
[10, 11, 12, 13, 14], // 11 ~ 15번째 이미지로 애니메이션 구성
8
);
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
Map.putObject(5, 5, blueman_right, { overlap: true });
Map.playObjectAnimation(5, 5, "#" + blueman_right.id, -1);
Map.moveObject(5, 5, 10, 5, 3) // (5,5)에서 (10,5)로 3초 동안 이동
});

moveObjectWithKey

Map.moveObjectWithKey(key: string, targetX: number, targetY: number, usePath:boolean = true)
key 값을 가진 오브젝트를 targetX, targetY로 움직이는 함수입니다.
💡 path 파라미터가 true인 경우, 목표 지점이 impassable 타일이거나 도달 할 수 없는 좌표이면 오브젝트가 움직이지 않습니다.
파라미터
이름
타입
설명
key
String
오브젝트의 key 값
targetX, targetY
Number
목적지 x, y 좌표
usePath
Boolean
true일 경우 Impassable 타일을 통과하지 못합니다. false일 경우 Impassable 타일을 무시하고 지나갑니다.
예제
moveObejctWithKey 동작 방식
// 한 프레임의 사이즈 48x64
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],
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);
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown 설명(링크)
App.addOnKeyDown(81, function (player) {
Map.putObjectWithKey(18, 6, blueman, {
overlap: true,
movespeed: 50, // default: 80
key: "TestBlueMan",
useDirAnim: true // 방향을 인지해서 애니메이션 재생하는 옵션
offsetX: -8,
offsetY: -32,
});
Map.moveObjectWithKey("TestBlueMan", 10, 10, true);
});

clearAllObjects()

Map.clearAllObjects()
ZEP 스크립트로 생성된 모든 오브젝트를 제거하는 함수입니다.
파라미터
  • 없음
예제
생성된 모든 오브젝트 삭제하기
let blueman = App.loadSpritesheet("blueman.png");
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81, function (player) {
// 5, 5 좌표부터 blueman 오브젝트 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});
});
// w 키를 누르면 동작하는 함수
App.addOnKeyDown(87, function (player) {
// 스크립트로 생성된 모든 오브젝트 제거
Map.clearAllObjects();
});

getTile

Map.getTile(layer: number, x: number, y: number)
해당하는 레이어의 x, y 좌표에 있는 타일의 타입 값을 리턴, 타일이 없으면 -1을 리턴합니다.
파라미터
이름
타입
설명
layer
Number
레이어에 해당하는 값 0 = Floor (바닥타일), 1 = WALL (벽타일), 2 = TileEffect (타일효과), 3 = Object (오브젝트), 5 = TopObject (상단오브젝트),
x, y
Number
x, y 좌표
예제
맵에 있는 모든 오브젝트의 타입을 조회하기
const LayerType = {
FLOOR: 0,
WALL: 1,
TILE_EFFECTS: 2,
OBJECTS: 3,
TOP_OBJECTS: 5,
};
// q 키를 누르면 동작하는 함수
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): Boolean
맵에 해당 로케이션이 있는지 체크하여 true/false 값을 리턴합니다.
파라미터
이름
타입
설명
locationName
String
로케이션 이름
예제
로케이션이 설치되어있는지 체크하는 키 함수 만들어보기
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
if(Map.hasLocation("test")){
App.sayToAll("test 로케이션이 설치되어있습니다.")
} else {
App.sayToAll("test 로케이션이 설치되어있지 않습니다.")
}
});

getObjectsByType

Map.getObjectsByType(type: numer) : array
Type에 해당하는 오브젝트들을 리턴하는 함수입니다.
파라미터
이름
타입
설명
type
Number
오브젝트의 type 값
예제
모든 타입의 오브젝트 조회하기
const ObjectEffectType = {
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,
STAMP = 16,
TOKEN_DONATION_DOOR = 17,
CHANGE_OBJECT = 18,
ANIMATION = 19,
NFT_DOOR_MOVE = 20,
INTERACTION_WITH_ZEPSCRIPTS = 21,
MULTIPLE_CHOICE = 22,
}
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81,function(player){
for(let key in ObjectEffectType){
let type = ObjectEffectType[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
Type에 해당하는 상단오브젝트들을 리턴하는 함수입니다.
파라미터
이름
타입
설명
type
Number
오브젝트의 type 값
예제
모든 타입의 상단오브젝트 조회하기
const ObjectEffectType = {
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,
STAMP : 16,
TOKEN_DONATION_DOOR : 17,
CHANGE_OBJECT : 18,
ANIMATION : 19,
NFT_DOOR_MOVE : 20,
INTERACTION_WITH_ZEPSCRIPTS : 21,
MULTIPLE_CHOICE : 22,
}
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81,function(player){
for(let key in ObjectEffectType){
let type = ObjectEffectType[key];
let arr = Map.getTopObjectsByType(type);
for(let obj of arr){
for(let key in obj){
App.sayToAll(`${key}: ${obj[key]}`);
}
}
}
})
상단 오브젝트 조회

sayObjectWithKey

Map.sayObjectWithKey( key: string, message: string )
key 값을 가진 오브젝트 위에 말풍선을 표시하는 함수입니다.
파라미터
이름
타입
설명
key
String
대상오브젝트의 키 값
message
String