# Methods

소개

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

<table><thead><tr><th width="270">이름</th><th>설명</th></tr></thead><tbody><tr><td>putTileEffect</td><td>지정한 좌표에 타일 효과를 적용하는 함수입니다</td></tr><tr><td>putObject</td><td>지정한 좌표에 오브젝트를 놓는 함수입니다.</td></tr><tr><td>putObjectMultiple</td><td>오브젝트를 배치할 좌표들을 2차원 배열로 입력하여 한 번에 오브젝트를 설치하는 기능입니다.</td></tr><tr><td>putObjectWithKey</td><td>지정한 좌표에 키 값을 가진 오브젝트를 놓는 함수입니다.</td></tr><tr><td>getObjectWithKey</td><td>해당 키 값을 가지고 있는 오브젝트의 정보를 가져옵니다.</td></tr><tr><td>playObjectAnimation</td><td>해당 좌표에 있는 오브젝트의 스프라이트 애니메이션을 실행시키는 함수입니다.</td></tr><tr><td>playObjectAnimationWithKey</td><td>key 값이 일치하는 오브젝트의 스프라이트 애니메이션을 실행시키는 함수입니다.</td></tr><tr><td>moveObject</td><td>x, y 좌표에 위치한 오브젝트를 지정한 x, y 좌표로 time 초 동안 움직이는 함수입니다.</td></tr><tr><td>moveObjectWithKey</td><td>키 값을 가진 오브젝트를 지정한 x,y 좌표로 움직이는 함수입니다.</td></tr><tr><td>clearAllObjects</td><td>ZEP 스크립트로 생성된 모든 오브젝트를 제거하는 함수입니다.</td></tr><tr><td>getTile</td><td>해당하는 레이어의 x,y 좌표에 있는 타일의 enum 값을 반환하는 함수입니다.</td></tr><tr><td>hasLocation</td><td>맵에 해당 로케이션이 있는지 체크하여 true/false를 반환하는 함수입니다.</td></tr><tr><td>getObjectsByType</td><td>Type에 해당하는 오브젝트들을 반환하는 함수입니다.</td></tr><tr><td>getTopObjectsByType</td><td>Type에 해당하는 상단 오브젝트들을 반환하는 함수입니다.</td></tr><tr><td>sayObjectWithKey</td><td>key 값을 가진 오브젝트 위에 말풍선을 표시하는 함수입니다.</td></tr><tr><td>getLocation</td><td>파라미터로 전달한 로케이션이 존재하는 경우, 로케이션 설치 좌표를 리턴합니다.</td></tr><tr><td>getLocationRandom</td><td>파라미터로 전달한 로케이션이 2개이상  존재하는 경우, 무작위로 선택하여 해당 로케이션의 설치 좌표를 리턴합니다.</td></tr><tr><td>getLocationList</td><td>파라미터로 전달된 로케이션 이름과 일치하는 모든 로케이션의 정보를 배열 형태로 반환합니다</td></tr></tbody></table>

## 📚 API 설명 및 예제

<mark style="background-color:yellow;">**Methods 함수 한 눈에 보기**</mark>

