All pages
Powered by GitBook
1 of 7

ScriptApp

ScriptApp 클래스는 아래와 같이 5개의 카테고리로 구성되어있습니다. 각 카테고리의 제목을 선택하시면, 자세한 내용을 확인할 수 있습니다.

Lifecycle

앱이 시작되어, 실행되고 종료될 때까지를 하나의 생애 주기(Lifecycle)라고 합니다. 앱이 시작될 때, 실행 중일 때 그리고 종료될 때 등의 상황에서 필요한 동작들을 실행해 전체적인 앱의 생애주기를 만들어 나갈 수 있는 함수들이 모여있는 카테고리 입니다.

Field

스페이스나 맵, 플레이어 정보 등을 조회하거나, 저장공간을 활용할 수 있는 App과 관련된 속성이 모여있는 카테고리입니다.

Event Listeners

플레이어가 지정된 채팅을 입력하거나, 특정한 오브젝트를 공격할 와 같이 맵 내에서 발생할 수 있는 다양한 상황을 감지하여 동작하는 함수들이 모여있는 카테고리 입니다.

Callbacks

스크립트 개발자가 지정한 키를 플레이어가 누르거나 특정 지점에 도착했을 때와 같이 조건을 설정하고 조건이 만족되었을 때 동작하는 함수들이 모여있는 카테고리 입니다.

Methods

화면에 UI를 표시, 유저 이동 또는 강퇴, 사운드 재생 등 편리한 기능을 제공하는 함수들이 모여있는 카테고리 입니다.

Lifecycle

소개

앱이 시작되어, 실행되고 종료될 때까지를 하나의 생애 주기(Lifecycle)라고 합니다. 관련 함수들을 이용하여 앱이 시작될 때, 실행 중일 때 그리고 종료될 때 등의 상황에서 필요한 동작들을 실행해 전체적인 앱의 생애주기를 만들 수 있습니다.

이름
설명

onInit

App이 최초로 시작될 때 한 번 호출되는 함수입니다.

onJoinPlayer

onInit이 호출된 후, 접속해 있는 모든 플레이어를 해당 이벤트를 통해 입장 시키고, 이후 입장하는 플레이어가 있을 때 마다 동작합니다.

onStart

모든 플레이어가 onJoinPlayer를 통해 입장한 후 한 번 호출 됩니다.

onUpdate

약 20ms 마다 주기적으로 실행되는 함수입니다.

onLeavePlayer

퇴장하는 플레이어가 있을 때 마다 동작합니다. 이후, 다른 App이 실행되거나 설치한 Game Block이 파괴될 때 모든 플레이어를 이 함수를 통해 퇴장시킵니다.

onDestroy

다른 App이 실행되거나 설치한 Game Block이 파괴될 때 동작합니다.

App 생애 주기(Lifecycle) 이해하기

Lifecycle 함수들은 생애 주기에 맞게 기능을 만들 수 있는 필수적인 함수입니다. 아래 그림과 같이 앱이 실행될 때는 Enter 단계의 함수들이 동작하고, 앱이 실행 중 일때는 Update 단계의 함수들이 주기적으로 동작하며, 앱이 종료될 때는 Exit 단계의 함수들이 동작하게됩니다.

앱이 실행되어 종료될 때 까지 각 단계의 함수들을 잘 활용해 생애 주기에 맞게 App을 만들어보세요.

Lifecycle 함수 한 눈에 보기

// App 실행 시에 최초로 호출되는 이벤트 (유저 진입 전)
// Normal App과 Sidebar App은 Script 적용 후 맵이 실행될 때 호출 [ Enter ]
App.onInit.Add(function(){
});

// 모든 플레이어를 이 이벤트를 통해 App에 진입시킴 [ Enter ]
// 이후 플레이어가 입장 할 때마다 호출 [ Events ]
App.onJoinPlayer.Add(function(player) {
});

// 플레이어 모두 진입 시 최초로 시작되는 이벤트 [ Enter ]
App.onStart.Add(function(){
});

// 20ms 마다 호출되는 이벤트
// dt: deltatime(전 프레임이 완료되기까지 걸린 시간) [ Update ]
App.onUpdate.Add(function(dt){
});

// 이벤트 콜백 처리 후 다시 onUpdate

// App 종료 시 모든 플레이어를 App에서 나가게 함 [ Exit ]
App.onLeavePlayer.Add(function(player){
});

// App 종료 시 마지막으로 호출 [ Exit ]
// Normal App과 Sidebar App은 별도의 종료
App.onDestroy.Add(function(){
});

1️⃣ Enter 단계 함수

App의 실행과 함께 호출되는 라이프사이클 Enter 단계에서 호출되는 함수를 안내합니다.

onInit

App.onInit.Add(function(){})

App이 최초로 시작될 때 한 번 호출됩니다.

파라미터

  • 없음

예제

onInit 에서 채팅 출력해보기. ( 미니게임으로 만들어 확인해보세요. )

App.onInit.Add(function(){
	App.sayToAll("-- onInit --")
	App.sayToAll("   ready..  ")
	App.sayToAll("------------")
});

onJoinPlayer

App.onJoinPlayer.Add(function(player){})

onInit이 호출된 후, 접속해 있는 모든 플레이어를 해당 이벤트를 통해 입장시키고, 이후 입장하는 플레이어가 있을 때 마다 동작합니다.

파라미터

이름
타입
설명

player

Player

player는 입장하는 플레이어를 가르킴 파라미터의 이름은 임의로 변경가능

예시

플레이어 입장시 메시지 출력해보기

App.onJoinPlayer.Add(function(player){
	App.showCenterLabel(`${player.name}님이 입장하셨습니다.`)
});

onStart

App.onStart.Add(function(){})

모든 플레이어가 onJoinPlayer를 통해 입장한 후 한 번 호출 됩니다.

파라미터

  • 없음

예제

onStart에서 채팅 출력해보기 ( 미니게임으로 만들어 확인해보세요. )

App.onStart.Add(function(){
	App.sayToAll("-- App Start --")
});

Enter 단계 함수의 흐름 이해하기

Lifecycle Enter 단계의 흐름을 코드로 확인해보세요. 아래 코드를 미니게임으로 만들어 실행해보세요!

// main.js
App.onInit.Add(function(){
	App.sayToAll("-- onInit --")
	App.sayToAll("   ready..  ")
	App.sayToAll("------------")
});

App.onJoinPlayer.Add(function(player){
	App.sayToAll(`${player.name}님이 입장하셨습니다.`)
});

