# Field
### 소개
플레이어와 관련된 속성 값들 입니다.
플레이어의 닉네임([name](#id-name)), 위치([tileX / tileY](#tilex-tiley)) 등을 조회하거나 플레이어에게 스팟라이트([spotlight](#spotlight)), 안보임([hidden](#hidden)) 기능을 활성화 할 수 있으며, 캐릭터의 이동속도([moveSpeed](#movespeed)), 이미지([sprite](#sprite))를 변경하거나 플레이어의 저장공간([storage](#storage))을 활용할 수도 있습니다.
🔒 아이콘이 있는 필드는 수정이 불가능한 읽기 전용 필드입니다.
이름
설명
🔒 id
플레이어의 id 값
name
플레이어의 닉네임 값
title
아바타 닉네임 위에 노란색으로 노출되는 텍스트
🔒 role
플레이어의 권한을 나타내는 숫자 값
🔒 tileX / tileY
아바타가 서있는 X 좌표 값과 Y 좌표 값
🔒 dir
아바타가 바라보고 있는 방향 값
moveSpeed
플레이어의 이동속도 값
sprite
아바타의 스프라이트 이미지 값
tag
필요한 속성 값을 부여 가능한 값 저장 공간
hidden
값이 true 이면, 다른 플레이어에게 보이지 않습니다.
spotlight
플레이어의 스팟라이트 기능 활성화 여부
attackType
플레이어의 공격(Z키) 타입
attackSprite
플레이어의 공격(Z키) 이미지 값
attackParam1
공격 이미지가 날아가는 거리 값
attackParam2
공격 가능 거리 값 attackType이 2(원거리 공격)으로 설정 된 경우에만 유효
🔒 walletAddress
플레이어의 전자지갑 주소 값
storage
스페이스 내의 Player 값 저장 공간(스페이스 한정)
🔒 isMobile
플레이어의 모바일 접속여부
🔒 isMoving
플레이어가 움직이고 있으면 True, 아니면 False를 반환
🔒 isJumping
플레이어가 점프하고 있으면 True, 아니면 False를 반환
🔒 customData
URL 쿼리 스트링을 읽어 값을 저장 할 수 있습니다.
displayRatio
플레이어의 화면 줌 비율을 조절 할 수 있습니다.
titleColor
플레이어의 타이틀 색상
🔒 emailHash
플레이어의 이메일 Hash 값
🔒 isGuest
비로그인 플레이어인 경우 true 값을 가집니다.
🔒 language
플레이어의 브라우저에서 사용하는 언어 설정 값
🔒 away
5분 이상 비활성화된 유저인 경우 true값을 가집니다.
enableFreeView
맵 둘러보기 허용 여부를 설정할 수 있습니다.
## 📚 API 설명 및 예제
### id , name
{% hint style="info" %}
player.id : Number player.name : String
{% endhint %}
플레이어의 id, 닉네임 값을 가져옵니다.
**예제**
플레이어가 입장 할 때 플레이어의 id, name 값 출력해보기
```jsx
// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function(player){
App.sayToAll(`id: ${player.id} name: ${player.name}`);
})
```
####
### title
{% hint style="info" %}
player.title : String
{% endhint %}
title은 캐릭터 닉네임 위에 노란색으로 노출되는 텍스트입니다.
**예제**
플레이어가 입장 할 때 title 설정해보기
```jsx
// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function(player){
player.title = "타이틀";
player.sendUpdated();
})
```
####
### role
{% hint style="info" %}
player.role : Number
{% endhint %}
role은 플레이어의 권한을 나타내는 숫자 값 입니다.
플레이어의 role에 따라 다음과 같은 값을 출력합니다.
| 일반/비로그인유저 | -1 | 스태프 | 2000 |
| --------- | ---- | ---- | ---- |
| 멤버 | 0 | 관리자 | 3000 |
| 에디터 | 1000 | 맵소유자 | 3001 |
**예제**
권한 값을 채팅 창에 표시해보기
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81,function(player){
App.sayToAll(`${player.name}님의 권한: ${player.role}`)
})
```
####
### tileX, tileY
{% hint style="info" %}
player.tileX: Number player.tileY: Number
{% endhint %}
플레이어의 캐릭터가 서있는 X 좌표 값과 Y 좌표 값입니다.
**예제**
내 캐릭터의 x, y 좌표 출력해보기
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81,function(player){
App.sayToAll(`현재 좌표: (${player.tileX}, ${player.tileY})`)
})
```
####
### dir
{% hint style="info" %}
player.dir : Number
{% endhint %}
플레이어의 캐릭터가 바라보고 있는 방향입니다.
캐릭터가 바라보고 있는 방향에 따라 다음과 같은 값을 출력합니다.
캐릭터가 바라보는 방향에 따른 dir 값
**예제**
캐릭터가 바라보고 있는 방향을 출력해보기
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81,function(player){
App.sayToAll(`바라보고 있는 방향: ${player.dir}`)
})
```
####
### moveSpeed
{% hint style="info" %}
player.moveSpeed : Number
{% endhint %}
플레이어의 이동속도 값입니다.( 기본 값: 80 )
이동속도 값이 0이면 움직일 수 없습니다.
**예제**
q 키를 누르면 이동속도가 빨라지는 함수 만들어보기
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81,function(player){
player.moveSpeed = 150;
player.sendUpdated();
})
```
####
### sprite
{% hint style="info" %}
player.sprite : ScriptDynamicResource
{% endhint %}
플레이어 캐릭터의 스프라이트 이미지입니다. ( **null** 입력 시 기본 아바타 이미지로 초기화 )
스프라이트 이미지를 처음 들어보신다면 [**스프라이트시트 이해하기**](/creator/reference/spritesheet.md) 문서를 확인해보세요!
**예제**
페인트맨 - 블루맨 이미지를 캐릭터 이미지로 적용해보기
{% file src="/files/2JzKM0PwoR2p0RFZXeWm" %}
```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],
}, 8);
// 플레이어가 입장하면 캐릭터 이미지가 바뀜
App.onJoinPlayer.Add(function(player){
player.sprite = blueman;
player.sendUpdated();
});
```
####
### tag
{% hint style="info" %}
player.tag: Any
{% endhint %}
tag를 사용해 플레이어에게 필요한 속성 값을 부여 할 수 있습니다.
**예제**
플레이어에게 ‘alive’ 속성 값 부여해보기. ‘alive’ 속성 값은 임의로 생성한 속성 입니다.
쓰이지 않는다면 아무 의미 없는 속성 값 이지만, 게임을 만들 때 플레이어의 생존 여부를 체크하는 중요한 속성으로 사용할 수 있습니다.
```jsx
// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function (player) {
player.tag = {
alive: true,
};
player.sendUpdated();
App.sayToAll(`alive: ${player.tag.alive}`);
});
```
####
### hidden
{% hint style="info" %}
player.hidden: Boolean
{% endhint %}
hidden 값이 true 이면, 해당 플레이어는 다른 플레이어에게 보이지 않습니다.
:warning: hidden인 상태에서 모습은 보이지 않지만, 오디오와 비디오 연결은 됩니다.
**예제**
캐릭터에게 hidden 속성을 부여해서 다른 플레이어에게 안 보이게 해보기
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81,function(player){
player.hidden = true;
player.sendUpdated();
});
```
####
### spotlight
{% hint style="info" %}
player.spotlight: Boolean
{% endhint %}
플레이어의 스팟 라이트 기능 활성화 여부입니다.
**예제**
q 키를 누르면 스팟 라이트 기능을 ON/OFF 하는 함수 만들어보기
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81,function(player){
if(player.spotlight){
player.spotlight = false;
}
else{
player.spotlight = true;
}
player.sendUpdated();
});
```
### attackType
{% hint style="info" %}
player.attackType : Number
{% endhint %}
플레이어의 공격(Z키) 타입입니다. ( 기본: 0 )
attackType
설명
0
attackType을 설정 하지 않았을 때 기본 공격 타입을 의미합니다.
2
원거리 공격 타입입니다. attackParam2와 함께 설정할 때 유효합니다.
**예제**
캐릭터의 attackType 변경해보기
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81, function (player) {
player.attackType = 0;
App.sayToAll(`attackType: ${player.attackType}`);
player.sendUpdated();
});
```
####
### attackParam1
{% hint style="info" %}
player.attackParam1: Number
{% endhint %}
공격(Z키) 이미지가 날아가는 거리 속성입니다. 공격 가능 거리는 늘어나지 않습니다.
**예제**
attackParam1 변경해보기
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81, function (player) {
player.attackType = 0;
player.attackParam1 = 10;
App.sayToAll(`attackType: ${player.attackType}`);
App.sayToAll(`attackParam1: ${player.attackParam1}`);
player.sendUpdated();
});
```
####
### attackParam2
{% hint style="info" %}
player.attackParam2: Number
{% endhint %}
공격 가능 거리 속성입니다. attackType이 원거리 공격으로 설정 된 경우에만 유효합니다.
**예제**
attackParam2 이용해 원거리 공격 설정 해보기.
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81, function (player) {
player.attackType = 2;
player.attackParam2 = 5;
App.sayToAll(`attackType: ${player.attackType}`);
App.sayToAll(`attackParam2: ${player.attackParam2}`);
player.sendUpdated();
});
```
####
### attackSprite
{% hint style="info" %}
player.attackSprite : ScriptDynamicResource
{% endhint %}
공격(Z키) 이미지를 지정할 수 있습니다.
**예제**
공격 이미지 적용해보기
예시 이미지 - 단일 이미지
예시 이미지 - 연속된 이미지
연속된 이미지의 경우
방향별 애니메이션 적용
{% file src="/files/d1s15vxM9bJBN4MkEeMk" %}
방향별 애니메이션 예제 코드
{% endfile %}
```jsx
// 단일 이미지의 경우
let redBoxing = App.loadSpritesheet("redBoxing.png");
App.onJoinPlayer.Add(function (player) {
player.attackSprite = redBoxing;
player.sendUpdated();
});
```
```javascript
// 연속된 이미지의 경우
let attackSprite = App.loadSpritesheet("attack_sprite.png", 32, 32, [0, 1, 2], 3);
App.onJoinPlayer.Add(function (player) {
player.attackSprite = attackSprite;
player.sendUpdated();
});
```
```
// 방향별 애니메이션을 적용하는경우
let attackSprite = App.loadSpritesheet(
"animation_sprite.png", // 이미지 파일명
48, 48, // 이미지 프레임 사이즈
{
left: [0, 1, 2, 3, 4, 5], // 좌측을 보고 공격하는 경우
right: [6, 7, 8, 9, 10, 11], // 우측을 보고 공격하는 경우
down: [12, 13, 14, 15, 16, 17], // 위를 보고 공격하는 경우
up: [18, 19, 20, 21, 22, 23], // 아래를 보고 공격하는 경우
},
6
);
App.onJoinPlayer.Add(function (player) {
player.attackSprite = attackSprite;
player.sendUpdated();
});
```
###
### walletAddress
{% hint style="info" %}
player.walletAddress : String
{% endhint %}
플레이어의 전자지갑 주소입니다.
**예제**
전자지갑 주소 출력해보기 ( 전자지갑 주소가 없을 경우 null이 출력 )
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81, function (player) {
App.sayToAll(`${player.walletAddress}`)
});
```
####
### storage
{% hint style="info" %}
player.storage : String
{% endhint %}
스페이스 내의 Player 값 저장 공간 입니다 (스페이스 한정)
**예제**
플레이어 storage에 데이터를 저장하고, 확인해보기
💡 앱을 종료했다가 다시 켜도 저장된 값이 사라지지 않습니다.
```jsx
// q 키를 누르면 동작하는 함수
// App.addOnKeyDown
App.addOnKeyDown(81,function(player){
player.storage = "data";
player.save(); // storage의 값이 변경되면 player.save()로 변경값을 적용
})
// w 키를 누르면 동작하는 함수
App.addOnKeyDown(87,function(player){
App.sayToAll(player.storage); // player storage에 저장된 값을 채팅창에 출력
})
```
####
### isMobile
{% hint style="info" %}
player.isMobile : Boolean
{% endhint %}
플레이어의 모바일 접속 여부를 true/false 로 출력합니다.
**예제**
플레이어가 입장 할 때 입장메시지에 모바일/PC 표시해보기
```jsx
// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function(player){
if(player.isMobile){
App.sayToAll(`${player.name}님이 모바일에서 접속했습니다.`)
} else{
App.sayToAll(`${player.name}님이 PC에서 접속했습니다.`)
}
});
```
####
### isMoving
{% hint style="info" %}
player.isMoving : Boolean
{% endhint %}
플레이어가 움직이고 있으면 True, 아니면 False를 반환합니다.
**예제**
플레이어의 움직임을 감지해서 메시지 출력해보기.
```jsx
App.onUpdate.Add(function (dt) {
let _players = App.players;
for (let i in _players) {
let p = _players[i];
if (p.isMoving) {
App.sayToAll(`${p.name}님이 움직이는 중..`);
}
}
});
```
####
### isJumping
{% hint style="info" %}
player.isJumping : Boolean
{% endhint %}
플레이어가 점프하고 있으면 True, 아니면 False를 반환합니다.
**예제**
플레이어의 점프를 감지해서 메시지 출력해보기.
```jsx
App.onUpdate.Add(function (dt) {
let _players = App.players;
for (let i in _players) {
let p = _players[i];
if (p.isJumping) {
App.sayToAll(`[시스템] ${p.name}님이 점프 중..`);
}
}
});
```
####
### customData
{% hint style="info" %}
player.customData : String
{% endhint %}
URL 쿼리스트링으로 전달 받은 값을 저장하는 필드입니다.
**예제**
:fire: [URL 쿼리스트링 활용하기](/creator/reference/url.md)
### displayRatio
{% hint style="info" %}
player.displayRatio
{% endhint %}
플레이어화면의 줌을 컨트롤 하는 값 ( 기본 값: 1 )
**예제**
화면의 줌을 컨트롤 하는 키 만들어보기
```jsx
// q 키를 누르면 동작하는 함수
// 한 번 누르면 화면의 줌 값이 커지고, 한 번 더 누르면 원래대로 돌아오는 키 함수
App.addOnKeyDown(81,function(player){
if(player.displayRatio == 1){
player.displayRatio = 5;
}else{
player.displayRatio = 1;
}
player.sendUpdated(); //* player의 Field값이 변경되면 player.sendUpdated()로 변경값을 적용
})
```
displayRatio = 1
displayRatio = 5
### titleColor
{% hint style="info" %}
player.titleColor
{% endhint %}
플레이어의 타이틀 색상을 읽거나 수정 할 수 있습니다.
Enum 값 또는 컬러 Hex Code 값을 입력할 수 있습니다.
사용 가능한 Enum ColorType
{ WHITE, BLACK, RED, GREEN, BLUE, ORANGE, PURPLE, GRAY, YELLOW, MAGENTA, CYAN }
**예제**
타이틀 색상 바꿔보기
```jsx
// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
player.title = "🔸Title🔸";
// Enum 값으로 입력하는 경우
player.titleColor = ColorType.CYAN;
// Hex Code로 입력하는 경우 (주석을 해제해주세요)
// player.titleColor = 0x00FFFF;
player.sendUpdated(); //* player의 Field값이 변경되면 player.sendUpdated()로 변경값을 적용
});
```
### emailHash
{% hint style="info" %}
player.emailHash
{% endhint %}
플레이어의 이메일 Hash 값을 가져옵니다.
**예제**
플레이어의 이메일 Hash 값 출력하기
```jsx
// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function(player){
App.sayToAll(`name: ${player.name} emailHash: ${player.emailHash}`);
})
```
###
### isGuest
{% hint style="info" %}
player.isGuest
{% endhint %}
비로그인 플레이어인 경우 true 값을 가집니다.
**예제**
비로그인 유저 입장시 타이틀에 "GUEST" 표시하기
```jsx
// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function(player){
if(player.isGuest){
player.title = "GUEST";
player.sendUpdated();
}
})
```
### language
{% hint style="info" %}
player.language
{% endhint %}
브라우저에서 사용하는 언어 설정값에 따라 다음과 같은 값을 가집니다.
> 한국어 "**ko**", 일본어: "**ja**", 영어: "**en**"
**예제**
유저 입장시 브라우저에서 사용 하는 언어 설정 값 표시하기
```jsx
// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function(player){
App.sayToAll(player.language);
})
```
### away
{% hint style="info" %}
player.away
{% endhint %}
장시간 비활성화된 유저인 경우 `true`값을 가집니다.
### enableFreeView
{% hint style="info" %}
player.enableFreeView
{% endhint %}
플레이어의 맵 둘러보기 허용 여부를 설정할 수 있습니다.
**예제**
단축키로 플레이어의 맵 둘러보기 허용 여부 설정하기
```jsx
// Q를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
if (player.enableFreeView) {
player.enableFreeView = false;
} else {
player.enableFreeView = true;
}
player.sendUpdated();
player.sendMessage(`player.enableFreeView = ${player.enableFreeView}`, 0x00ffff);
});
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs-kr.zep.us/zep-script-api/zepscriptapi/scriptplayer/field.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.