```javascript
// 지정된 좌표에 타일효과를 적용
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

{% hint style="info" %}
Map.putTileEffect(x: number, y: number, tileID: TileEffectType)
{% endhint %}

지정한 좌표에 타일 효과를 적용하는 함수입니다.

**파라미터**

TileEffectType에 대한 자세한 설명은 [<mark style="color:purple;">TileEffectType 상세 설명</mark>](https://docs-kr.zep.us/creator/reference/tileeffecttype) 페이지를 참고해주세요.

<table><thead><tr><th width="139.33333333333331">이름</th><th width="159">타입</th><th>설명</th></tr></thead><tbody><tr><td>x, y</td><td>Number</td><td>타일 효과를 설치할 x, y 좌표</td></tr><tr><td>tileID</td><td>TileEffectType</td><td><p>• TileEffectType.NONE : 없음<br>•TileEffectType.IMPASSABLE : 통과 불가<br>• TileEffectType.SPAWN : 스폰</p><p>• TileEffectType.PORTAL : 포털<br>• TileEffectType.PRIVATE_AREA : 프라이빗 공간<br>• TileEffectType.SPOTLIGHT : 스포트라이트<br>• TileEffectType.EMBED : 웹 링크<br>• TileEffectType.LOCATION : 지정 영역<br>• TileEffectType.AMBIENT_SOUND : 배경 음악<br>• TileEffectType.TILE_EMBED : 웹 임베드<br>• TileEffectType.WEB_PORTAL : 웹 포털<br>• TileEffectType.SPACE_PORTAL : 스페이스 포털</p></td></tr></tbody></table>

**예제**

**IMPASSABLE** 타일 효과 설치해보기

```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81, function (player) {
	// 5, 5 좌표에 IMPASSABLE 타일 효과 설치
	Map.putTileEffect(5, 5, TileEffectType.IMPASSABLE);
});
```

####

### putObject

{% hint style="info" %}
Map.putObject(x: number, y: number, dynamicResource: ScriptDynamicResource, option: JsValue)
{% endhint %}

지정한 좌표에 오브젝트를 놓는 함수입니다. ( 기준 좌표: Left Top ) → [<mark style="color:purple;">**기준 좌표란?**</mark>](https://docs-kr.zep.us/creator/reference/coordinate)

ScriptDynamicResource에 대한 이해를 돕는 [<mark style="color:purple;">스프라이트시트 이해하기</mark>](https://docs-kr.zep.us/creator/reference/spritesheet) 문서를 확인해보세요!&#x20;

> null 값을 파라미터로 전달하여 스크립트로 설치한 오브젝트를 삭제 할 수 있습니다.
>
> ```
> Map.putObject(x, y, null);
> ```

**파라미터**

<table><thead><tr><th width="183.33333333333331">이름</th><th width="216">타입</th><th>설명</th></tr></thead><tbody><tr><td>x, y</td><td>Number</td><td>오브젝트를 놓을 x, y 좌표</td></tr><tr><td>dynamicResource</td><td>ScriptDynamicResource</td><td>App.loadSpritesheet 함수로 로드한 이미지</td></tr><tr><td>option</td><td>Object</td><td>onObjectTouched, onObjectAttacked 와 같은 App EventListener에서 오브젝트를 인식하려면 파라미터 란에 { overlap: true } 입력해야 합니다.</td></tr></tbody></table>

**예제**

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FEsF45f1QAbO4p550RiUc%2Fblueman.png?alt=media&#x26;token=8744b3cb-57be-4865-b7b2-1e56dc19330d" alt=""><figcaption></figcaption></figure></div>

```jsx
// 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

{% hint style="info" %}
Map.putObjectMultiple(tileArray: array, type: PutObjectType, dynamicResource: ScriptDynamicResource, option: object);
{% endhint %}

오브젝트를 배치할 좌표들을 2차원 배열로 입력하여 한 번에 오브젝트를 설치하는 기능입니다. 이 기능을 사용하면 한 번에 많은 오브젝트를 설치할 경우 부하를 줄이는 효과를 얻을 수 있습니다.

**파라미터**

<table><thead><tr><th width="121.33333333333331">이름</th><th width="152">타입</th><th>설명</th></tr></thead><tbody><tr><td>tileArray</td><td>Array</td><td>오브젝트를 배치할 좌표들을 정의할 2차원 배열을 입력할 수 있습니다. (최대 길이 10 제한)</td></tr><tr><td>type</td><td>PutObjectType</td><td><p><code>PutObjectType.STROKE</code></p><ul><li>tileArray 배열에 정의된 좌표들을 순서대로 연결하여 경로를 생성한 다음, 생성된 경로 상의 모든 좌표들에 오브젝트를 배치합니다.</li></ul></td></tr><tr><td>dynamicResource</td><td>ScriptDynamicResource</td><td>App.loadSpritesheet 함수로 로드한 이미지</td></tr><tr><td>option</td><td>Object</td><td>onObjectTouched, onObjectAttacked 와 같은 App EventListener에서 오브젝트를 인식하려면 파라미터 란에 { overlap: true } 입력해야 합니다.</td></tr></tbody></table>

**예제**

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