App.onStart.Add(function(){
	App.sayToAll("-- App Start --")
});
Enter 단계 함수들이 순서대로 동작하는 모습.

2️⃣ Update

Update에는 약 20ms 마다 주기적으로 실행되는 함수 onUpdate가 있습니다.

onJoinPlayer, onLeavePlayer 등의 이벤트가 발생하면 해당 이벤트 처리 후 다시 onUpdate가 주기적으로 실행됩니다.

onUpdate

App.onUpdate.Add(function(dt){})

약 20ms 마다 주기적으로 실행되는 함수입니다.

파라미터

이름
타입
설명

dt

Number

deltatime (전 프레임이 완료되기까지 걸린 시간, 약 20ms) dt 파라미터의 이름은 임의로 변경 가능

예시

onUpdate 함수를 이용해 10초 카운트다운 만들어보기

let countdown = 10;
let timer = 0;
App.onUpdate.Add(function(dt){
	timer += dt;
	if(timer >=1){
		if(countdown >= 0)
		{
			App.showCenterLabel(countdown--);
		}
		else{
			App.showCenterLabel("Time Over");
		}
		timer = 0;
	}
})

3️⃣ Exit 단계 함수

앱이 종료될 때 실행되는 함수 입니다.

onLeavePlayer

App.onLeavePlayer.Add(function(player){})

퇴장하는 플레이어가 있을 때 마다 동작합니다. 이후, 다른 App이 실행되거나 설치한 Game Block이 파괴될 때 모든 플레이어를 이 함수를 통해 퇴장시킵니다.

파라미터

이름
타입
설명

player

Player

player 파라미터는 퇴장하는 플레이어를 가르킴 player 파라미터의 이름은 임의로 변경 가능

예시

플레이어 퇴장 시 메시지 출력해보기

// 플레이어가 퇴장할 때 실행
App.onLeavePlayer.Add(function(player){
	App.showCenterLabel(`${player.name}님이 퇴장하셨습니다.`)
});

onDestroy

App.onDestroy.Add(function(){})

다른 App이 실행되거나, 설치한 Game Block이 파괴될 때 동작합니다.

파라미터

  • 없음

예제

Game Block 파괴 시 메시지 출력해보기 ( 미니게임 )

// Game Block 파괴 시 실행
App.onDestroy.Add(function(){
	App.showCenterLabel("게임 블록이 파괴되었습니다.")
});

Field

소개

Field는 App과 관련된 속성 값들 입니다. 이 필드를 활용해 참가 중인 스페이스나 맵, 플레이어 정보 등을 조회하거나, 저장공간을 활용할 수 있습니다.

🔒 아이콘이 있는 필드는 수정이 불가능한 읽기 전용 필드입니다.

이름
설명

🔒 spaceHashID

App이 설치된 스페이스의 해쉬값을 보여줍니다.

🔒 mapHashID

App이 설치된 맵의 해쉬값을 가져옵니다.

🔒 creatorID

App을 실행한 플레이어의 ID 값을 가져옵니다.

🔒 players

맵에 있는 모든 플레이어 리스트를 배열로 가져옵니다.

🔒 playerCount

앱이 설치된 맵에 있는 플레이어의 수를 가져옵니다.

cameraEffect

카메라 이펙트의 종류를 셋팅할 변수 값

cameraEffectParam

카메라 이펙트 효과의 범위 값

displayRatio

화면의 줌을 컨트롤 하는 값

storage

스페이스 내의 App 데이터의 저장공간(스페이스 한정)

followPlayer

App의 따라가기 기능 활성화 여부 값

showName

플레이어 닉네임 숨김 여부

🔒 appHashID

앱의 HashID 값을 가져옵니다.

enableFreeView

앱이 설치된 맵의 둘러보기 허용 여부를 설정할 수 있습니다.

📚 API 설명 및 예제

spaceHashID & mapHashID

App.spaceHashID: String App.mapHashID: String

앱이 설치된 스페이스의 spaceHashID와 mapHashID를 가져옵니다. (스페이스와 맵 이해하기)

예제

앱이 설치된 맵의 spaceHashID와 mapHashID 출력해보기

// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function(player){
  // 채팅창에 spaceHashID와 mapHashID 출력해보기
	App.sayToAll(`spaceHashID: ${App.spaceHashID}`); // spaceHashID: Ak42Xz
	App.sayToAll(`mapHashID: ${App.mapHashID}`) // mapHashId: 25g3RQ
})

creatorID

App.creatorID

미니게임을 실행한 플레이어의 ID 값을 가져옵니다. ⛔맵 내장형 앱인 노멀 앱과 사이드바 앱에서는 동작하지 않습니다.

예제

미니게임을 실행한 플레이어의 닉네임을 채팅창에 출력해보기

// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function(player){
	if(player.id == App.creatorID){
		App.sayToAll(`${player.name}님이 앱을 실행했습니다.`)
	}
})

players

App.players: ScriptPlayer[]

맵에 있는 모든 플레이어 리스트를 배열로 가져옵니다.

예제

맵에 있는 모든 플레이어 닉네임을 출력해보기

// q 키를 누르면 동작하는 함수
// App.addOnKeyDown 설명
App.addOnKeyDown(81,function(p){
	//App.players를 이용해 채팅창에 접속해있는 모든 플레이어의 닉네임을 출력하기
	let players = App.players;
	for(let i in players){
		let player = players[i]
		App.sayToAll(player.name)
	}
})

playerCount

App.playerCount: Number

앱이 설치된 맵에 있는 플레이어의 수를 가져옵니다.

예시

맵에 있는 플레이어 수 출력해보기

// q 키를 누르면 동작하는 함수
// App.addOnKeyDown 설명
App.addOnKeyDown(81,function(p){
	// 현재 접속자 수를 채팅창에 출력
	App.sayToAll(`접속자 수: ${App.playerCount}`)
})

cameraEffect & cameraEffectParam1

App.cameraEffect: NONE = 0, SPOTLIGHT = 1 App.cameraEffectParam1: Number

App.cameraEffect: 카메라 이펙트의 종류를 셋팅할 변수 값

App.cameraEffectParam1: 카메라 이펙트 효과의 범위 값

예제

비네팅 효과를 On/Off 하는 키 함수 만들어보기

