Methods

소개

Map에 타일 효과나 오브젝트 설치 등 맵과 관련된 편리한 기능을 제공하는 함수들 입니다.

📚 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 상세 설명 페이지를 참고해주세요.

예제

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);

파라미터

예제

블루맨 오브젝트 생성해보기

// 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차원 배열로 입력하여 한 번에 오브젝트를 설치하는 기능입니다. 이 기능을 사용하면 한 번에 많은 오브젝트를 설치할 경우 부하를 줄이는 효과를 얻을 수 있습니다.

파라미터

예제

사각형, 원 모양으로 오브젝트 배치하기

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 )

dynamicResource 파라미터에 null 입력시 해당 좌표의 오브젝트를 삭제할 수 있습니다.

관련 문서: 오브젝트 npcProperty

파라미터

옵션 (option)

값을 입력하지 않아도 Default 값이 적용됩니다

예제

키 값을 가진 블루맨 오브젝트 생성해보기

let blueman = App.loadSpritesheet("blueman.png");
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
	Map.putObjectWithKey(18, 6, blueman, {
		type:21, // zep-script 상호작용 오브젝트
		overlap: true, // 충돌 이벤트 감지
		movespeed: 100, // 이동속도, 기본값: 80
		key: "TestBlueMan", // 키 값
		impassalbe:true, // 통과 불가 오브젝트 설정
		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)

해당 키 값을 가지고 있는 오브젝트의 정보를 가져옵니다.

파라미터

예제

키 값을 가진 오브젝트를 생성하고 관련 데이터를 채팅창에 출력해보기.

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 함수가 선행되어야합니다.

스프라이트 이미지를 처음 들어보신다면 스프라이트시트 이해하기 문서를 확인해보세요!

파라미터

예제

춤추는 블루맨 오브젝트 설치해보기

// 한 프레임의 사이즈 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함수가 선행되어야합니다.

스프라이트 이미지를 처음 들어보신다면 스프라이트시트 이해하기 문서를 확인해보세요!

파라미터

예제

춤추는 블루맨 오브젝트 설치해보기

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 함수가 선행되어야합니다.

스프라이트 이미지를 처음 들어보신다면 스프라이트시트 이해하기 문서를 확인해보세요!

파라미터

예제

블루맨 이동시켜보기

// 한 프레임의 사이즈 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 타일이거나 도달 할 수 없는 좌표이면 오브젝트가 움직이지 않습니다.

파라미터

예제

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을 리턴합니다.

파라미터

예제

맵에 있는 모든 오브젝트의 타입을 조회하기

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}`);
			}
		}
	}
});

getLocation

Map.getLocation(locationName: string)

파라미터로 전달한 로케이션이 존재하는 경우, 로케이션 설치 좌표를 리턴합니다.

파라미터

예제

맵 에디터에서 타일효과 > 지정 영역 선택 후 영역 이름을 "testLocation" 으로 지정해 맵에 설치한 후 예제 코드를 실행해보세요.

// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
    const targetLocationName = "testLocation";
    const targetLocation = Map.getLocation(targetLocationName);
    
    if(targetLocation) {
        player.sendMessage(`targetLocation placed at (${targetLocation.x}, ${targetLocation.y})`)
    } else {
        player.sendMessage(`${targetLocationName} is not exist!`)
    }
});

getLocationRandom

Map.getLocationRandom(locationName: string)

파라미터로 전달한 로케이션이 2개이상 존재하는 경우, 무작위로 선택하여 해당 로케이션의 설치 좌표를 리턴합니다.

파라미터

예제

맵 에디터에서 타일효과 > 지정 영역 선택 후 영역 이름을 "testLocation" 으로 지정해 맵에 여러개 설치한 후 예제 코드를 실행해보세요.

// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
    const targetLocationName = "testLocation";
    const targetLocation = Map.getLocationRandom(targetLocationName);
    
    if(targetLocation) {
        player.sendMessage(`targetLocation placed at (${targetLocation.x}, ${targetLocation.y})`)
    } else {
        player.sendMessage(`${targetLocationName} is not exist!`)
    }
});

getLocationList

Map.getLocationList(locationName: string): Array

파라미터로 전달된 로케이션 이름과 일치하는 모든 로케이션의 정보를 배열 형태로 반환합니다. 각각의 로케이션 정보는 로케이션 설치 좌표(x, y), 크기(width, height), 그리고 라벨 값(label)을 포함하고 있습니다.

파라미터

예제

맵 에디터에서 타일효과 > 지정 영역 선택 후 영역 이름을 "testLocation" 으로 지정해 맵에 여러개 설치한 후 예제 코드를 실행해보세요.

// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
	const targetLocationName = "testLocation";
	const targetLocationList = Map.getLocationList(targetLocationName);

	if (targetLocationList) {
		for (const location of targetLocationList) {
			player.sendMessage(`${JSON.stringify(location)}`);
		}
	} else {
		player.sendMessage(`${targetLocationName} is not exist!`);
	}
});

hasLocation

Map.hasLocation(locationName: String): Boolean

맵에 해당 로케이션이 있는지 체크하여 true/false 값을 리턴합니다.

파라미터

예제

로케이션이 설치되어있는지 체크하는 키 함수 만들어보기

// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
	if(Map.hasLocation("test")){
		App.sayToAll("test 로케이션이 설치되어있습니다.")
	} else {
		App.sayToAll("test 로케이션이 설치되어있지 않습니다.")
	}
});

getObjectsByType

Map.getObjectsByType(type: numer) : Array

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에 해당하는 상단오브젝트들을 리턴하는 함수입니다.

파라미터

예제

모든 타입의 상단오브젝트 조회하기

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 값을 가진 오브젝트 위에 말풍선 표시하기

const objectKey = "TestBlueMan";
// Q를 누르면 동작하는 함수
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
	});
});

// W를 누르면 동작하는 함수
App.addOnKeyDown(87, function(player){
    Map.sayObjectWithKey(objectKey, `I'm BlueMan!`)
})

부록

스프라이트시트 이해하기

기준좌표란?

---