![](https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2F7DZTGj9cSPCP5XnhsOsg%2Fwarning.png?alt=media\&token=42ae9f1f-b731-4855-bf25-b755df3f4cce)

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FJQ58Tw2ohbYg1a6IXUFt%2Fimage.png?alt=media&#x26;token=336482aa-1b51-48e9-90bd-5e30a1e2caf2" alt=""><figcaption><p><code>PutObjectType.STROKE</code> <br>사각형 모양으로 배치</p></figcaption></figure> <figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2F1b22vZJONULREgAA56zM%2Fimage.png?alt=media&#x26;token=de43a496-d160-4e79-8a3a-b5ce0d00cb38" alt=""><figcaption><p><code>PutObjectType.STROKE</code> <br>원 모양으로 배치</p></figcaption></figure></div>

```
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

{% hint style="info" %}
Map.putObjectWithKey(x: number, y: number, dynamicResource: ScriptDynamicResource, option: JsValue)
{% endhint %}

지정한 좌표에 키 값을 가진 오브젝트를 놓는 함수입니다. ( 기준 좌표: Left Top )

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

**관련 문서:** [npcproperty](https://docs-kr.zep.us/creator/reference/npcproperty "mention")

**파라미터**

<table><thead><tr><th width="183.33333333333331">이름</th><th width="214">타입</th><th>설명</th></tr></thead><tbody><tr><td>x, y</td><td>Number</td><td>오브젝트를 놓을 x, y 좌표</td></tr><tr><td>dynamicResource</td><td>ScriptDynamicResource</td><td>App.loadSpritesheet 함수로 로드한 이미지</td></tr></tbody></table>

**옵션 (option)**

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

<table><thead><tr><th width="183.33333333333331">이름</th><th width="154">타입</th><th>설명</th></tr></thead><tbody><tr><td>key</td><td>String</td><td>오브젝트의 키 값<br><strong>(Default: null)</strong></td></tr><tr><td>moveSpeed</td><td>Number</td><td><p>오브젝트의 이동속도</p><p><strong>(Default: 80)</strong></p></td></tr><tr><td>useDirAnim</td><td>Boolean</td><td>방향을 인지해서 애니메이션을 재생하는 옵션<br><strong>(Default: false)</strong></td></tr><tr><td>impassable</td><td>Boolean</td><td>오브젝트 통과불가 옵션<br><strong>(Default: false)</strong></td></tr><tr><td>offsetX</td><td>Number</td><td>오브젝트 이미지의 배치 기준점의 X좌표<br><strong>(Default: 0)</strong></td></tr><tr><td>offsetY</td><td>Number</td><td>오브젝트 이미지의 배치 기준점의 Y좌표<br><strong>(Default: 0)</strong></td></tr><tr><td>npcProperty</td><td>Object</td><td>npcProperty 관련 내용은 <a href="../../../creator/reference/npcproperty"><strong>문서</strong></a>를 참고해주세요.<br><strong>(Default: null)</strong></td></tr><tr><td>topObject</td><td>Boolean</td><td>true 로 설정하면 오브젝트가 상단오브젝트로  설치됩니다.<br><strong>(Default: false)</strong></td></tr></tbody></table>

**예제**

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FjWShei1tdfQfaQWGAZJF%2Fblueman.png?alt=media&#x26;token=802a123f-07c0-4a2a-8291-1d997caaac9e" alt=""><figcaption></figcaption></figure></div>

```bash
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

{% hint style="info" %}
Map.getObjectWithKey(key: String)
{% endhint %}

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

**파라미터**

<table><thead><tr><th width="108.33333333333331">이름</th><th width="160">타입</th><th>설명</th></tr></thead><tbody><tr><td>key</td><td>String</td><td>정보를 가져올 오브젝트의 key 값</td></tr></tbody></table>

**예제**

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FZzI4nWf0PeiPilsyPZuL%2FUntitled.png?alt=media&#x26;token=655894f6-06a4-4e0c-9d28-f87b3fa07cba" alt=""><figcaption></figcaption></figure></div>