// q 키를 누르면 동작하는 함수
// 한 번 누르면 비네팅 효과가 켜지고, 두 번 누르면 비네팅 효과가 꺼짐
// App.addOnKeyDown 설명
App.addOnKeyDown(81,function(p){
	if(App.cameraEffect == 0){
		App.cameraEffect = 1; // 1 = 비네팅 효과
		App.cameraEffectParam1 = 500; // 비네팅 효과의 범위를 500으로 지정
	}
	else if(App.cameraEffect == 1){
		App.cameraEffect = 0; // 비네팅 효과 끄기
	}
	App.sendUpdated(); // 앱의 Field값이 변경되면 App.sendUpdated()로 변경값을 적용
})
비네팅 효과 범위 500이 적용된 모습

displayRatio

App.displayRatio

화면의 줌을 컨트롤 하는 값 ( 기본 값: 1 )

예제

화면의 줌을 컨트롤 하는 키 만들어보기

// q 키를 누르면 동작하는 함수
// 한 번 누르면 화면의 줌 값이 커지고, 한 번 더 누르면 원래대로 돌아오는 키 함수 
// App.addOnKeyDown 설명
App.addOnKeyDown(81,function(p){
	if(App.displayRatio == 1){
		App.displayRatio = 5;
	}else{
		App.displayRatio = 1;
	}
	App.sendUpdated(); //* 앱의 Field값이 변경되면 App.sendUpdated()로 변경값을 적용
})
displayRatio 값이 5일 때
displayRatio 값이 1일 때

storage

App.storage: String

스페이스 내의 App 데이터의 저장공간 입니다 (스페이스 한정)

예제

Storage 페이지를 참고해주세요

followPlayer

App.followPlayer: Boolean

App의 따라가기 기능 활성화 여부 값 입니다. ( 기본 값 : false )

노멀 앱, 미니게임 앱이 실행 중인 경우 followPlayer 값이 false로 설정되어 ‘따라가기’ 기능이 비활성화됩니다.

예제

따라가기 기능을 끄고 키는 함수 만들어보기

// q 키를 누르면 동작하는 함수
// followPlayer 값을 바꾸는 키 함수
App.addOnKeyDown(81,function(p){
	if(App.followPlayer){
		App.followPlayer = false;
	}else{
		App.followPlayer = true;
	}
	App.sayToAll(`App.followPlayer: ${App.followPlayer}`)
	App.sendUpdated(); //* 앱의 Field값이 변경되면 App.sendUpdated()로 변경값을 적용
})

showName

App.showName: Boolean

플레이어 닉네임 숨김 여부

App.showName 을 false로 설정하면 모든 플레이어의 닉네임이 숨김 처리됩니다.

예제

// q 키를 누르면 동작하는 함수
// showName 값을 바꾸는 키 함수
App.addOnKeyDown(81,function(p){
	if(App.showName){
		App.showName = false;
	}else{
		App.showName = true;
	}
	App.sayToAll(`App.showName: ${App.showName}`)
	App.sendUpdated(); //* 앱의 Field값이 변경되면 App.sendUpdated()로 변경값을 적용
})

appHashID

App.appHashID: String

앱의 HashID를 가져옵니다.

예제

채팅창에앱의 HashID 출력하기

// 플레이어가 입장할 때 동작하는 함수
App.onJoinPlayer.Add(function(player){
	App.sayToAll(`appHashID: ${App.appHashID}`); 
})

enableFreeView

App.enableFreeView

앱이 설치된 맵의 둘러보기 허용 여부를 설정할 수 있습니다.

예제

단축키로 맵 둘러보기 허용 여부 설정하기

// Q를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
	if (App.enableFreeView) {
		App.enableFreeView = false;
	} else {
		App.enableFreeView = true;
	}
	App.sendUpdated();
	player.sendMessage(`App.enableFreeView = ${App.enableFreeView}`, 0x00ffff);
});


부록

스페이스와 맵 이해하기

Storage

App storage는 스페이스 내의 App 데이터의 저장공간 입니다.

App storage에 데이터 저장하기

권장하는 데이터 저장 방식

App.setStorage(string);

App.setStorage 함수는 기존 App storage 데이터 저장 방식을 보완한 데이터 저장 함수입니다.

권장하지 않는 데이터 저장 방식

App.storage = string; App.save();

위 방식은 앱이 같은 스페이스 내 여러 맵에서 실행중인 경우, 데이터를 덮어쓰는 등의 문제가 발생할 수 있어 사용을 권장드리지 않습니다.

App storage 값 읽어오기

App.getStorage(function(){})

App.getStorage 함수는 앱이 실행중인 같은 스페이스 내 다른 맵의 App storage 데이터 변경 여부를 체크하여 같은 데이터를 가지도록 동기화 해주는 함수입니다.

App.getStorage 함수는 비동기 함수이기 때문에 App.getStorage 함수 다음 라인에 App.storage를 사용하는 코드를 작성할 경우 동기화를 보장할 수 없습니다.

App storage 사용 예제

아래 예제코드를 사이드바 앱으로 설치해 같은 스페이스 내 다른 맵에서 Q를 눌러 count 값이 동기화되는지 확인해보세요.


App.onStart.Add(function(){
	if(App.storage == null){
		App.setStorage(JSON.stringify({count: 0}))
	}
})
// Q 키를 누르면 동작하는 함수
App.addOnKeyDown(81,function(player){
	// App.storage를 최신화 한 후 callback 함수를 실행합니다.
	App.getStorage(function () {
		let appStorage = JSON.parse(App.storage);
		appStorage.count += 1;
		App.sayToAll(`count: ${appStorage.count}`)
		// App.setStorage를 사용해 변경내용을 저장합니다.
		App.setStorage(JSON.stringify(appStorage));
	});
	// App.getStorage 함수 다음 라인에 App.storage 코드를 작성할 경우 동기화를 보장할 수 없습니다.
	App.sayToAll(App.storage);
})

Event Listeners

소개

플레이어가 지정된 채팅을 입력하거나, 특정한 오브젝트를 공격할 와 같이 ZEP 스페이스에서 발생하는 특정 상황에 반응하여 동작하는 함수들 입니다.

EventListener가 비정상적으로 많이 추가되는 경우 앱이 종료될 수 있습니다.

onUpdate문 또는 반복적으로 실행되는 문에서 EventListener를 등록하는 것을 지양해주세요.

이름
설명

onSay

플레이어가 채팅을 입력할 때 동작하는 함수입니다.

onPlayerTouched

캐릭터들끼리 충돌할 때 동작하는 함수입니다.

onObjectTouched

캐릭터가 오브젝트와 충돌할 때 동작하는 함수입니다.

onAppObjectTouched

플레이어가 키 값을 가진 오브젝트와 충돌할 때 동작하는 함수입니다.

