# Methods ### 소개 화면에 UI를 표시, 유저 이동 또는 강퇴, 사운드 재생 등 편리한 기능을 제공하는 함수들 입니다. Methods 함수는 용도에 따라 [**UI**](#ui) **,** [**User Control**](#user-control)**,** [**Sound**](#sound)**,** [**통신**](#undefined-1)**,** [**공통**](#undefined-2) 메소드로 나눌 수 있습니다. ### UI

이름	설명
loadSpritesheet	스프라이트 시트 그림 파일을 읽어 객체화하는 함수입니다.
showCenterLabel	모든 플레이어에게 지정된 위치에 text를 3초간 표시하는 함수입니다.
showCustomLabel	모든 플레이어에게 지정된 위치에 text를 3초간 표시하는 함수입니다. text 부분에 span 태그를 넣어 텍스트를 꾸밀 수 있습니다.
sayToAll	모든 플레이어의 채팅창에 text 를 출력하는 함수입니다.
sayToStaffs	Staff 권한 이상의 플레이어의 채팅창에 text 를 출력하는 함수입니다.
showWidget	모든플레이어에게 지정된 align의 위치에 html파일을 위젯으로 불러오는 함수입니다.
showYoutubeWidget	링크에 해당하는 Youtube 컨텐츠를 위젯으로 불러옵니다.

### **Control**

이름	설명
spawnPlayer	플레이어를 지정한 x, y 좌표로 이동 시키는 함수입니다.
kickPlayer	플레이어를 추방하는 함수입니다.
forceDestroy	미니게임 앱을 강제 종료하는 함수입니다.
clearChat	모든 채팅 내용을 삭제하는 함수입니다.
getPlayerByID	id 에 해당하는 플레이어를 반환하는 함수입니다.

### Sound

이름	설명
playSound	사운드 파일을 재생하는 함수입니다.
playSoundLink	사운드 URL을 재생하는 함수입니다.
stopSound	재생 중인 모든 사운드를 멈추는 함수입니다.

### 통신

이름	설명
httpGet	http get 요청을 보내는 함수입니다.
httpPost	Form-Data 형태의 http post 요청을 보내는 함수 입니다.
httpPostJson	JSON 형태의 http post 요청을 보내는 함수입니다.

### 공통

이름	설명
sendUpdated	App, Player 관련 필드 값이 변경되면 변경 값을 적용하는 함수입니다.

## 📚 API 설명 및 예제 ### 🎨 **UI Methods** **UI 함수 한 눈에 보기** ```jsx // 스프라이트 시트 그림 파일을 읽어 객체화 App.loadSpritesheet(fileName: string, frameWidth: number, frameHeight: number, anims: array, frameRate: number): ScriptDynamicResource // 모든 플레이어에게 지정된 위치에 해당 text를 1초간 표시 App.showCenterLabel(text: string, color: uint = 0xFFFFFF, bgColor: uint = 0x000000, offset: int = 0, time: int = 3000) // 모든 플레이어에게 지정된 위치에 해당 text를 3초간 표시, 커스터마이징 가능 App.showCustomLabel(text: string, color: number = 0xFFFFFF, bgColor: number = 0x000000, offset: number = 0, width = 100, opacity = 0.6, time: int = 3000); // 채팅창에 해당 text내용을 출력 App.sayToAll(text: string, color: uint = 0xFFFFFF) // 모든 플레이어에게 지정된 align의 위치에 해당 html파일을 위젯으로 불러오기 App.showWidget(fileName: string, align: string, width: number, height: number): ScriptWidget // 모든 플레이어에게 지정된 align의 위치에 해당 YouTube link의 동영상을 재생시킴 App.showYoutubeWidget(link: string, align: string, width: number, height: number): ScriptWidget ``` #### ### loadSpritesheet {% hint style="info" %} App.loadSpritesheet(fileName: string, frameWidth: number, frameHeight: number, anims: array, frameRate: number): ScriptDynamicResource {% endhint %} 스프라이트 시트 그림 파일을 읽어 객체화하는 함수입니다. ScriptDynamicResource에 대한 이해를 돕는 [스프라이트시트 이해하기](/creator/reference/spritesheet.md) 문서를 확인해보세요! **파라미터**