```bash
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

{% hint style="info" %}
Map.playObjectAnimation(x: number, y: number, name: string, loop: number)
{% endhint %}

해당 좌표에 있는 오브젝트의 스프라이트 애니메이션을 실행시키는 함수입니다.

해당 좌표 지점에[ <mark style="color:purple;">Map.putObject</mark>](#putobject) 함수가 선행되어야합니다.

스프라이트 이미지를 처음 들어보신다면 [<mark style="color:purple;">스프라이트시트 이해하기</mark>](https://docs-kr.zep.us/creator/reference/spritesheet) 문서를 확인해보세요!

**파라미터**

<table><thead><tr><th width="117.33333333333326">이름</th><th width="137">타입</th><th>설명</th></tr></thead><tbody><tr><td>x, y</td><td>Number</td><td>타일 효과를 적용할 x, y 좌표</td></tr><tr><td>name</td><td>String</td><td><mark style="color:purple;background-color:yellow;">let 변수 = App.loadSpritesheet(...)</mark><br>스프라이트를 저장한 변수 이름을 다음과 같이 입력해야 합니다.<br>→ ‘#’ + 변수.id</td></tr><tr><td>loop</td><td>number</td><td>애니메이션 반복 횟수 (  -1: 계속반복)</td></tr></tbody></table>

**예제**

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FVOxdlRD24vPOOFd95Zuc%2Fblueman%201.png?alt=media&#x26;token=f84a5709-f61c-4924-92ef-70d4c98dd734" alt=""><figcaption></figcaption></figure> <figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2Fg5UZjUAiXu97SadtX3mK%2FGIF_2022-07-18_%EC%98%A4%ED%9B%84_2-38-22.gif?alt=media&#x26;token=0b75a650-b4a8-4159-999c-32238b03d1ce" alt=""><figcaption></figcaption></figure></div>

```jsx
// 한 프레임의 사이즈 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

{% hint style="info" %}
Map.playObjectAnimation(key: string, animName: string, repeatCount: number)
{% endhint %}

key 값이 일치하는 오브젝트의 스프라이트 애니메이션을 실행시키는 함수입니다.

<mark style="color:purple;">`Map.putObjectWithKey`</mark>함수가 선행되어야합니다.