onUnitAttacked

공격 키(Z)로 다른 캐릭터를 공격할 때 동작하는 함수입니다.

onObjectAttacked

공격 키(Z)로 오브젝트를 공격할 때 동작하는 함수입니다.

onSidebarTouched

플레이어가 사이드바 앱을 클릭(터치)할 때 실행되는 함수입니다.

onTriggerObject

오브젝트와 F 상호작용 시 동작하는 함수입니다.

onAppObjectAttacked

플레이어가 키 값을 가진 오브젝트를 공격(Z키) 할 때 동작하는 함수입니다.

📚 API 설명 및 예제

Event Listener 함수 한 눈에 보기

// 플레이어들이 채팅창에 입력하는 모든 채팅에 대해 호출 되는 이벤트
// !로 시작하는 텍스트는 채팅창에 나오지 않으나, onSay 함수에는 사용 가능
App.onSay.Add(function(player, text) {
});

// 플레이어가 다른 플레이어와 부딪혔을 때 호출 되는 이벤트
App.onPlayerTouched.Add(function(sender, target, x, y){
});

// 플레이어가 오브젝트와 부딪혔을 때 호출 되는 이벤트
App.onObjectTouched.Add(function(sender, x, y, tileID, obj) {  
});

// 플레이어가 키 값을 가진 오브젝트와 부딪혔을 때 호출 되는 이벤트
App.onAppObjectTouched.Add(function(key, sender, x, y){});

// 플레이어가 다른 플레이어를 공격할 때 (Z키) 호출 되는 이벤트
App.onUnitAttacked.Add(function(sender, x, y, target) {
});

// 플레이어가 오브젝트를 공격(Z키)했을 때 호출 되는 이벤트
App.onObjectAttacked.Add(function(sender, x, y){
});

// 플레이어가 사이드바 앱을 클릭(터치)할 때 호출 되는 이벤트
App.onSidebarTouched.Add(function(player){
}); 

// 오브젝트와 F 상호작용 시 동작하는 함수
App.onTriggerObject.Add(function(player, layer, x, y){
});

// 플레이어가 키 값을 가진 오브젝트를 공격할 때 (Z키) 호출 되는 이벤트
App.onAppObjectAttacked.Add(function (sender, x, y, layer, key) {
});

onSay

App.onSay.Add(function(player, text){});

플레이어가 채팅을 입력할 때 동작합니다.

파라미터

이름
타입
설명

player

Player

player 파라미터는 채팅을 입력한 플레이어를 가르킴 player 파라미터의 이름은 임의로 변경 가능

text

String

text는 입력한 채팅 내용을 가르킴 text 파라미터의 이름은 임의로 변경 가능

예제

초성퀴즈 - 채팅으로 정답 맞추는 기능 만들어보기

_answer = "ZEP" // 정답
// 플레이어가 채팅을 칠 때 실행
App.onSay.add(function(player, text) {
    if(_answer == text){
        App.showCenterLabel(player.name + '님 정답!\n정답은 ' + _answer);
    }
});

onPlayerTouched

App.onPlayerTouched.Add(function(sender, target, x, y){});

캐릭터들끼리 충돌할 때 동작합니다.

파라미터

이름
타입
설명

sender

Player

sender는 부딪힌 주체자를 가르킴

target

String

target은 부딪힘을 당한 플레이어를 가르킴

x, y

Number

x, y는 충돌한 x, y 좌표를 가르킴

sender, target, x, y 파라미터의 이름은 임의로 변경 가능

예제

캐릭터끼리 부딪힐 때 메시지 출력해보기

// 플레이어끼리 부딪힐 때 실행
App.onPlayerTouched.Add(function (sender, target, x, y) {
	App.showCenterLabel(
		`${sender.name}님과 ${target.name}님이 좌표: (${x}, ${y}) 에서 부딪혔습니다.`
	);
});

onObjectTouched

App.onObjectTouched.Add(function(sender, x, y, tileID, obj){});

캐릭터가 오브젝트와 충돌 또는 상호작용 할 때 한 번 실행됩니다.

파라미터

이름
타입
설명

sender

Player

sender는 오브젝트와 부딪힌 플레이어를 가르킴

x, y

Number

오브젝트와충돌한 x, y 좌표를 가르킴

tileID

Number

오브젝트의 타일 ID 입니다.

obj

Object

오브젝트 객체

예제

⭐ overlap: true 속성이 없는 오브젝트는 충돌해도 함수가 실행되지 않습니다.

2KB
예제_onObjectTouched.zip
archive
let testObject = App.loadSpritesheet("object.png");
// 사용 가능한 ObjectEffectType
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,
}

App.onStart.Add(function () {
	Map.putObject(5, 5, testObject, { overlap: true });
});

// 플레이어와 오브젝트가 부딪힐 때 실행
App.onObjectTouched.Add(function (sender, x, y, tileID, obj) {
	Map.putObject(x, y, null);
	App.showCenterLabel(
		`${sender.name}님이 좌표: (${x}, ${y}) 에서 오브젝트와 부딪혔습니다.(타입: ${obj.type})`
	);
});

onAppObjectTouched

App.onAppObjectTouched.Add(function(sender, key, x, y){});

️ 캐릭터가 키 값을 가진 오브젝트와 충돌할 때 동작합니다.

파라미터

이름
타입
설명

sender

Player

sender는 오브젝트와 부딪힌 플레이어를 가르킴

key

String

오브젝트의 Key 값

x, y

Number

x, y는 충돌한 x, y 좌표를 가르킴

예제

라벨 출력 예제

⭐ overlap: true 속성이 없는 오브젝트는 충돌해도 함수가 실행되지 않습니다.

29KB
예제_onAppObjectTouched.zip
archive
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],
	8
);

// Q를 누르면 동작 하는 함수
App.addOnKeyDown(81, function (player) {
	App.sayToAll("키 값을 가진 오브젝트 충돌 테스트");
	Map.putObjectWithKey(8, 5, blueman_dance, { overlap: true, key: "blueman" });
});

App.onAppObjectTouched.Add(function (player, key, x, y) {
	App.sayToAll(
		`${player.name}이 키 값이 ${key}인 오브젝트와 ${x},${y}에서 충돌!`
	);
});

onUnitAttacked

App.onUnitAttacked.Add(function(sender, x, y, target){});

플레이어가 공격 키(Z)로 다른 캐릭터를 공격할 때 동작합니다.

파라미터

이름
타입
설명

sender

Player