이름	타입	설명
fileName	String	불러올 파일의 이름
frameWidth frameHeight	number	한 프레임의 가로, 세로 픽셀 크기
anims	Array	애니메이션으로 지정할 frame 이미지 번호 배열
frameRate	number	프레임 하나 당 데이터를 표시하는 속도 frameRate: 8 → 1초에 8개의 이미지를 보여줌

**예제** 페인트맨 - 블루맨 스프라이트 이미지 적용해보기 {% file src="/files/BbXwzNer4wOQczIP3pn6" %} ```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(); }); ``` #### ### showCenterLabel {% hint style="info" %} App.showCenterLabel(text: string, color: uint = 0xFFFFFF, bgColor: uint = 0x000000, offset: number = 0, time: number = 3000) {% endhint %} 모든 플레이어에게 지정된 위치에 text를 3초간 표시하는 함수입니다. **파라미터**

이름	타입	설명
text	String	라벨에 출력할 텍스트
color	Uint	출력할 글씨의 색 (HexCode) 값을 입력하지 않을 경우, 흰색(0xFFFFFF)으로 적용됩니다. ➡️구글 색상 선택 도구
bgColor	Uint	메시지가 출력되는 라벨의 배경색 값을 입력하지 않을 경우, 검은색(0x000000)으로 적용됩니다.
offset	number	offset 값이 클수록 표시되는 위치가 화면 아래쪽 방향으로 가까워집니다. 값을 입력하지 않을 경우, 0으로 지정됩니다.
time	number	라벨 표시 시간 (ms), 기본 값 3000 ( 3초 )

**예제** 노란색 배경 입장 메시지 라벨을 2초간 출력해보기

```jsx App.onJoinPlayer.Add(function(player){ App.showCenterLabel(`${player.name}님이 입장하셨습니다.`, 0x000000, 0xFFFF00, 200, 2000); // 노란색 배경, 검정색 글씨로 표시하기 }); ``` #### ### showCustomLabel {% hint style="info" %} App.showCustomLabel(text: string, color: number = 0xFFFFFF, bgColor: number = 0x000000, offset: number = 0, width = 100, opacity = 0.6, time: number = 3000, option: object = null); {% endhint %} 모든 플레이어에게 지정된 위치에 text를 3초간 표시하는 함수입니다. text 부분에 `span` 태그를 넣어 텍스트를 꾸밀 수 있습니다. **파라미터**

이름	타입	설명
text	String	라벨에 출력할 텍스트 ( span 태그 허용 )
color	Uint	출력할 글씨의 색 (HexCode) 값을 입력하지 않을 경우, 흰색(0xFFFFFF)으로 적용됩니다.
bgColor	Uint	메시지가 출력되는 라벨의 배경색 값을 입력하지 않을 경우, 검은색(0x000000)으로 적용됩니다. ➡️구글 색상 선택 도구
offset	number	offset 값이 클수록 표시되는 위치가 화면 아래쪽 방향으로 가까워집니다. 값을 입력하지 않을 경우, 0으로 지정됩니다.
width	number	라벨의 너비를 n%로 설정하는 값 입니다. (기본 값 100)
opacity	number	라벨의 배경 투명도를 설정하는 값 입니다. (기본 값 0.6, 범위 0 ~ 1)
time	number	라벨 표시 시간 (ms), 기본 값 3000 ( 3초 )

**옵션**

이름	타입	설명
key	String	라벨에 키 값을 할당하여, 서로 다른 키 값을 가진 라벨은 동시에 표시할 수 있습니다.
borderRadius	String	라벨의 모서리에 둥글기를 설정할 수 있습니다. ex) borderRadius: "8px"
fontOpacity	boolean	false로 설정시 폰트에 투명도가 적용되지 않습니다.
padding	String	라벨 내부에 padding 값을 지정 할 수 있습니다. ex) padding: "8px"

**예제** [**커스텀 라벨 예제 코드 페이지**](/creator/tutor/custom-label.md)**를 참고해주세요** #### ### sayToAll {% hint style="info" %} App.sayToAll(text: string, color: uint = 0xFFFFFF) {% endhint %} 채팅창에 text 내용을 출력합니다. **파라미터**

이름	타입	설명
text	String	채팅창에 출력할 텍스트
color	Uint	출력할 글씨의 색을 지정합니다. (HexCode) 값을 입력하지 않을 경우, 흰색(0xFFFFFF)으로 적용됩니다. ➡️구글 색상 선택 도구

**예제** 입장메시지를 하늘색으로 출력해보기