스프라이트 이미지를 처음 들어보신다면 [<mark style="color:purple;">스프라이트시트 이해하기</mark>](https://docs-kr.zep.us/creator/reference/spritesheet) 문서를 확인해보세요!

**파라미터**

<table><thead><tr><th width="153.33333333333326">이름</th><th width="137">타입</th><th>설명</th></tr></thead><tbody><tr><td>key</td><td>String</td><td>오브젝트의 키값</td></tr><tr><td>animName</td><td>String</td><td>플레이할 애니메이션의 이름</td></tr><tr><td>repeatCount</td><td>Number</td><td>애니메이션 반복 횟수 ( -1 입력시 무한반복  )</td></tr></tbody></table>

**예제**

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FVOxdlRD24vPOOFd95Zuc%2Fblueman%201.png?alt=media&#x26;token=f84a5709-f61c-4924-92ef-70d4c98dd734" alt=""><figcaption></figcaption></figure> <figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2Fg5UZjUAiXu97SadtX3mK%2FGIF_2022-07-18_%EC%98%A4%ED%9B%84_2-38-22.gif?alt=media&#x26;token=0b75a650-b4a8-4159-999c-32238b03d1ce" alt=""><figcaption></figcaption></figure></div>

```jsx
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

{% hint style="info" %}
Map.moveObject(x: number, y: number, targetX: number, targetY: number, time: number)
{% endhint %}

x, y 좌표에 위치한 오브젝트를 targetX, targetY로 time 초 동안 움직이는 함수입니다.

해당 좌표 지점에 [<mark style="color:purple;">Map.putObject</mark>](https://app.gitbook.com/o/-MkvEtFn2kFBYSN4_5rX/s/iW553XSGeKCAPpImxXi3/~/changes/bRylDKw8UxLaVWLvuhVV/creator/zep-script-v2_kr/api/scriptmap/methods) 함수가 선행되어야합니다.

스프라이트 이미지를 처음 들어보신다면 [<mark style="color:purple;">스프라이트시트 이해하기</mark>](https://docs-kr.zep.us/creator/reference/spritesheet) 문서를 확인해보세요!

**파라미터**

<table><thead><tr><th width="189.33333333333331">이름</th><th width="160">타입</th><th>설명</th></tr></thead><tbody><tr><td>x, y</td><td>Number</td><td>오브젝트가 위치한 x, y 좌표</td></tr><tr><td>targetX, targetY</td><td>Number</td><td>목적지 x, y 좌표</td></tr><tr><td>time</td><td>Number</td><td>목적지까지 걸리는 시간(초)</td></tr></tbody></table>

**예제**

블루맨 이동시켜보기

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FFBxHCHGSyMANujnqcCDe%2Fblueman%201.png?alt=media&#x26;token=e1778c35-b1ab-4e55-b6f4-c5abafaa07e9" alt=""><figcaption></figcaption></figure> <figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FuDnqeoKnzGFU681VKL0d%2FmoveObject.gif?alt=media&#x26;token=f75f250b-9da4-4b58-9dc3-141b33058c71" alt=""><figcaption></figcaption></figure></div>

```jsx
// 한 프레임의 사이즈 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

{% hint style="info" %}
Map.moveObjectWithKey(key: string, targetX: number, targetY: number, usePath:boolean = true)
{% endhint %}

key 값을 가진 오브젝트를 targetX, targetY로 움직이는 함수입니다.

💡 path 파라미터가 true인 경우, 목표 지점이 impassable 타일이거나 도달 할 수 없는 좌표이면 오브젝트가 움직이지 않습니다.

**파라미터**

<table><thead><tr><th width="171.33333333333331">이름</th><th width="134">타입</th><th>설명</th></tr></thead><tbody><tr><td>key</td><td>String</td><td>오브젝트의 key 값</td></tr><tr><td>targetX, targetY</td><td>Number</td><td>목적지 x, y 좌표</td></tr><tr><td>usePath</td><td>Boolean</td><td>true일 경우 Impassable 타일을 통과하지 못합니다.<br>false일 경우 Impassable 타일을 무시하고 지나갑니다.</td></tr></tbody></table>

**예제**

moveObejctWithKey 동작 방식

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2F9DH0Ku6RiK5ZOeeI8UzG%2FGIF%202022-11-25%20%EC%98%A4%EC%A0%84%2011-50-28.gif?alt=media&#x26;token=e30b2cae-0e5b-476c-8408-3b9cbb572644" alt=""><figcaption></figcaption></figure></div>

```jsx
// 한 프레임의 사이즈 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()

{% hint style="info" %}
Map.clearAllObjects()
{% endhint %}

ZEP 스크립트로 생성된 모든 오브젝트를 제거하는 함수입니다.

**파라미터**

* 없음

**예제**

생성된 모든 오브젝트 삭제하기

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FcqPIHzqT5kDiidMH3cba%2Fblueman.png?alt=media&#x26;token=81c342e1-e175-4995-bc7c-8a1b0ebf340d" alt=""><figcaption></figcaption></figure></div>

```jsx
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

{% hint style="info" %}
Map.getTile(layer: number, x: number, y: number)
{% endhint %}

해당하는 레이어의 x, y 좌표에 있는 타일의 타입 값을 리턴, 타일이 없으면 -1을 리턴합니다.

**파라미터**

<table><thead><tr><th width="134">이름</th><th width="123.33333333333331">타입</th><th>설명</th></tr></thead><tbody><tr><td>layer</td><td>Number</td><td>레이어에 해당하는 값<br>0 = Floor (바닥타일),<br>1 = WALL (벽타일),<br>2 = TileEffect (타일효과),<br>3 = Object (오브젝트),<br>5 = TopObject (상단오브젝트),</td></tr><tr><td>x, y</td><td>Number</td><td>x, y 좌표</td></tr></tbody></table>

**예제**

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

```jsx
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

{% hint style="info" %}
Map.getLocation(locationName: string)
{% endhint %}

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

**파라미터**

<table><thead><tr><th width="166">이름</th><th width="123.33333333333331">타입</th><th>설명</th></tr></thead><tbody><tr><td>locationName</td><td>String</td><td>로케이션 이름</td></tr></tbody></table>

**예제**

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FiNFdSzIwKDrlADluAxS5%2Fimage.png?alt=media&#x26;token=e4531f0d-68f4-4ba4-8022-bf3df09aff1a" alt=""><figcaption></figcaption></figure></div>

```jsx
// 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

{% hint style="info" %}
Map.getLocationRandom(locationName: string)
{% endhint %}

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

**파라미터**

<table><thead><tr><th width="242">이름</th><th width="123.33333333333331">타입</th><th>설명</th></tr></thead><tbody><tr><td>locationName</td><td>String</td><td>로케이션 이름</td></tr></tbody></table>

**예제**

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FiNFdSzIwKDrlADluAxS5%2Fimage.png?alt=media&#x26;token=e4531f0d-68f4-4ba4-8022-bf3df09aff1a" alt=""><figcaption></figcaption></figure></div>

```jsx
// 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

{% hint style="info" %}
Map.getLocationList(locationName: string): Array
{% endhint %}

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

**파라미터**

<table><thead><tr><th width="242">이름</th><th width="123.33333333333331">타입</th><th>설명</th></tr></thead><tbody><tr><td>locationName</td><td>String</td><td>로케이션 이름</td></tr></tbody></table>

**예제**

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FrA5vQIeT9rFA1w8wJCTQ%2Fimage.png?alt=media&#x26;token=11413179-0471-47d5-b55f-906c7547c790" alt=""><figcaption></figcaption></figure></div>

```jsx
// 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

{% hint style="info" %}
Map.hasLocation(locationName: String): Boolean
{% endhint %}

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

**파라미터**

| 이름           | 타입     | 설명      |
| ------------ | ------ | ------- |
| locationName | String | 로케이션 이름 |

**예제**

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

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

### getObjectsByType

{% hint style="info" %}
Map.getObjectsByType(type: numer) : Array
{% endhint %}

&#x20;Type에 해당하는 오브젝트들을 리턴하는 함수입니다.

**파라미터**

| 이름   | 타입     | 설명           |
| ---- | ------ | ------------ |
| type | Number | 오브젝트의 type 값 |

**예제**

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

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FF2dFIiZPH4pUKucIe10P%2Fimage.png?alt=media&#x26;token=970e0c60-51ac-41df-8261-b3e0a0f2856e" alt=""><figcaption><p>오브젝트 조회</p></figcaption></figure></div>

### getTopObjectsByType

{% hint style="info" %}
Map.getTopObjectsByType(type: numer) : array
{% endhint %}

&#x20;Type에 해당하는 상단오브젝트들을 리턴하는 함수입니다.

**파라미터**

| 이름   | 타입     | 설명           |
| ---- | ------ | ------------ |
| type | Number | 오브젝트의 type 값 |

**예제**

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

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

<div align="left"><figure><img src="https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FF2dFIiZPH4pUKucIe10P%2Fimage.png?alt=media&#x26;token=970e0c60-51ac-41df-8261-b3e0a0f2856e" alt=""><figcaption><p>상단 오브젝트 조회</p></figcaption></figure></div>

### sayObjectWithKey

{% hint style="info" %}
Map.sayObjectWithKey( key: string, message: string )
{% endhint %}

&#x20;key 값을 가진 오브젝트 위에 말풍선을 표시하는 함수입니다.

**파라미터**

| 이름      | 타입     | 설명           |
| ------- | ------ | ------------ |
| key     | String | 대상오브젝트의 키 값  |
| message | String | 말풍선에 표시할 메시지 |

**예제**

&#x20;key 값을 가진 오브젝트 위에 말풍선 표시하기

![](https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2Fb6S18wK09wyTuvGCAJT0%2Fimage.png?alt=media\&token=b61ef385-7458-41f7-b19b-9b123701bf90)

{% file src="<https://2461137890-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiW553XSGeKCAPpImxXi3%2Fuploads%2FzKQGTyeEbqPFHp3Qg5Ka%2FsayObjectWithKey.zip?alt=media&token=f7fd9815-e5f2-448f-bf4f-b885f2873279>" %}

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

### 부록

[<mark style="color:purple;">스프라이트시트 이해하기</mark>](https://docs-kr.zep.us/creator/reference/spritesheet)

[<mark style="color:purple;">기준좌표란?</mark>](https://docs-kr.zep.us/creator/reference/coordinate)

***