sender는 공격한 플레이어를 가르킴

x, y

Number

x, y는 공격한 플레이어의 x, y 좌표 값을 가르킴

target

Player

target은 공격 받은 플레이어를 가르킴

sender, x, y, target 파라미터의 이름은 임의로 변경 가능

예제

플레이어를 공격 할 때 메시지 출력해보기

// Z 키로 플레이어를 공격할 때 실행
App.onUnitAttacked.Add(function (sender, x, y, target) {
	App.showCenterLabel(`${sender.name}님이 ${target.name}님을 공격했습니다.`);
	App.sayToAll(`(${x}, ${y})`);
});

onObjectAttacked

App.onObjectAttacked.Add(function(sender, x, y){});

플레이어가 공격 키(Z)로 오브젝트를 공격할 때 동작합니다.

파라미터

이름
타입
설명

sender

Player

sender는 공격한 플레이어를 가르킴

x, y

Number

x, y는 오브젝트의 x, y 좌표 값을 가르킴

sender, x, y 파라미터의 이름은 임의로 변경 가능

예제

오브젝트를 공격할 때 메시지 출력해보기

⭐ overlap: true 속성이 없는 오브젝트는 공격해도 함수가 실행되지 않습니다.

2KB
예제_onObjectAttacked.zip
archive
let testObject = App.loadSpritesheet("object.png");

App.onStart.Add(function () {
	Map.putObject(5, 5, testObject, { overlap: true });
});
// Z 키로 오브젝트를 공격할 때 실행
App.onObjectAttacked.Add(function(sender, x, y){
	App.showCenterLabel(
		`${sender.name}님이 좌표: (${x}, ${y})에 위치 오브젝트를 공격했습니다.`
	);
})

onSidebarTouched

App.onSidebarTouched.Add(function(player){});

플레이어가 사이드바 앱을 클릭(터치) 할 때 동작합니다.

파라미터

이름
타입
설명

player

Player

사이드바 앱을 클릭한 player를 가르킴

예제

사이드바 앱 클릭 시 채팅창 메시지 출력하기.

App.onSidebarTouched.Add(function (player) {
	App.sayToAll(`${player.name}님이 사이드바 앱을 클릭했습니다.`)
});

관련 페이지

사이드바 앱 예제

onTriggerObject

App.onTriggerObject.Add(function(player, layerID, x, y, key){});

오브젝트와 F 상호작용 시 동작하는 함수를 작성할 수 있습니다.

맵에디터로 설치한 오브젝트 또는 스크립트에서 type을 INTERACTION_WITH_ZEPSCRIPTS(21)로 설치한 오브젝트와 상호작용 시 동작합니다.

파라미터

이름
타입
설명

player

Player

오브젝트와 상호작용한 player를 가르킴

layerID

Number

오브젝트가 설치된 레이어 ID 오브젝트인 경우 layerID = 3 상단 오브젝트인 경우 layerID = 5

x, y

Number

상호작용한 오브젝트의 x, y 좌표

key

String

상호작용한 오브젝트의 key 값

예제

오브젝트와 F 상호작용시 메시지 출력하기

2KB
onTriggerObject.zip
archive
let blueman = App.loadSpritesheet("blueman.png");

App.onJoinPlayer.Add(function (player) {
	Map.putObjectWithKey(player.tileX + 1, player.tileY, blueman, {
		type: ObjectEffectType.INTERACTION_WITH_ZEPSCRIPTS,
		impassable: true,
		key: "objectKey",
	});
});


App.onTriggerObject.Add(function (player, layerID, x, y, key) {
	App.sayToAll(`playerName: ${player.name} / layer: ${layerID} / coordinates:(${x}, ${y}) / key: ${key}`);
});

onAppObjectAttacked

App.onAppObjectAttacked.Add(function (sender, x, y, layer, key) {});

플레이어가 공격 키(Z)로 키 값을 가진 오브젝트를 공격할 때 동작합니다.

관련 문서: 오브젝트 npcProperty

파라미터

이름
타입
설명

sender

Player

sender는 공격한 플레이어를 가르킴

x, y

Number

x, y는 오브젝트의 x, y 좌표 값을 가르킴

layer

Number

오브젝트가 설치된 레이어

key

String

공격한 오브젝트의 키 값

예제

키 값을 가진 오브젝트를 공격할 때 메시지 출력해보기

29KB
onAppObjectAttacked.zip
archive

⭐ collide: true 속성이 없는 키 값 오브젝트는 공격해도 함수가 실행되지 않습니다.

App.onAppObjectAttacked.Add(function (sender, x, y, layer, key) {
    App.showCenterLabel(
        `sender: ${sender.name} 
        coordinates: (${x}, ${y})
        layer: ${layer}
        key: ${key}`
    );
});

관련 페이지

사이드바 앱 예제

Callbacks

소개

스크립트 개발자가 지정한 키를 플레이어가 눌렀을 때 또는 스크립트 개발자가 지정한 지점에 도착했을 때 등, 조건을 설정하여 플레이어가 조건을 달성했을 경우 동작하는 함수들 입니다.

이름
설명

runLater

지정한 시간(초) 후 동작하는 함수 입니다.

addOnTileTouched

지정한 x, y 좌표에 플레이어가 도착했을 때 실행되는 함수입니다.

addOnLocationTouched

지정한 ‘지정영역’에 플레이어가 도착했을 때 실행되는 함수입니다.

addOnKeyDown

플레이어가 지정된 키를 눌렀을 때 실행되는 함수 입니다.

setTimeout

지정한 시간(ms) 후 함수를 실행합니다.

setInterval

지정한 시간(ms) 간격으로 함수를 실행합니다.

addMobileButton

모바일 환경에서 커스텀 모바일 버튼을 추가하고, 버튼을 눌렀을 때 동작하는 함수를 지정합니다.

putMobilePunch

모바일 환경에서 펀치 버튼을 추가합니다.

putMobilePunchWithIcon

로드한 이미지로 펀치 버튼을 만들어 추가합니다.

📚 API 설명 및 예제

Callbacks 함수 한 눈에 보기

// time(초) 후에 callback 함수를 실행
App.runLater(callback, time: number)

// 플레이어가 해당 위치의 타일과 부딪혔을 때 실행
App.addOnTileTouched(x: number, y: number, callback)

// 플레이어가 지정한 위치와 부딪혔을 때 실행
App.addOnLocationTouched(name: string, callback)

// 플레이어가 지정된 키를 눌렀을 때 실행
App.addOnKeyDown(keycode : number, callback);