```jsx // 플레이어가 입장할 때 실행 App.onJoinPlayer.Add(function (player) { App.sayToAll(`[info]${player.name} has entered.`, 0x00ffff); // 하늘색으로 표시하기 }); ``` ### sayToStaffs {% hint style="info" %} App.sayToStaffs(text: string, color: uint = 0xFFFFFF) {% endhint %} Staff이상 권한의 유저 채팅창에 text 내용을 출력합니다. **파라미터**

이름	타입	설명
text	String	채팅창에 출력할 텍스트
color	Uint	출력할 글씨의 색을 지정합니다. (HexCode) 값을 입력하지 않을 경우, 흰색(0xFFFFFF)으로 적용됩니다. ➡️구글 색상 선택 도구

**예제** 입장메시지를 하늘색으로 출력해보기

```jsx // 플레이어가 입장할 때 실행 App.onJoinPlayer.Add(function (player) { App.sayToStaffs(`[Staff] ${player.name} has entered.`, 0x00ffff); // 하늘색으로 표시하기 }); ``` ### showWidget {% hint style="info" %} App.showWidget(fileName: string, align: string, width: number, height: number): ScriptWidget {% endhint %} 모든 플레이어에게 지정된 align의 위치에 해당 html파일을 위젯으로 불러오는 함수입니다. **파라미터**

이름	타입	설명
fileName	String	불러올 파일의 이름
align	String	위젯을 표시할 위치 ’popup’, ‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’
width height	number	위젯을 표시할 영역의 가로, 세로 크기(px)

**예제** 초성퀴즈 위젯 따라해보기 {% file src="/files/r3LiUM54pxLvLilyxNI7" %} ![](/files/a7GYgJdTTL0zkewyWlVk) ```jsx let _widget = null; // 플레이어가 입장할 때 실행 App.onJoinPlayer.Add(function (player) { _widget = App.showWidget("widget.html", "top", 200, 300); // 화면 상단, 200x300 영역에 위젯을 보여줌 _widget.sendMessage({ timer: 15, answer: "ㅅㅍㅋ", }); }); ``` #### ### showYoutubeWidget {% hint style="info" %} App.showYoutubeWidget(link: string, align: string, width: number, height: number): ScriptWidget {% endhint %} 링크에 해당하는 Youtube 컨텐츠를 위젯으로 불러옵니다. **파라미터**

이름	타입	설명
link	String	Youtube 컨텐츠 url
align	String	위젯을 표시할 위치 ’popup’, ‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’
width height	number	위젯을 표시할 영역의 가로, 세로 크기(px)

**예제** Youtube 위젯 표시해보기 ![](/files/9Za1cnJNtGZcZG0l1P68) ```jsx // 플레이어가 입장할 때 실행 App.onJoinPlayer.Add(function (player) { App.showYoutubeWidget("https://www.youtube.com/watch?v=SXnMGIR8cjY","top",600,500); }); ``` ### ## **🔗Control Methods** **Control 함수 한 눈에 보기** ```jsx // playerID 에 해당하는 플레이어를 tileX, tileY 좌표로 이동시킨다. App.spawnPlayer(playeID: string, tileX: number, tileY: number) // playerID 에 해당하는 플레이어를 추방한다. // 추방당한 유저는 24시간 동안 해당 스페이스에 접근하지 못하게 된다. App.kickPlayer(playeID: string) // 미니게임 앱을 강제종료시킵니다. App.forceDestroy(); // 모든 채팅내용을 삭제합니다. App.clearChat(); //id 에 해당하는 플레이어를 반환하는 함수입니다. App.getPlayerID(playerID:string); ``` #### ### spawnPlayer {% hint style="info" %} App.spawnPlayer(playeID: string, tileX: number, tileY: number) {% endhint %} playerID 에 해당하는 플레이어를 tileX, tileY 좌표로 이동시키는 함수입니다. **파라미터**

이름	타입	설명
playerID	String	플레이어의 ID 값
tileX tileY	number	플레이어를 이동시킬 x, y 좌표 값

**예제** 입장하는 플레이어를 지정 좌표로 이동시키기 ```jsx // 플레이어가 입장할 때 실행 App.onJoinPlayer.Add(function (player) { App.spawnPlayer(player.id, 5, 5); // 플레이어를 5,5 위치로 이동시키기 }); ``` ### kickPlayer {% hint style="info" %} App.kickPlayer(playerID: string) {% endhint %} playerID 에 해당하는 플레이어를 추방하는 함수입니다. **파라미터**