// time(ms) 후에 callback 함수를 실행
setTimeout(callback, time: number)

// time(ms) 후 함수를 실행
setInterval(callback, time: number)

// 모바일 환경에서 커스텀 모바일 버튼을 추가하고, 버튼을 눌렀을 때 동작하는 함수를 지정
App.addMobileButton(anchor: number, posX: number, posY: number, function(player){} )

// 모바일 환경에서 펀치 버튼 추가/제거합니다.
App.putMobilePunch(enable: boolean = true)

// 로드한 이미지로 펀치 버튼을 만들어 추가합니다.
App.putMobilePunchWithIcon(icon: ScriptDynamicResource)

runLater

App.runLater(function(){}, time: number);

time(초) 후에 callback 함수를 실행합니다.

파라미터

이름
타입
설명

time

Number

몇 초 후에 실행 될 지를 정하는 시간 (초)

예제

앱이 시작되고 5초 후 메시지 출력해보기

App.onStart.Add(function () {
	App.runLater(function() {
		App.showCenterLabel("메시지");
	}, 5);
});

addOnTileTouched

App.addOnTileTouched(x: number, y: number, function(player){})

지정한 x, y좌표에 플레이어가 도착할 경우 callback 함수를 실행합니다.

파라미터

이름
타입
설명

x, y

number

지정 할 x, y 좌표

예제

플레이어가 지정 좌표에 도착 했을 때 메시지 출력해보기

// 플레이어가 5, 5 좌표에 도착한 경우
App.addOnTileTouched(5, 5, function (player) {
	App.showCenterLabel(`${player.name}님이 (5, 5) 좌표에 도착!`);
});

addOnLocationTouched

addOnLocationTouched(name: string, function(player){})

플레이어가 맵에디터에서 지정한 ‘지정영역’에 도착했을 때 callback 함수를 실행합니다.

파라미터

이름
타입
설명

name

String

맵 에디터에서 지정한 ‘지정 영역’의 이름

player

Player

지정 영역에 도착한 플레이어를 가르킴 파라미터의 이름은 임의로 지정 가능

예제

플레이어가 지정 영역에 도착했을 때 메시지 출력해보기

// 플레이어가 이름이 "myLocation"인 영역에 도착했을 때 실행
App.addOnLocationTouched("myLocation", function(player){
	App.showCenterLabel(`${player.name}님이 myLocation에 도착했습니다.`)
});

addOnKeyDown

App.addOnKeyDown(keycode : number, function(player){});

플레이어가 지정된 키를 눌렀을 때 callback 함수를 실행합니다.

파라미터

이름
타입
설명

keycode

Number

키에 해당하는 숫자 자바스크립트 키코드 표

player

Player

해당 키를 누른 플레이어를 가르킴 player 파라미터 이름은 임의로 변경 가능

예제

a를 눌렀을 때 메시지 출력해보기 ( a의 키코드: 65 )

// 플레이어가 a를 눌렀을 때 실행
App.addOnKeyDown(65, function(player){
	App.sayToAll(`${player.name}님이 a키를 눌렀습니다.`)
});

setTimeout

setTimeout(function(){}, time: number);

time(ms) 후에 callback 함수를 실행합니다.

파라미터

이름
타입
설명

time

Number

callback 함수 실행 전 대기 시간 (ms)

예제

앱이 시작되고 5초 후 메시지 출력해보기

App.onStart.Add(function () {
	setTimeout(function () {
		App.sayToAll("5초후 메시지 출력");
	}, 5000);
});

setInterval

setInterval(function(){}, time: number);

time(ms) 간격으로 callback 함수를 실행합니다.

파라미터

이름
타입
설명

time

Number

callback 함수 실행 주기 (ms)

예제

앱이 시작되고 1초 간격으로 메시지 출력해보기

let time = 0;
App.onStart.Add(function () {
	setInterval(function () {
		App.sayToAll(`앱 실행 ${++time}초 경과`);
	}, 1000);
});

addMobileButton

App.addMobileButton( anchor: number, posX: number, posY: number, function(player){} )

모바일 환경에서 커스텀 모바일 버튼을 추가하고, 버튼을 눌렀을 때 동작하는 함수를 지정합니다.

모바일버튼의을이미지를 원하는 이미지로 변경 할 수 있습니다.

모바일버튼 이미지 변경하기

파라미터

이름
타입
설명

anchor

Number

모바일 버튼의 위치를 숫자로 입력합니다. TOP = 0, TOP_LEFT = 1, TOP_RIGHT = 2, MIDDLE = 3, MIDDLE_LEFT = 4, MIDDLE_RIGHT = 5, BOTTOM = 6, BOTTOM_LEFT = 7, BOTTOM_RIGHT = 8

posX

Number

모바일 버튼 x 방향 오프셋 수치

posY

Number

모바일 버튼 y 방향 오프셋 수치

player

Player

모바일 버튼을 누른 플레이어를 가르킴

예제

모바일 버튼 추가해보기

예제를 참고해 버튼의 위치를 설정해보세요!
App.onStart.Add(function () {
	// Bottom_Right
	App.addMobileButton(8, 145, 75, function (player) {
		App.sayToAll(`${player.name}, Bottom 버튼A`);
	});
	// Bottom_Right
	App.addMobileButton(8, 145, -20, function (player) {
		App.sayToAll(`${player.name}, Bottom 버튼B`);
	});
	// Top
	App.addMobileButton(0, 0, 400, function (player) {
		App.sayToAll(`${player.name}, TOP 버튼`);
	});
	// Top_Left
	App.addMobileButton(1, 50, 400, function (player) {
		App.sayToAll(`${player.name}, TOP_LEFT 버튼`);
	});
	// Top_right
	App.addMobileButton(2, 50, 400, function (player) {
		App.sayToAll(`${player.name}, TOP_RIGHT 버튼`);
	});
	// Middle
	App.addMobileButton(3, 0, 100, function (player) {
		App.sayToAll(`${player.name}, MIDDLE 버튼`);
	});
	// Middle_left
	App.addMobileButton(4, 50, 100, function (player) {
		App.sayToAll(`${player.name}, MIDDLE LEFT 버튼`);
	});
	// Middle_right
	App.addMobileButton(5, 50, 100, function (player) {
		App.sayToAll(`${player.name}, MIDDLE RIGHT 버튼`);
	});
});

putMobilePunch

App.putMobilePunch(enable: boolean = true)

enable이 true이면 모바일 환경에서 펀치 버튼이 추가됩니다.