이름	타입	설명
playerID	String	플레이어의 ID 값

**예제** 강퇴 명령어 만들어보기 ⛔ 강퇴 당한 참가자는 24시간 동안 해당 스페이스에 접속하지 못합니다. ```jsx // 플레이어가 채팅을 입력할 때 실행 // 명령어 형식 '!강퇴 닉네임' App.onSay.Add(function (player, text) { let players = App.players; if (text.indexOf("!강퇴 ") == 0) { let nickname = text.slice(4); for (let i in players) { let p = players[i]; if (p.name == nickname) { App.kickPlayer(p.id); break; } } } }); ``` ### forceDestroy {% hint style="info" %} App.forceDestroy(); {% endhint %} 미니게임 앱을 강제 종료하는 함수입니다. **예제** 미니게임 앱을 강제 종료시키기 ```jsx // q 키를 누르면 동작하는 함수 App.addOnKeyDown(81, function (player) { App.forceDestroy(); }); ```

### clearChat {% hint style="info" %} App.clearChat(); {% endhint %} 모든 채팅 내용을 삭제하는 함수입니다. **예제** Q를 눌러 채팅 내용 지우기 ```jsx // q 키를 누르면 동작하는 함수 App.addOnKeyDown(81, function (player) { App.clearChat(); }); ```

### getPlayerByID {% hint style="info" %} App.getPlayerByID(playerID: string); {% endhint %} id 에 해당하는 플레이어를 반환하는 함수입니다. **예제** App.getPlayerByID 사용 방법 ```jsx // q 키를 누르면 동작하는 함수 App.addOnKeyDown(81, function (player) { const myPlayer = App.getPlayerByID(player.id); }); ``` ## 🔉 **Sound Methods** **Sound 함수 한 눈에 보기** ```jsx // 모든 플레이어에게 사운드를 재생 App.playSound(fileName: string, loop: boolean = false, overlap: boolean = false) // 모든 플레이어에게 링크에 해당하는 사운드를 재생 App.playSoundLink(link: string, loop: boolean = false) // 모든 재생되는 사운드를 멈춤 App.stopSound() // 찌르기(Z키) 공격 효과음을 변경하는 함수입니다. App.changeAttackSound(fileName:string) ``` ### playSound {% hint style="info" %} App.playSound(fileName: string, loop: boolean = false, overlap: boolean = false) {% endhint %} 모든 플레이어에게 사운드를 재생하는 함수입니다. **파라미터**

이름	타입	설명
fileName	String	불러올 파일의 이름
loop	boolean	true: 반복 재생 false: 1회 재생
overlap	boolean	사운드 오버랩(겹침) 재생 가능 여부

**예제** 플레이어가 입장할 때 입장음 적용해보기 ( 파일 ) {% file src="/files/MFoMKAuui8WogohY8jA1" %} ```jsx //플레이어가 입장할 때 실행 App.onJoinPlayer.Add(function (player) { App.playSound("join.mp3", false, true); }); ``` #### ### playSoundLink {% hint style="info" %} App.playSoundLink(link: string, loop: boolean = false) {% endhint %} 모든 플레이어에게 사운드를 재생하는 함수입니다. > 💡 **올바른 링크를 입력했는데 재생이 되지 않는 경우** > > CORS 정책을 위반한 경우일 가능성이 높습니다. CORS 정책을 맞출 수 없는 경우에는 playSoundLink 대신 음악 파일을 업로드 하여 playSound 함수를 사용하는 것을 권장드립니다. **파라미터**

이름	타입	설명
link	String	사운드 url
loop	boolean	true: 반복 재생 false: 1회 재생

**예제** 플레이어가 입장할 때 입장음 적용해보기 ( 사운드 url ) ```jsx // 플레이어가 입장할 때 실행 App.onJoinPlayer.Add(function (player) { App.playSoundLink("https://zep.us/assets/sounds/ring.mp3",false); }); ``` #### ### stopSound {% hint style="info" %} App.stopSound(); {% endhint %} 재생되고 있는 사운드를 멈추는 함수입니다. **파라미터** * 없음 **예제** q를 누르면 사운드가 멈추는 기능 만들어보기 ```jsx // q 키를 누르면 동작하는 함수 App.addOnKeyDown(81,function(p){ App.stopSound(); }) ``` ### changeAttackSound {% hint style="info" %} App.changeAttackSound(fileName:string) {% endhint %} 찌르기(Z키) 공격 효과음을 변경하는 함수입니다. **파라미터**