파라미터

이름
타입
설명

enable

Boolean

모바일 펀치 버튼 활성화 여부 ( 기본 값 true )

예제

Q 버튼을 눌러 모바일 환경에 펀치 버튼을 추가/제거 해보기

let punchButton = false;
// Q 버튼을 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
	if (!punchButton) {
		punchButton = true;
		App.putMobilePunch();
	} else {
		punchButton = false;
		App.putMobilePunch(false);
	}
});

putMobilePunchWithIcon

App.putMobilePunchWithIcon(icon: ScriptDynamicResource)

로드한 이미지로 펀치 버튼을 만들어 추가합니다.

파라미터

이름
타입
설명

icon

ScriptDynamicResource

App.loadSpriteSheet 함수로 로드한 이미지 리소스

예제

Q 버튼을 눌러 모바일 환경에 로드한 이미지로 펀치 버튼 추가하기

펀치아이콘
const punchIcon = App.loadSpritesheet("punchIcon.png")
// Q 버튼을 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
	App.putMobilePunchWithIcon(punchIcon);
});

부록

자바스크립트 키코드 표

Methods

소개

화면에 UI를 표시, 유저 이동 또는 강퇴, 사운드 재생 등 편리한 기능을 제공하는 함수들 입니다.

Methods 함수는 용도에 따라 UI , User Control, Sound, 통신, 공통 메소드로 나눌 수 있습니다.

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 함수 한 눈에 보기

// 스프라이트 시트 그림 파일을 읽어 객체화
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

App.loadSpritesheet(fileName: string, frameWidth: number, frameHeight: number, anims: array, frameRate: number): ScriptDynamicResource

스프라이트 시트 그림 파일을 읽어 객체화하는 함수입니다.

ScriptDynamicResource에 대한 이해를 돕는 스프라이트시트 이해하기 문서를 확인해보세요!

파라미터

이름
타입
설명

fileName

String

불러올 파일의 이름

frameWidth frameHeight

number

한 프레임의 가로, 세로 픽셀 크기

anims

Array

애니메이션으로 지정할 frame 이미지 번호 배열

frameRate

number

프레임 하나 당 데이터를 표시하는 속도 frameRate: 8 → 1초에 8개의 이미지를 보여줌

예제

페인트맨 - 블루맨 스프라이트 이미지 적용해보기

29KB
예제_loadSpritesheet.zip
archive
// 한 프레임의 사이즈 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

App.showCenterLabel(text: string, color: uint = 0xFFFFFF, bgColor: uint = 0x000000, offset: number = 0, time: number = 3000)

모든 플레이어에게 지정된 위치에 text를 3초간 표시하는 함수입니다.

파라미터

이름
타입
설명

text

String

라벨에 출력할 텍스트

color

Uint

출력할 글씨의 색 (HexCode) 값을 입력하지 않을 경우, 흰색(0xFFFFFF)으로 적용됩니다. ➡️구글 색상 선택 도구

bgColor

Uint

메시지가 출력되는 라벨의 배경색 값을 입력하지 않을 경우, 검은색(0x000000)으로 적용됩니다.

offset

number

offset 값이 클수록 표시되는 위치가 화면 아래쪽 방향으로 가까워집니다. 값을 입력하지 않을 경우, 0으로 지정됩니다.

time

number

라벨 표시 시간 (ms), 기본 값 3000 ( 3초 )

예제

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

App.onJoinPlayer.Add(function(player){
	App.showCenterLabel(`${player.name}님이 입장하셨습니다.`, 0x000000, 0xFFFF00, 200, 2000); // 노란색 배경, 검정색 글씨로 표시하기
});

showCustomLabel

App.showCustomLabel(text: string, color: number = 0xFFFFFF, bgColor: number = 0x000000, offset: number = 0, width = 100, opacity = 0.6, time: number = 3000, option: object = null);

모든 플레이어에게 지정된 위치에 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"

예제

커스텀 라벨 예제 코드 페이지를 참고해주세요

sayToAll

App.sayToAll(text: string, color: uint = 0xFFFFFF)

채팅창에 text 내용을 출력합니다.

파라미터

이름
타입
설명

text

String

채팅창에 출력할 텍스트

color

Uint

출력할 글씨의 색을 지정합니다. (HexCode) 값을 입력하지 않을 경우, 흰색(0xFFFFFF)으로 적용됩니다. ➡️구글 색상 선택 도구

예제

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

// 플레이어가 입장할 때 실행
App.onJoinPlayer.Add(function (player) {
	App.sayToAll(`[info]${player.name} has entered.`, 0x00ffff); // 하늘색으로 표시하기
});

sayToStaffs

App.sayToStaffs(text: string, color: uint = 0xFFFFFF)

Staff이상 권한의 유저 채팅창에 text 내용을 출력합니다.

파라미터

이름
타입
설명

text

String

채팅창에 출력할 텍스트

color

Uint

출력할 글씨의 색을 지정합니다. (HexCode) 값을 입력하지 않을 경우, 흰색(0xFFFFFF)으로 적용됩니다. ➡️구글 색상 선택 도구

예제

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

// 플레이어가 입장할 때 실행
App.onJoinPlayer.Add(function (player) {
	App.sayToStaffs(`[Staff] ${player.name} has entered.`, 0x00ffff); // 하늘색으로 표시하기
});

showWidget

App.showWidget(fileName: string, align: string, width: number, height: number): ScriptWidget

모든 플레이어에게 지정된 align의 위치에 해당 html파일을 위젯으로 불러오는 함수입니다.

파라미터

이름
타입
설명

fileName

String

불러올 파일의 이름

align

String

위젯을 표시할 위치 ’popup’, ‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’

width height

number

위젯을 표시할 영역의 가로, 세로 크기(px)

예제

초성퀴즈 위젯 따라해보기

1KB
예제_showWidget.zip
archive

let _widget = null;
// 플레이어가 입장할 때 실행
App.onJoinPlayer.Add(function (player) {
	_widget = App.showWidget("widget.html", "top", 200, 300); // 화면 상단, 200x300 영역에 위젯을 보여줌
	_widget.sendMessage({
		timer: 15,
		answer: "ㅅㅍㅋ",
	});
});

showYoutubeWidget

App.showYoutubeWidget(link: string, align: string, width: number, height: number): ScriptWidget

링크에 해당하는 Youtube 컨텐츠를 위젯으로 불러옵니다.

파라미터

이름
타입
설명

link

String

Youtube 컨텐츠 url

align

String

위젯을 표시할 위치 ’popup’, ‘sidebar’, ‘top’, ‘topleft’, ‘topright’, ‘middle’, ‘middleleft’, ‘middleright’, ‘bottom’, ‘bottomleft’, ‘bottomright’

width height

number

위젯을 표시할 영역의 가로, 세로 크기(px)

예제

Youtube 위젯 표시해보기

// 플레이어가 입장할 때 실행
App.onJoinPlayer.Add(function (player) {
	App.showYoutubeWidget("https://www.youtube.com/watch?v=SXnMGIR8cjY","top",600,500);
});

🔗Control Methods

Control 함수 한 눈에 보기

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

App.spawnPlayer(playeID: string, tileX: number, tileY: number)

playerID 에 해당하는 플레이어를 tileX, tileY 좌표로 이동시키는 함수입니다.

파라미터

이름
타입
설명

playerID

String

플레이어의 ID 값

tileX tileY

number

플레이어를 이동시킬 x, y 좌표 값

예제

입장하는 플레이어를 지정 좌표로 이동시키기

// 플레이어가 입장할 때 실행
App.onJoinPlayer.Add(function (player) {
	App.spawnPlayer(player.id, 5, 5); // 플레이어를 5,5 위치로 이동시키기
});

kickPlayer

App.kickPlayer(playerID: string)

playerID 에 해당하는 플레이어를 추방하는 함수입니다.

파라미터

이름
타입
설명

playerID

String

플레이어의 ID 값

예제

강퇴 명령어 만들어보기

⛔ 강퇴 당한 참가자는 24시간 동안 해당 스페이스에 접속하지 못합니다.

// 플레이어가 채팅을 입력할 때 실행
// 명령어 형식 '!강퇴 닉네임'
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

App.forceDestroy();

미니게임 앱을 강제 종료하는 함수입니다.

예제

미니게임 앱을 강제 종료시키기

// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
	App.forceDestroy();
});

clearChat

App.clearChat();

모든 채팅 내용을 삭제하는 함수입니다.

예제

Q를 눌러 채팅 내용 지우기

// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
	App.clearChat();
});
채팅이 삭제되는 모습

getPlayerByID

App.getPlayerByID(playerID: string);

id 에 해당하는 플레이어를 반환하는 함수입니다.

예제

App.getPlayerByID 사용 방법

// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81, function (player) {
	const myPlayer = App.getPlayerByID(player.id);
});

🔉 Sound Methods

Sound 함수 한 눈에 보기

// 모든 플레이어에게 사운드를 재생
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

App.playSound(fileName: string, loop: boolean = false, overlap: boolean = false)

모든 플레이어에게 사운드를 재생하는 함수입니다.

파라미터

이름
타입
설명

fileName

String

불러올 파일의 이름

loop

boolean

true: 반복 재생 false: 1회 재생

overlap

boolean

사운드 오버랩(겹침) 재생 가능 여부

예제

플레이어가 입장할 때 입장음 적용해보기 ( 파일 )

20KB
join.mp3
//플레이어가 입장할 때 실행
App.onJoinPlayer.Add(function (player) {
	App.playSound("join.mp3", false, true);
});

playSoundLink

App.playSoundLink(link: string, loop: boolean = false)

모든 플레이어에게 사운드를 재생하는 함수입니다.

💡 올바른 링크를 입력했는데 재생이 되지 않는 경우

CORS 정책을 위반한 경우일 가능성이 높습니다. CORS 정책을 맞출 수 없는 경우에는 playSoundLink 대신 음악 파일을 업로드 하여 playSound 함수를 사용하는 것을 권장드립니다.

파라미터

이름
타입
설명

link

String

사운드 url

loop

boolean

true: 반복 재생 false: 1회 재생

예제

플레이어가 입장할 때 입장음 적용해보기 ( 사운드 url )

// 플레이어가 입장할 때 실행
App.onJoinPlayer.Add(function (player) {
	App.playSoundLink("https://zep.us/assets/sounds/ring.mp3",false);
});

stopSound

App.stopSound();

재생되고 있는 사운드를 멈추는 함수입니다.

파라미터

  • 없음

예제

q를 누르면 사운드가 멈추는 기능 만들어보기

// q 키를 누르면 동작하는 함수
App.addOnKeyDown(81,function(p){
	App.stopSound();
})

changeAttackSound

App.changeAttackSound(fileName:string)

찌르기(Z키) 공격 효과음을 변경하는 함수입니다.

파라미터

이름
타입
설명

fileName

String

적용할 사운드 파일명

예제

changeAttackSound 사용 방법

App.onStart.Add(function(){
	App.changeAttackSound("attack.mp3");
})

📡 통신 Methods

통신 함수 한 눈에 보기

// 해당 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

App.httpGet(url: string, headers: object, function(res: string){})

http get 요청을 보내는 함수입니다.

파라미터

이름
타입
설명

url

String

요청을 보낼 주소

headers

Object

요청 헤더

res

String

요청에 대한 응답

예제

한국어 별명 생성기 API를 이용해 입장하는 플레이어의 닉네임을 바꿔보기

// 플레이어가 입장할 때 동작하는 함수
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

App.httpPost(url: string, headers: object, body: object, function(res: string))

Form-Data 형태의 http post 요청을 보내는 함수 입니다.

파라미터

이름
타입
설명

url

String

요청을 보낼 주소

headers

Object

요청 헤더, 요청 헤더가 없으면 { } 를 입력.

body

Object

요청 바디 ( Form data )

res

String

요청에 대한 응답

예제

앱에서 보낸 헤더와 데이터를 응답으로 받아 채팅창에 출력해보기.

예제와 같이 key, value 값을 string 형태로 작성해야하며, 요청 서버에서 폼데이터를 받아 처리가 가능해야합니다.

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

App.httpPostJson(url: string, headers: object, body: object, function(res: string))

Json 형태의 http post 요청을 보내는 함수 입니다.

파라미터

이름
타입
설명

url

String

요청을 보낼 주소

headers

Object

요청 헤더, 요청 헤더가 없으면 { } 를 입력.

body

Object

요청 바디 ( JSON data )

res

String

요청에 대한 응답

예제

앱에서 보낸 데이터를 응답으로 받아 채팅창에 출력해보기.

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

공통 함수 한 눈에 보기

// App 관련 필드값이 변경되면 변경값을 적용함
App.sendUpdated()

sendUpdated

App.sendUpdated()

App 관련 필드 값이 변경되면 변경 값을 적용하는 함수입니다.

파라미터

  • 없음