이름	타입	설명
fileName	String	적용할 사운드 파일명

**예제** changeAttackSound 사용 방법 ```jsx App.onStart.Add(function(){ App.changeAttackSound("attack.mp3"); }) ``` ## 📡 **통신 Methods** **통신 함수 한 눈에 보기** ```jsx // 해당 URL에 HTTP Get 요청을 실행 App.httpGet(url: string, headers: object, callback: ((string) => void)) // 해당 URL에 HTTP Post 포스팅을 실행 App.httpPost(url: string, headers: object, body: object, callback: ((string) => void)) // 해당 URL에 HTTP Post 포스팅을 실행 App.httpPostJson(url: string, headers: object, body: object, callback: ((string) => void)) ``` #### ### httpGet {% hint style="info" %} App.httpGet(url: string, headers: object, function(res: string){}) {% endhint %} http get 요청을 보내는 함수입니다. **파라미터**

이름	타입	설명
url	String	요청을 보낼 주소
headers	Object	요청 헤더
res	String	요청에 대한 응답

**예제** [한국어 별명 생성기](https://nickname.hwanmoo.kr/) API를 이용해 입장하는 플레이어의 닉네임을 바꿔보기

```jsx // 플레이어가 입장할 때 동작하는 함수 App.onJoinPlayer.Add(function (player) { App.httpGet( "https://nickname.hwanmoo.kr/?format=json&count=1&max_length=6&whitespace=_", null, function (res) { // 응답 결과를 JSON 오브젝트로 변경 let response = JSON.parse(res); player.name = response.words[0]; player.sendUpdated(); } ); }); ``` #### ### httpPost {% hint style="info" %} App.httpPost(url: string, headers: object, body: object, function(res: string)) {% endhint %} Form-Data 형태의 http post 요청을 보내는 함수 입니다. **파라미터**

이름	타입	설명
url	String	요청을 보낼 주소
headers	Object	요청 헤더, 요청 헤더가 없으면 { } 를 입력.
body	Object	요청 바디 ( Form data )
res	String	요청에 대한 응답

**예제** 앱에서 보낸 헤더와 데이터를 응답으로 받아 채팅창에 출력해보기. 예제와 같이 key, value 값을 string 형태로 작성해야하며, 요청 서버에서 폼데이터를 받아 처리가 가능해야합니다. ```jsx // q를 눌렀을 때 실행되는 함수 App.addOnKeyDown(81, function (player) { App.httpPost( "https://postman-echo.com/post", { "test-header": "zep", }, { "name": "zepscript", }, (res) => { // 요청 결과를 JSON 오브젝트로 변환 let response = JSON.parse(res); App.sayToAll(`보낸 헤더: ${response.headers["test-header"]}`, 0xffffff); App.sayToAll(`보낸 데이터: ${response.form.name}`, 0xffffff); } ); }); ``` #### ### httpPostJson {% hint style="info" %} App.httpPostJson(url: string, headers: object, body: object, function(res: string)) {% endhint %} Json 형태의 http post 요청을 보내는 함수 입니다. **파라미터**

이름	타입	설명
url	String	요청을 보낼 주소
headers	Object	요청 헤더, 요청 헤더가 없으면 { } 를 입력.
body	Object	요청 바디 ( JSON data )
res	String	요청에 대한 응답

**예제** 앱에서 보낸 데이터를 응답으로 받아 채팅창에 출력해보기. ```jsx // q를 눌렀을 때 실행되는 함수 App.addOnKeyDown(81, function (player) { App.httpPostJson( "https://postman-echo.com/post", {}, { name: "zepscript", }, (res) => { App.sayToAll(`${res}`, 0xffffff); // 요청 결과를 JSON 오브젝트로 변환 let response = JSON.parse(res); App.sayToAll(`보낸 데이터: ${response.data.name}`, 0xffffff); } ); }); ``` ## 💠 **공통 Methods** **공통 함수 한 눈에 보기** ```jsx // App 관련 필드값이 변경되면 변경값을 적용함 App.sendUpdated() ``` *** ### sendUpdated {% hint style="info" %} App.sendUpdated() {% endhint %} App 관련 필드 값이 변경되면 변경 값을 적용하는 함수입니다. **파라미터** * 없음 --- # 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/scriptapp/methods.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.